Skip to main content

MCP Server

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 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 toUse
Give an agent the Payments AI toolsMCP server — the rest of this page
Build and test without touching live dataSandbox MCP server — Sandbox MCP URL
Let an agent answer questions from these docssearch_payments_ai_docs, shipped with the MCP server
Teach an agent our conventions before it writes codeSkill — Agent discovery
Feed these docs to an agent that cannot speak MCPllms.txt and raw Markdown — Agent discovery
Script merchants and products from a terminal or CICLI — Payments AI CLI
Call the API yourself, without an agentPublic 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.

jsonOAuth
{
  "mcpServers": {
    "payments-ai": {
      "url": "https://mor.payments.ai/api/mcp"
    }
  }
}

Connect with OAuth​

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

Setup prompt

Not sure which client you are in, or using one that is not listed? Paste this prompt and let the agent work out its own install path.

Prompt
Install the Payments AI MCP server in this environment using OAuth. Do not ask me for a pai_mcp_* token.
Server name: payments-ai
URL: https://mor.payments.ai/api/mcp
Transport: Streamable HTTP
1. Detect which client you are (Cursor, Claude Code, Codex, Gemini CLI, Antigravity, VS Code, Grok, ChatGPT, or other).
2. Install with the matching command when a CLI exists:
- Claude Code: claude mcp add --transport http payments-ai https://mor.payments.ai/api/mcp
- Codex: codex mcp add payments-ai --url https://mor.payments.ai/api/mcp && codex mcp login payments-ai
- Gemini CLI: gemini mcp add --transport http payments-ai https://mor.payments.ai/api/mcp
- Antigravity: merge this into ~/.gemini/config/mcp_config.json (project: .agents/mcp_config.json). Use serverUrl, not url or httpUrl:
{ "mcpServers": { "payments-ai": { "serverUrl": "https://mor.payments.ai/api/mcp" } } }
- VS Code: code --add-mcp '{"name":"payments-ai","type":"http","url":"https://mor.payments.ai/api/mcp"}'
- Grok CLI: grok mcp add --transport http payments-ai https://mor.payments.ai/api/mcp
- Cursor: merge this into ~/.cursor/mcp.json and, if a project is open, .cursor/mcp.json:
{ "mcpServers": { "payments-ai": { "url": "https://mor.payments.ai/api/mcp" } } }
Then tell me to click Connect in Settings → MCP, or run: agent mcp login payments-ai
3. If no CLI matches, write the client config file and tell me the path.
4. After install, call whoami if tools are available. If not, tell me to reload MCP and approve OAuth, then retry.
5. Quote userId, host and endpoint from whoami. A 401 means not connected (quote its message); any tool error means connected but the call failed.
Manual configuration

Add to your client’s MCP config, then restart Any agent.

json
{
"mcpServers": {
"payments-ai": {
"url": "https://mor.payments.ai/api/mcp"
}
}
}

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, 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 has the steps and the calls; the agent auth guide has every error and polling rule.

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

ClientPath with no terminal
Any agentDevice grant, then your client's own way of sending a bearer header. If it cannot send one, use the connect page on a device with a browser.
CursorDevice grant, then headers in ~/.cursor/mcp.json.
Claude CodeDevice 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): no terminal, 90-day credential. Fallback: a 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.
GrokThe connector's browser sign-in (Grok Connectors). No shell, so no device grant; a header path is not verified. Fallback: the connect page on a device with a browser.
ChatGPTThe app's browser sign-in (ChatGPT developer mode). No shell, so no device grant; a header path is not verified. Fallback: the connect page on a device with a browser.
CodexDevice 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 CLIDevice grant, then gemini mcp add --transport http --header "Authorization: Bearer <token>" payments-ai <url>.
AntigravityDevice grant, then headers next to serverUrl in mcp_config.json.
VS CodeDevice 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.

ResultWhat it means
SuccessConnected 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 401Not connected. The agent quotes the 401 message, which says how to recover (for example, how to renew an expired connection).
Any tool errorConnected, 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. 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).

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:

Prompt
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.

{
"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 #.

{
"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​

ToolWhat it does
whoamiaccountName, userId, scopes, host, endpoint, merchantIds, credentialExpiresAt, credentialExpiresInSeconds, credentialExpiryWarning (verify the connection; any valid token)
get_my_merchantOwned merchants (first call after verify)
create_merchant_accountDual-provision live + sandbox merchant
get_merchant_activation_statusActivation status: pending, verification_pending, active
go_livePromote to live; a repeat call returns the current status
search_payments_ai_docsSearch PAI Managed documentation
create_productCreate product + pricing plans (sandbox until go-live)
create_orderPayable multi-item or caller-priced checkout (checkout:write)
update_productMerge-update a product's name, description or status (product:create)
update_planMerge-update a plan's name, description, price, billing period or free trial (product:create)
list_productsList products and pricing plans for a merchant
list_transactionsLook up a merchant's transactions (transaction:read)
get_transactionOne transaction's details and line items
get_product_image_upload_urlMint presigned POST for product image
confirm_product_imageAttach uploaded product image
get_checkout_customizationRead checkout theme and branding
update_checkout_customizationMerge-update checkout branding
set_checkout_logoMint → 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 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.
  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 (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.

{
"mcpServers": {
"payments-ai": {
"type": "streamableHttp",
"url": "https://mor.payments.ai/api/mcp",
"headers": {
"Authorization": "Bearer pai_mcp_<your-token>"
}
}
}
}
ClientWhere
CursorSettings → 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 CodeRun 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.

codeMeaningFix
missing_tokenNo Authorization: Bearer headerMissing MCP token
invalid_tokenUnknown, revoked or malformed tokenInvalid MCP token
token_expiredThe 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
token_validation_unavailableThe token could not be checked right now; retry, do not generate a new oneError catalog

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). 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.

{
"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:

FileURL
Skillhttps://doc.mor.payments.ai/SKILL.md
Authhttps://doc.mor.payments.ai/auth.md
Concise indexhttps://doc.mor.payments.ai/llms.txt
Full indexhttps://doc.mor.payments.ai/llms-full.txt
Agent Skills indexhttps://doc.mor.payments.ai/.well-known/agent-skills/index.json
MCP Server Cardhttps://mor.payments.ai/.well-known/mcp/server-card.json
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 (npx skills add paymentsai/Payments-AI-skills).

Privacy and support​

Next steps​