# MCP Server

> Connect Cursor, Claude, Grok, ChatGPT, Codex, Gemini CLI, Antigravity, or VS Code to Payments AI in under 2 minutes. OAuth first.

Connect Cursor, Claude, Grok, ChatGPT, Codex, Gemini CLI, Antigravity, VS Code, or any MCP client to Payments AI. Your agent can provision merchants, create products, open checkout, and search these docs without leaving the chat.

Stuck connecting? The [connect page](/connect) shows server status, one path for your client, and the check that proves it works.

## Pick a surface

Payments AI exposes more than one surface to an agent. Start here, then follow the one that matches the job.

| You want to                                          | Use                                                               |
| ---------------------------------------------------- | ----------------------------------------------------------------- |
| Give an agent the Payments AI tools                  | **MCP server** — the rest of this page                            |
| Build and test without touching live data            | **Sandbox MCP server** — [Sandbox MCP URL](#sandbox-mcp-url)      |
| Let an agent answer questions from these docs        | `search_payments_ai_docs`, shipped with the MCP server            |
| Teach an agent our conventions before it writes code | **Skill** — [Agent discovery](#agent-discovery)                   |
| Feed these docs to an agent that cannot speak MCP    | `llms.txt` and raw Markdown — [Agent discovery](#agent-discovery) |
| Script merchants and products from a terminal or CI  | **CLI** — [Payments AI CLI](/cli)                                 |
| Call the API yourself, without an agent              | **Public API** — [Public API](/public-api)                        |

**OAuth is the fastest path.** No User MCP Key to copy. Your client opens a browser or prints a sign-in URL (in Claude Code run `/mcp` → Authenticate), you sign in, approve scopes, and tools appear.

<McpSetupWalkthrough />

## Connect with OAuth

Pick your client. Every path ends the same way: approve scopes in the browser, then your agent has the tools.

<McpClientSetup />

### Claude Connectors (no terminal)

In Claude on the web or Claude Desktop, open **Settings → Connectors** and click **Add custom connector**. Paste `https://mor.payments.ai/api/mcp` (or `https://sandbox.mor.payments.ai/api/mcp` for Sandbox), sign in to Payments AI, and click **Approve**. Then ask Claude: "Show me my Payments AI merchants."

### Grok Connectors (no terminal)

In Grok, open **[Connectors](https://grok.com/connectors)**, click **New Connector** → **Custom**, and paste `https://mor.payments.ai/api/mcp`. Sign in on the dashboard, approve scopes, and return to Grok.

### ChatGPT (developer mode)

In ChatGPT, enable **Developer mode**, then add a custom MCP app with the same URL and complete OAuth.

### No terminal or browser

If nothing in your setup can open a browser or answer a terminal prompt, the OAuth steps above cannot finish. The agent runs the OAuth device authorization grant itself over HTTP, shows you a short code, and you approve it on any device with a browser. The [connect page](/connect#connect-without-a-terminal) has the steps and the calls; the [agent auth guide](https://doc.mor.payments.ai/auth.md) has every error and polling rule.

Your client then takes the resulting `pai_mcp_*` token as an `Authorization: Bearer` header:

| Client                    | Path with no terminal                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Any agent**             | Device grant, then your client's own way of sending a bearer header. If it cannot send one, use the [connect page](/connect) on a device with a browser.                                                                                                                                                                                                                  |
| **Cursor**                | Device grant, then `headers` in `~/.cursor/mcp.json`.                                                                                                                                                                                                                                                                                                                     |
| **Claude Code**           | Device grant, then `claude mcp add --transport http payments-ai <url> --header "Authorization: Bearer <token>"`. `/mcp` → Authenticate and `claude mcp login` need a terminal.                                                                                                                                                                                            |
| **Claude (web, Desktop)** | No shell, so no device grant. Use the connector's own browser sign-in ([Claude Connectors](#claude-connectors-no-terminal)): no terminal, 90-day credential. Fallback: a [User MCP Key](#manual-user-mcp-key) under Request headers, which lasts at most 7 days. On Team and Enterprise the Owner sets the headers, so every member then acts as the key owner's account. |
| **Grok**                  | The connector's browser sign-in ([Grok Connectors](#grok-connectors-no-terminal)). No shell, so no device grant; a header path is not verified. Fallback: the [connect page](/connect) on a device with a browser.                                                                                                                                                        |
| **ChatGPT**               | The app's browser sign-in ([ChatGPT developer mode](#chatgpt-developer-mode)). No shell, so no device grant; a header path is not verified. Fallback: the [connect page](/connect) on a device with a browser.                                                                                                                                                            |
| **Codex**                 | Device grant, then `codex mcp add payments-ai --url <url> --bearer-token-env-var PAI_MCP_TOKEN`. Codex reads the variable from its environment at startup: set it in the environment Codex starts from (shell profile or launch environment) and restart Codex.                                                                                                           |
| **Gemini CLI**            | Device grant, then `gemini mcp add --transport http --header "Authorization: Bearer <token>" payments-ai <url>`.                                                                                                                                                                                                                                                          |
| **Antigravity**           | Device grant, then `headers` next to `serverUrl` in `mcp_config.json`.                                                                                                                                                                                                                                                                                                    |
| **VS Code**               | Device grant, then `headers` in `.vscode/mcp.json`, with the token entered through an input.                                                                                                                                                                                                                                                                              |

### Verify the connection

Do not rely on the client's "connected" label. Ask your agent: "Call whoami and quote accountName, userId, host and endpoint." `whoami` needs no scope, so it works for every valid token.

| Result         | What it means                                                                                                                                                                                                                                                                                                                                                   |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Success        | Connected as `accountName` (the business name of the account you are connected to, never an email; `null` when no label is known), `userId`, on `host` (`sandbox` or `live`) at `endpoint`. Confirm `accountName` together with `host` (live or sandbox) and check it is your own business account. `scopes: null` means every scope except `transaction:read`. |
| HTTP 401       | Not connected. The agent quotes the 401 `message`, which says how to recover (for example, how to renew an expired connection).                                                                                                                                                                                                                                 |
| Any tool error | Connected, but the server could not prove the connection. Quote the error; do not reconnect.                                                                                                                                                                                                                                                                    |

`whoami` also returns `merchantIds` (the merchants this credential is a member of), `credentialExpiresAt` (when it stops working, ISO 8601 UTC) and `credentialExpiresInSeconds`. In the last 14 days of an OAuth connection it adds `credentialExpiryWarning` with the link to re-approve. Every tool result carries the same warning under `_meta["ai.payments/credentialExpiryWarning"]` and in a closing text block; only `whoami` has a `credentialExpiryWarning` field. The link opens the [connect page](/connect). Tokens you generate in the dashboard never warn. An agent that sees the warning tells you and shares the link; if you connected with the device grant, run it again and replace the `Authorization` header instead ([steps](/connect#connect-without-a-terminal)).

`host` is the kind of MCP URL your client is connected to: `live` for the main MCP URL, `sandbox` for the sandbox-only URL. It is not the environment and not your merchant's deployment. On a `live` host, a merchant that has not gone live still shows `deployment: "sandbox"` in `get_my_merchant`.

## Try it

Copy this into your agent after the server is connected:

<CodeExampleTabs
  wrap
  examples={[
    {
      label: 'Prompt',
      language: 'text',
      code: 'Show me my Payments AI merchants. If none, create a sandbox merchant named Quickstart Demo, then create a $19.99/month product and give me the checkout URL.',
    },
  ]}
/>

You should see tool names (`get_my_merchant`, `create_merchant_account`, `create_product`) before each call runs.

**Create a merchant**

> Create a sandbox merchant named "Quickstart Demo" with my email \<your email\>.

Use your own real, deliverable email address — `create_merchant_account` rejects example, disposable, and other reserved or undeliverable addresses. Phone is optional. If you add one, use your own mobile number, starting with `+` and your country code, with no spaces or dashes (for example, `+14155552671` is a US number, but not yours): after go-live the identity-verification link is sent to it by SMS. Without a phone, the link goes by email.

The tool returns `{ "merchantId": "<uuid>", "existing": false }` for a new merchant. `existing: true` means this account already owns a merchant and the tool returned that one instead of creating a second. Either way, use that `merchantId` for the steps below.

**Create a product and plan, then open checkout**

> Create a sandbox product called "Starter Plan" with a $19.99/month recurring plan for merchant \<merchantId\>, then give me the hosted checkout URL to open in a browser.

The agent sends `create_product` arguments shaped like this. A plan's `type` is `recurring`, `one-time`, or `free-access`; `amount` is in major units (`19.99` is $19.99, not cents); `currency` is lowercase; the billing interval is `billingPeriod` (`week`, `month`, `year`) times `periodLength`.

```json
{
  "merchantId": "<merchantId>",
  "name": "Starter Plan",
  "plans": [
    {
      "name": "Monthly",
      "type": "recurring",
      "amount": 19.99,
      "currency": "usd",
      "billingPeriod": "month",
      "periodLength": 1
    }
  ]
}
```

**Checkout branding**

> Show my checkout customization for merchant \<merchantId\> and update the button color to #2563EB.

The agent sends `update_checkout_customization` arguments shaped like this. The fields to change go inside a nested `customization` object, never at the top level; fields you leave out keep their current value. Colors are 6-digit hex with the leading `#`.

```json
{
  "merchantId": "<merchantId>",
  "customization": {
    "buttonColor": "#2563EB"
  }
}
```

Use sandbox merchant data for exploration. Mutating tools target sandbox until go-live.

**Test card (Sandbox):** pay a sandbox checkout link with `4242 4242 4242 4242`, any future expiry, and any CVC. To test a refused payment, use `4000 0000 0000 0002`. Test cards never work on Live: live checkout links take real cards only.

## Available tools

| Tool                             | What it does                                                                                                                                                                                  |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `whoami`                         | `accountName`, `userId`, `scopes`, `host`, `endpoint`, `merchantIds`, `credentialExpiresAt`, `credentialExpiresInSeconds`, `credentialExpiryWarning` (verify the connection; any valid token) |
| `get_my_merchant`                | Owned merchants (first call after verify)                                                                                                                                                     |
| `create_merchant_account`        | Dual-provision live + sandbox merchant                                                                                                                                                        |
| `get_merchant_activation_status` | Activation status: `pending`, `verification_pending`, `active`                                                                                                                                |
| `go_live`                        | Promote to live; a repeat call returns the current status                                                                                                                                     |
| `search_payments_ai_docs`        | Search PAI Managed documentation                                                                                                                                                              |
| `create_product`                 | Create product + pricing plans (sandbox until go-live)                                                                                                                                        |
| `create_order`                   | Payable multi-item or caller-priced checkout (`checkout:write`)                                                                                                                               |
| `update_product`                 | Merge-update a product's name, description or status (`product:create`)                                                                                                                       |
| `update_plan`                    | Merge-update a plan's name, description, price, billing period or free trial (`product:create`)                                                                                               |
| `list_products`                  | List products and pricing plans for a merchant                                                                                                                                                |
| `list_transactions`              | Look up a merchant's transactions (`transaction:read`)                                                                                                                                        |
| `get_transaction`                | One transaction's details and line items                                                                                                                                                      |
| `get_product_image_upload_url`   | Mint presigned POST for product image                                                                                                                                                         |
| `confirm_product_image`          | Attach uploaded product image                                                                                                                                                                 |
| `get_checkout_customization`     | Read checkout theme and branding                                                                                                                                                              |
| `update_checkout_customization`  | Merge-update checkout branding                                                                                                                                                                |
| `set_checkout_logo`              | Mint → PUT → confirm checkout logo                                                                                                                                                            |

The `checkoutUrl` returned by `create_product` and `list_products` is ready to open — use it verbatim. It already targets the right environment (sandbox URLs carry `?isSandbox=true`; live URLs have no query param).

### Transaction lookup

`list_transactions` answers "did this customer pay?": filter by `customerEmail`, `orderId` or `orderNumber`, `status`, `dateFrom` / `dateTo` and `deployment` (`sandbox` or `live`; omitted means where the merchant's checkouts run now). `get_transaction` returns one transaction's details: the same fields plus the refunded amount and the order's line items.

- Only `succeeded` means paid. `pending` is not yet confirmed and must never be reported as paid. `partially_refunded` means part of the amount was refunded.
- Each transaction returns customer email, first and last name, and card brand and last 4 only.
- Both tools need the `transaction:read` scope. It is never granted by default or by a token whose `scopes` is `null`, so existing connections must re-authorize with it and tick it on the consent screen, where it always starts unticked (or mint a token with it ticked).
- There is no refund tool. Send the merchant to the transaction's `transactionDetailsUrl` and tell them to select its deployment (Sandbox or Live) in the dashboard.

### Going live

`go_live` promotes the merchant to live routing only — it does **not** copy products, plans, or checkout customization. The live side starts with an **empty catalog**: call `create_product` again for every product and plan you want live, and re-apply any branding with `update_checkout_customization` on the same `merchantId` (after `go_live` it writes to live). `set_checkout_logo` always writes to sandbox, so the live logo cannot be set over MCP yet: upload it in the dashboard checkout builder (https://mor.payments.ai/checkout-builder) with Live selected. A sandbox checkout link stays sandbox-only forever (it always carries `?isSandbox=true`) and never turns into a live link — read the new `checkoutUrl` from `create_product` or `list_products` on live instead of reusing the one you already showed.

The **Sandbox Deployment** needs no identity verification: products, checkout links and test transactions all work while KYC/KYB status stays `not_started`. On the **Live Deployment**, the merchant can process up to $5,000 in card transactions before identity verification is required — but payouts (withdrawing funds) always require completed KYC/KYB, independent of that $5,000 threshold, before a payout method can be added and before the first live payout.

## Sandbox MCP URL

For staging agents (build and test only in sandbox), connect to the **sandbox** MCP endpoint instead of the live URL:

`https://sandbox.mor.payments.ai/api/mcp`

Generate a `pai_mcp_*` token in **Developer Tools → MCP Tokens** while the dashboard is on **Sandbox**, or complete OAuth through the sandbox MCP server (its authorization server redirects to the dashboard with `deployment=sandbox` so consent calls the sandbox API). Live MCP tokens and live OAuth consent do not work on this URL. Merchant, product, and checkout writes stay on the sandbox schema. The `go_live` tool is not available here — promote merchants on the [live MCP URL](https://mor.payments.ai/api/mcp) when you are ready.

The client snippets above default to the **live** URL; swap in the Sandbox URL to build and test.

## Manual: User MCP Key

Use this only if your client cannot do OAuth, or you can't sign in through your client's browser window.

1. Sign in to the [Payments AI dashboard](https://mor.payments.ai).
2. Open **Developer Tools → MCP Tokens** and pick the **Sandbox** or **Live** tab.
3. Click **Generate MCP Token**, enter a name and duration, choose the tool scopes the token may use, then click **Generate Token**. Copy your token (`pai_mcp_*`). It is shown only once.
4. Paste the config below into your client (`~/.cursor/mcp.json`, Claude Desktop config, or equivalent), or run the Claude Code command.

A token belongs to the tab it was generated on. A **Sandbox** token works only with the [sandbox MCP URL](#sandbox-mcp-url) (`https://sandbox.mor.payments.ai/api/mcp`); a **Live** token works only with the live MCP URL (`https://mor.payments.ai/api/mcp`). The success dialog in the dashboard shows the matching URL. The examples below use the live URL.

<McpConfigExamples />

| Client             | Where                                                                                                                                |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Cursor**         | **Settings → MCP** → edit config (or `~/.cursor/mcp.json`) → paste under `mcpServers`                                                |
| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |
| **Claude Code**    | Run the **Claude Code** command above                                                                                                |
| **Grok CLI**       | `~/.grok/config.toml`                                                                                                                |

Restart your client after saving.

### When the MCP endpoint answers 401

The response body carries a machine-readable `code` and a `docUrl` to its Fix-It page. The `WWW-Authenticate` header keeps the OAuth discovery challenge.

| `code`                         | Meaning                                                                                                                                                                                                      | Fix                                        |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ |
| `missing_token`                | No `Authorization: Bearer` header                                                                                                                                                                            | [Missing MCP token](/errors/missing-token) |
| `invalid_token`                | Unknown, revoked or malformed token                                                                                                                                                                          | [Invalid MCP token](/errors/invalid-token) |
| `token_expired`                | The credential expired: a token's duration passed, or the 90-day OAuth connection ran out; re-approve it in your client (OAuth), run the device grant again (no terminal), or generate a new token (MCP key) | [MCP token expired](/errors/token-expired) |
| `token_validation_unavailable` | The token could not be checked right now; retry, do not generate a new one                                                                                                                                   | [Error catalog](/errors)                   |

### When a stored credential keeps getting 401

Some clients keep an OAuth credential saved without an `issuer` stamp (upstream MCP issue SEP-2352). That stored credential wins over every new authorization, so signing in again changes nothing.

**Signature:** your client shows Payments AI as connected or holds a stored credential, but every MCP call answers `401`, and running OAuth again does not fix it.

**Recovery:**

1. Clear the stored Payments AI credential in your client, then reconnect and approve scopes in the browser again. In Claude Code, run `claude mcp remove payments-ai` and add the server again with the OAuth command above. In other clients, sign out of the server or remove it from the MCP settings, then add it again.
2. If your client offers no way to clear the stored credential, generate a new token in **Developer Tools → MCP Tokens** and connect with the `Authorization: Bearer` header instead (see [Manual: User MCP Key](#manual-user-mcp-key)). A bearer token does not use the client's OAuth credential store.

**Report it:** agents report this case with the code `stale_credential_no_issuer`, so the upstream problem can be sized. Send `POST https://mor.payments.ai/api/mcp/connect-diagnostics` (or the sandbox MCP URL plus `/connect-diagnostics`) with `Content-Type: application/json` and only these fields. The endpoint needs no token and always answers `204` with an empty body. Never put a token in the report: a body containing a `pai_` token is discarded whole, and any field not listed here is dropped.

```json
{
  "client": "claude-code",
  "stage": "false_connected_state",
  "code": "stale_credential_no_issuer",
  "mcpServerVersion": "1.4.0",
  "clientVersion": "2.0.14",
  "deployment": "live",
  "reportedAt": "2026-10-12T09:30:00Z"
}
```

`client` is one of `claude-code`, `claude`, `cursor`, `codex`, `grok`, `chatgpt`, `gemini`, `vscode` or `other`. `mcpServerVersion` is the `serverInfo.version` the MCP server returned on initialize, and both versions are plain semver.

## Agent discovery

Agents can fetch these without a key:

| File               | URL                                                                                                                                |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| Skill              | [https://doc.mor.payments.ai/SKILL.md](https://doc.mor.payments.ai/SKILL.md)                                                       |
| Auth               | [https://doc.mor.payments.ai/auth.md](https://doc.mor.payments.ai/auth.md)                                                         |
| Concise index      | [https://doc.mor.payments.ai/llms.txt](https://doc.mor.payments.ai/llms.txt)                                                       |
| Full index         | [https://doc.mor.payments.ai/llms-full.txt](https://doc.mor.payments.ai/llms-full.txt)                                             |
| Agent Skills index | [https://doc.mor.payments.ai/.well-known/agent-skills/index.json](https://doc.mor.payments.ai/.well-known/agent-skills/index.json) |
| MCP Server Card    | [https://mor.payments.ai/.well-known/mcp/server-card.json](https://mor.payments.ai/.well-known/mcp/server-card.json)               |

```bash
mkdir -p "$HOME/.payments-ai" && curl --fail --show-error --location \
  --output "$HOME/.payments-ai/SKILL.md" \
  "https://doc.mor.payments.ai/SKILL.md"
```

Host plugins still install from [paymentsai/Payments-AI-skills](https://github.com/paymentsai/Payments-AI-skills) (`npx skills add paymentsai/Payments-AI-skills`).

## Privacy and support

- **Privacy policy:** [payments.ai/mor/privacy-policy](https://payments.ai/mor/privacy-policy/)
- **Product & technical support:** [merchants@payments.ai](mailto:merchants@payments.ai) (see [Getting help](/getting-help))

## Next steps

- [Quickstart](/quickstart): first sandbox API call
- [Webhooks](/webhooks): signed events sent to your server
- [API Reference](/api): OpenAPI contracts
