MCP server

Payman in Claude, ChatGPT, Grok or Cursor, against your own accounts.

Ask your AI assistant about your money and it answers from your real accounts. Balances, recent activity, payments.

There is no credential to paste into the chat. You sign in on Payman’s own pages, your bank credential goes on Payman’s own pages, and nothing moves without your approval there.

Building a product for your customers? You want the SDK instead. One app key, your own UI, forUser(id) per customer.

Set it up

Use the hosted Streamable HTTP MCP server:

https://paygent-cloud-server-production.up.railway.app/mcp

This is the working endpoint on the current Railway staging deployment. The hostname includes production because of Railway’s service naming; it does not mean a separate production launch. Do not use api.payman.ai or api.paygent.payman.ai for this integration.

Claude Code

claude mcp add --transport http payman https://paygent-cloud-server-production.up.railway.app/mcp

Run /mcp inside Claude Code, select payman, and authenticate. If you already added a server called payman with an old URL, remove that entry with claude mcp remove payman before adding it again. This replaces the client’s saved configuration, so authenticate again afterwards.

Or put this in your project’s .mcp.json:

{
  "mcpServers": {
    "payman": {
      "type": "http",
      "url": "https://paygent-cloud-server-production.up.railway.app/mcp"
    }
  }
}

See Claude Code’s MCP setup guide for configuration scopes and authentication.

Other MCP clients

Add the URL above as a remote MCP server using Streamable HTTP and OAuth. No app key or client secret is required. The client discovers the authorization server and dynamically registers itself.

Setting	Value
MCP URL	https://paygent-cloud-server-production.up.railway.app/mcp
Transport	Streamable HTTP
Authentication	OAuth with PKCE (S256)
Scope	interact

For hosted chat products, use their custom connector settings. For a custom harness, use an MCP client with OAuth support and keep its authorization callback listener running until sign-in completes.

The hosted endpoint requires no npm installation. The local @paymanai/connect-mcp package is not currently available on the public npm registry; use hosted MCP instead of an npx configuration.

If sign-in returns to localhost

A callback such as http://localhost:54507/callback belongs to the MCP client running on your computer. It is not the API address. Start authentication from the MCP client, keep that process running, and complete sign-in in a browser on the same computer. A client running on a remote machine needs its own supported callback or forwarding setup.

If the callback cannot connect, restart authentication from the client. Codes are short-lived and single-use; reopening an old callback URL does not restart sign-in. Never paste the callback code into chat or change its host to Railway.

If a harness calls the HTTP API directly

Use https://paygent-cloud-server-production.up.railway.app as the base URL. For an existing SDK installation, set PAYMAN_BASE_URL to that origin and restart the process. Keep your existing app key and grant credentials; changing the URL does not reconnect or delete banks.

GET /health returns 200 without credentials. An unauthenticated request to /mcp returns 401 with OAuth discovery information; that is the sign-in challenge, not an outage.

Then ask

what’s my balance?

The first money question opens Payman’s consent page. Sign in, pick what to connect, and the answer arrives in the same turn. You never ask twice.

Your accounts

Tick every account you have already connected. One approval can hand a host your bank, your card platform and your wallet together. An account that still needs setting up is connected on its own, because it has its own credentials or its own trip to the bank, and that does not fit in a list.

Add one later from Connected apps in your Payman account, with Add a provider on the host’s row. Nothing changes on the host’s side: the connection it already holds reaches one more account on its next request.

Expect a question once a connection reaches more than one account. An instruction that does not say which account it means comes back naming your options, rather than being carried out against a guess. Say which one, and the follow-ups stay there until you say otherwise.

What it can do

Tool	For
payman_money_task	The action itself. Ask in plain language.
payman_approval_status	Did that payment go through yet?
payman_connection_status	Connected? To what? Nothing about your money.
payman_connect, payman_disconnect	Desktop only. Hosted chats connect from their own connector settings.

These are the default money-task tools. What your accounts can do differs by provider. Structured data uses a separate scope and the read tools below.

Structured records for your own agent

On an environment running the financial-data release with structured reads enabled, request OAuth scope financial_data:read and reauthorize. A read-only grant exposes payman_read_data and payman_read_result, alongside payman_connection_status, and omits money and approval tools. Request interact financial_data:read if both permissions are needed.

The financial-data guide shows connection discovery, account selection, typed transaction reads, polling, and native Plaid sync. Hosted MCP input uses deploymentId. Changing the requested scope requires new consent; asking for raw records in chat cannot upgrade an existing grant.

