Skip to main content

Connect your agent to Payments AI

No account needed to read this page. Follow it top to bottom: status first, then one way to connect, then one check.

Server status​

Checking… Asking the MCP server at https://mor.payments.ai/api/mcp whether it answers.

The status reads the server card, the public document the MCP server answers at /.well-known/mcp/server-card.json on its own host. Degraded means the problem is on our side: wait before changing your setup. Unreachable means this browser got no answer at all, which can be your network as well as our server.

Connect​

Pick your client. You get one way to connect and one fallback if it does not work.

Primary: Any agent

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.

If that does not work

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

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

Verify the connection​

Do not trust "added" or "connected" in your client: it only means the server is registered. Ask your agent:

Call whoami on the Payments AI MCP server and show me exactly what it returns.

whoami takes no arguments and needs no scope, so every valid credential can call it. It proves the connection without depending on what you granted.

  • Connected: whoami returns your accountName, your userId, your scopes, the host and the endpoint. accountName is the business name of the account you are connected to, never an email: confirm it with host (live or sandbox) and check it is your own business account. null means no label is known. host is live or sandbox and names the MCP URL you connected to, not a merchant. endpoint is that MCP URL: check it is the one you meant. scopes: null means every scope except transaction:read. It also returns merchantIds, credentialExpiresAt and credentialExpiresInSeconds; in the last 14 days of an OAuth connection it adds a credentialExpiryWarning with the link to re-approve.
  • Not connected: the tool is missing, or the call fails with 401. Reload MCP in your client, then repeat the check. The 401 codes and their fixes are listed under When the MCP endpoint answers 401; token_expired means the credential ran out, and the fix depends on how you connected: browser or OAuth client, re-approve it in the client; device grant (no terminal), run the device grant again and replace the Authorization header (Connect without a terminal); MCP key, generate a new key under Developer Tools → MCP Tokens. If your client cannot finish the browser sign-in at all, generate a token in the dashboard under Developer Tools → MCP Tokens and follow Manual: User MCP Key, or see Connect without a terminal.
  • Connected, but a tool is denied: the connection works and a scope is missing. get_my_merchant, for example, needs merchant:read. Re-approve with that scope instead of reconnecting.

Connect without a terminal​

Use this only when nothing in your setup can open a browser or answer a terminal prompt: a headless agent, CI, a container, an SSH session without a TTY. The steps above stay the way to connect everywhere else.

The agent runs an OAuth device authorization (RFC 8628) over plain HTTP and shows you a short code. You approve it on any device with a browser, such as your phone. Your MCP client never opens a browser itself: the agent hands it the resulting token as an Authorization: Bearer header.

  1. Register a device-only client. POST /v1/oauth/register with grant_types: ["urn:ietf:params:oauth:grant-type:device_code"] and no redirect_uris. A device-only client cannot use /authorize.
  2. Start the authorization. POST /v1/oauth/device_authorization with the client_id and the MCP URL as resource. The answer carries user_code, verification_uri, expires_in (30 minutes) and interval (5 seconds).
  3. You approve. The agent shows you user_code and verification_uri exactly as returned. Open the address and type the code. If you are not signed in, sign in or sign up first: the page keeps the code and pre-fills it afterwards, but you still press Continue, and only then do the scopes appear. Tick the scopes you want to grant. Write scopes start unticked. The page marks the client as an unverified application; approve only if you started this connection. Deny ends it.
  4. The agent polls. POST /v1/oauth/token with grant_type=urn:ietf:params:oauth:grant-type:device_code, every interval seconds, until it gets an access_token.
Device grant
API=https://mor.payments.ai/api
# 1. Register a device-only client once. Keep the client_id it returns.
curl -sS -X POST "$API/v1/oauth/register" \
-H 'Content-Type: application/json' \
-d '{"client_name":"My agent","grant_types":["urn:ietf:params:oauth:grant-type:device_code"]}'
# 2. Start the authorization. Show user_code and verification_uri to the person.
curl -sS -X POST "$API/v1/oauth/device_authorization" \
-d client_id="$CLIENT_ID" \
--data-urlencode resource="https://mor.payments.ai/api/mcp"
# 3. Poll every `interval` seconds until you get an access_token or a final error.
curl -sS -X POST "$API/v1/oauth/token" \
-d grant_type=urn:ietf:params:oauth:grant-type:device_code \
-d device_code="$DEVICE_CODE" \
-d client_id="$CLIENT_ID" \
--data-urlencode resource="https://mor.payments.ai/api/mcp"

For Sandbox, use https://sandbox.mor.payments.ai/api as API and https://sandbox.mor.payments.ai/api/mcp as resource.

What the poll can answer, as an RFC 6749 body { "error", "error_description" } with status 400:

