Connect Breeze to your AI assistant (MCP)

The Breeze MCP server lets your AI coding assistant answer questions about the Breeze API using our official documentation — so you can find the right endpoint, understand a field, and scaffold your integration without leaving your editor.

You'll need: an MCP-compatible AI client (e.g. Claude Code, Claude Desktop, Cursor, or any tool that supports MCP).

What is MCP?

Model Context Protocol (MCP) is an open standard that lets AI applications connect to external tools and data. The Breeze docs MCP server exposes our public documentation and API reference to your assistant, so it can:

• Search the docs and pull the relevant guide or reference page into context
• Browse the API — list endpoints, inspect a specific request/response, or search by keyword
• Ground its answers in the current spec instead of guessing

Out of the box — with no API key configured — it's read-only: your assistant can browse the public docs and API reference, but it has no access to your Breeze account or live data. You can optionally add a key to let it make live API calls on your behalf — see Use it to call endpoints below.

What you can ask

Once it's connected, ask your assistant things like:

• "How do I create a payment?"
• "What fields does the create-customer request require?"
• "Show me a curl example for creating a payout page."
• "Which currencies are supported for payouts?"

Option 1 — Add it with one command

From your project directory, run this before starting your AI client in the same directory:

npx add-mcp "https://docs.breeze.com/mcp"

Then start your client — the Breeze docs server will be available.

Option 2 — Add it with the config file

Edit your MCP client's configuration (for many clients this is an .mcp.json file in your project, or the client's MCP settings):

{
  "mcpServers": {
    "breeze-public-docs": {
      "type": "http",
      "url": "https://docs.breeze.com/mcp"
    }
  }
}

Save, then restart your client so it picks up the new server.

Verify it's connected

Ask your assistant: "What Breeze tools do you have available?" — you should see the Breeze documentation server listed. If it isn't, restart your client and confirm the config above was saved in the right place.

Use it to call endpoints

Beyond answering questions, the server's execute-request tool can run live API calls for you. To authenticate them, add your API key to the same config as an Authorization header — the MCP forwards it to Breeze on every request, so it's applied automatically and never has to go into a chat.

These are real requests against your account: execute-request can create and modify resources (payments, refunds, payout pages), not just read them. Start with a sandbox key so your assistant can't touch live money while you're setting things up.

Breeze uses Basic authentication (your API key as the username, empty password), so the header value is Basic followed by the base64 of "<your-key>:". Put the encoded key in an environment variable first, so it stays out of any file:

export BREEZE_AUTH="$(printf '<your-key>:' | base64)"

Then attach it when you add the server — both forms reference ${BREEZE_AUTH} (Claude Code expands it from your environment at runtime), so the secret never lands in the config:

With one command — single-quote the header so your shell doesn't expand ${BREEZE_AUTH}:

npx add-mcp "https://docs.breeze.com/mcp" \
  --name breeze-public-docs \
  --header 'Authorization: Basic ${BREEZE_AUTH}'

Or in the config file:

{
  "mcpServers": {
    "breeze-public-docs": {
      "type": "http",
      "url": "https://docs.breeze.com/mcp",
      "headers": { "Authorization": "Basic ${BREEZE_AUTH}" }
    }
  }
}

Heads-up on ${BREEZE_AUTH}: expanding environment variables in MCP config is a client feature, not something the MCP server does. Claude Code replaces ${BREEZE_AUTH} at runtime; clients that don't expand env vars in their config will send the literal text ${BREEZE_AUTH} and auth will fail. On those, put the base64-encoded value directly in the header instead — just note the secret then lives in the config file.

Grab a key from the merchant dashboard under Developers → API Keys → Generate new API Key. Start in sandbox (sk_test_… keys, with ?livemode=false on requests); the same setup works in production — swap in your sk_live_… key when you're ready. See API Fundamentals for full auth details.

Tip: You can also just hand the key to your assistant in the request itself (e.g. "use sk_test_…, create a $10 payment page"). That works too, but the key lands in your chat history — the config header above is the recommended way.