The read tools advertise optional intent by default. Include the known intent.purpose, optionally a shared taskId and caller-reported requestedBy label, for record keeping. Omit it or use null when unknown; no extra user question is needed. Job responses return the saved intent, or null, for their 24-hour lifetime. Compatible runtimes also save Studio traces for each provider-page attempt under the read job’s session, using separate execution retention and the agent’s trace storage settings. See recording intent for longer-term storage and retry rules.

For clients that cannot select hosted OAuth scopes, build the local stdio package from the matching SDK release:

npm ci
npm run build --workspace @paymanai/connect --workspace @paymanai/connect-mcp

Point your MCP host at that build:

{
  "mcpServers": {
    "payman-data": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/payman-connect/packages/connect-mcp/dist/bin.js"],
      "env": {
        "PAYMAN_BASE_URL": "http://localhost:8891",
        "PAYMAN_SCOPES": "financial_data:read"
      }
    }
  }
}

Replace the paths and API origin for your enabled environment. This defaults to the sandbox app. Set PAYMAN_ENVIRONMENT=live when connecting real institutions. Restart the process and call payman_connect. Local discovery is payman_data_connections and local read input uses connectionId; hosted MCP uses payman_connection_status and deploymentId. The other read operations and result pagination are the same. Node 22.5 or newer is required.

When money moves

It stops, every time.

1. The operation freezes

   A one-time code is emailed to you.
2. You get a link

   To Payman’s approval page. Open it yourself.
3. You approve there

   Then say so in the chat, or ask for the approval status.

Payman then finishes the frozen operation, never a rebuilt one.

No assistant can ask you for that code, and Payman refuses it from anyone but you. An assistant that asks for it is wrong.

Details

Why it needs no key

A secret shipped to consumers is not a secret. It would be one shared credential for every install.

So both ways in authenticate as public clients, using OAuth 2.1 with PKCE, the same mechanism as a mobile banking app. A fresh random verifier is minted per authorization and never leaves the client, so an intercepted code cannot be redeemed.

The desktop server ships a published client id. A hosted chat registers its own on first contact. Either way, every connection still passes the consent page you approve.

Whose name you see on the consent page

Your host’s. “Claude wants to act on your behalf”, not a generic Payman label. Claude, ChatGPT, Cursor and VS Code are recognised by name; anything else shows as “An AI assistant”.

Because they are separate clients, connecting Claude no longer disconnects ChatGPT. Two installs of the same host still replace each other.

The name is a label, not a proof. What you can rely on is where you are standing: consent and approval happen on Payman’s own site, behind your own sign-in, with the code in your own inbox. Approve a connection only when you just asked for one.

Where links appear

A link in a tool result is something a model can later reconstruct, plausibly and wrongly. So links go wherever your host can show them properly:

Your host	You see
Supports link prompts	The host shows the link itself
Desktop, no link prompt	The page simply opens
Neither	The exact URL in the reply, to hand over character for character

Open the link yourself. Never accept a retyped one. If the wait runs out, the connection or approval still lands: say so and ask again.

Desktop options

Nothing is required. These apply to @paymanai/connect-mcp only.

Flag	Env	Default
--live	PAYMAN_ENVIRONMENT=live	sandbox
--app-key	PAYMAN_APP_KEY	none, public client
--client-id	PAYMAN_CLIENT_ID	picked from the host
--base-url	PAYMAN_BASE_URL	production
--callback-port	PAYMAN_MCP_CALLBACK_PORT	first free of 8899 to 8903
--callback-path	PAYMAN_MCP_CALLBACK_PATH	/payman/callback
--data-dir	PAYMAN_MCP_DATA_DIR	~/.payman/connect-mcp
--user-id	PAYMAN_MCP_USER_ID	a stable local id
--no-browser	PAYMAN_MCP_NO_BROWSER=1	browser allowed
--print-redirect-uri		prints every registered URI, exits
-h, --help		prints usage, exits

Ports 8899 to 8903 are registered, and the server takes the first one free, so several assistants on one machine do not fight. A port outside that set is refused unless you registered it yourself.

--app-key switches to your own registered Connect app instead. It cannot be combined with the public client: a client that has a secret must use it.

What it will not do

It will not	Because
Run a payment twice	One request runs the action at most once, and a replay completes the approved ticket rather than paying again
Hold your approval code	It happens on Payman’s page, in your session, with a code emailed to you. Nothing here can carry it
Claim a payment landed unconfirmed	An unconfirmed outcome comes back unretryable, because a retry there risks paying twice
Start the same task twice	If your host stops waiting and retries, the repeat joins the run already in flight and gets its answer