errorWhat the agent does
authorization_pendingYou have not approved yet. Keep polling at the same interval.
slow_downPolling too fast. Add 5 seconds to the interval for this and every later poll.
access_deniedYou pressed Deny. Stop and tell you so.
expired_tokenThe 30 minutes passed. Start again at step 2.
invalid_grantThe code is unknown, already used, or belongs to another client. Start again at step 2.

device_authorization answers 429 temporarily_unavailable with Retry-After: 60 when too many authorizations are waiting: the agent backs off and tries again later instead of looping. The token it receives is the same pai_mcp_* credential OAuth issues, valid for 90 days. The agent then calls whoami as above. When the credential is about to expire (whoami warns) or has expired (token_expired), run these steps again and replace the Authorization header: the client never ran OAuth, so there is nothing to re-approve in it.

The page allows 5 code attempts per account every 15 minutes, a correct one included. If a code is rejected, check it against the one the agent shows, or have the agent start again.

Your client decides what it can do with that token. Find it below.

Any agent

Run the device authorization grant yourself over HTTP, then give the token to your client as an Authorization: Bearer header in whatever way it supports. If it cannot send a custom header, say so and send the person to this page on a device with a browser.

Any agent
{
"mcpServers": {
"payments-ai": {
"type": "streamableHttp",
"url": "https://mor.payments.ai/api/mcp",
"headers": {
"Authorization": "Bearer pai_mcp_<your-token>"
}
}
}
}

Cursor

Cursor reads headers for a remote server. Run the device grant over HTTP, then write the token into the same file.

Cursor
{
"mcpServers": {
"payments-ai": {
"url": "https://mor.payments.ai/api/mcp",
"headers": {
"Authorization": "Bearer pai_mcp_<your-token>"
}
}
}
}

Claude Code

/mcp → Authenticate and claude mcp login need an interactive terminal. Run the device grant over HTTP instead, then add the server with the token as a header.

Claude Code
claude mcp add --transport http payments-ai https://mor.payments.ai/api/mcp --header "Authorization: Bearer pai_mcp_<your-token>"

Claude

Claude on the web and Desktop has no shell, so the device grant is not available here, and none is needed: the connector's own browser sign-in above needs no terminal and gives a 90-day credential. Fallback: add the custom connector and, under Request headers, the line below with a User MCP Key from Developer Tools → MCP Tokens. That key 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.

Claude
Authorization: Bearer pai_mcp_<your-token>

Grok

Use the connector's browser sign-in described above: Grok runs in the browser and needs no terminal. The device grant does not apply (no shell) and a header setup for Grok is not verified. Fallback: open the connect page on a device with a browser and connect there.

ChatGPT

Use the app's browser sign-in described above: ChatGPT runs in the browser and needs no terminal. The device grant does not apply (no shell) and a bearer header setup for developer-mode apps is not verified. Fallback: open the connect page on a device with a browser and connect there.

Codex

codex mcp login opens a browser. Run the device grant over HTTP, put the token in an environment variable and point Codex at it: Codex sends it as Authorization: Bearer and never writes it to the config file. Codex reads the variable from its environment at startup, so set it in the environment Codex starts from (shell profile or launch environment) and restart Codex.

Codex
# Set PAI_MCP_TOKEN in the environment Codex starts from (shell profile or launch environment), then restart Codex.
export PAI_MCP_TOKEN=pai_mcp_<your-token>
codex mcp add payments-ai --url https://mor.payments.ai/api/mcp --bearer-token-env-var PAI_MCP_TOKEN

Gemini CLI

Run the device grant over HTTP, then add the server with the token as a header. The same headers field works in ~/.gemini/settings.json.

Gemini CLI
gemini mcp add --transport http --header "Authorization: Bearer pai_mcp_<your-token>" payments-ai https://mor.payments.ai/api/mcp

Antigravity

Run the device grant over HTTP, then add headers next to serverUrl.

Antigravity
{
"mcpServers": {
"payments-ai": {
"serverUrl": "https://mor.payments.ai/api/mcp",
"headers": {
"Authorization": "Bearer pai_mcp_<your-token>"
}
}
}
}

VS Code

Run the device grant over HTTP, then add headers to the server. VS Code asks for the token once through the input and stores it securely, so it never sits in the file.

VS Code
{
"inputs": [
{
"type": "promptString",
"id": "pai-mcp-token",
"description": "Payments AI MCP token",
"password": true
}
],
"servers": {
"payments-ai": {
"type": "http",
"url": "https://mor.payments.ai/api/mcp",
"headers": {
"Authorization": "Bearer ${input:pai-mcp-token}"
}
}
}
}

Open this page on your phone​

Scan the code to continue on another device, or type the address.

Open this page on another device, for example your phone:

https://doc.mor.payments.ai/connect

Still stuck? Write to merchants@payments.ai (see Getting help).