MCP server

The Model Context Protocol server gives a coding agent the same API you use, as typed tools. It is deliberately sandbox-only: it refuses a production key and exits, so an agent cannot move real money through it.

Get your test keys

Create a free account, then open Developers > API keys in the dashboard. Sandbox keys start with sk_test_ and are shown once, so store the key the moment it appears. Sandbox keys never touch a real provider and never move real money.

Get your test keys Already have an account?

What it exposes

One tool per API operation, named after the operation, plus a scenario guide that explains what each sandbox scenario key does. POST /checkout/initiate is deliberately not a tool: it is a public endpoint whose environment comes from the payment link rather than from this server's sandbox key, so a production link id would start a real payment prompt on a real phone.

whoamiproviderspricingcollectionspayoutsrefundsbalancesbalance_transactionseventswebhook_endpointstest_fundtest_advance

Configure your client

Not published yet

@capay/mcp is not on npm today. The install command shows the name it will ship under. Until the release lands, request early access through Support in your dashboard.

Point your MCP client at the package and pass a sandbox key in the environment. The server reads CAPAY_API_KEY and nothing else.

Claude Desktop

{
  "mcpServers": {
    "capay": {
      "command": "npx",
      "args": ["-y", "@capay/mcp"],
      "env": { "CAPAY_API_KEY": "sk_test_XXXXXXXXXXXX" }
    }
  }
}

Restart the client after editing its configuration. If the tools do not appear, run the command yourself in a terminal: it prints the reason it refused to start.

Sandbox keys only

This is a hard rule, not a setting. The server checks the key prefix at startup and exits on anything that is not sk_test_. There is no flag to override it.

shell

$ CAPAY_API_KEY=sk_live_XXXXXXXXXXXX npx -y @capay/mcp
error: production keys are refused. The MCP server runs with sk_test_ keys only. Exiting.

Give the agent the narrowest key

Create a dedicated sandbox key for the agent, tick only the scopes it needs, and set an IP allowlist and a daily cap on it in the dashboard under Developers > API keys: https://dashboard.capayglobal.com/developers/api-keys

The status rules apply to an agent exactly as they apply to your code: an in-flight status is not a failure. Tools return the resource as the API returns it, so an agent that reasons about status must poll or wait for the webhook rather than conclude a payment failed.

Agent keys

A production agent key (dashboard: Developers > API keys > Agent key) is still refused by this server: the designed opt-in (accepted only when GET /v1/whoami answers key.kind agent, live_money_enabled true and paused false) is specified but not implemented in this version. Sandbox agent keys work like any sandbox key; the API's own agent_* refusals surface verbatim in the tool result. See Keys for AI agents.