Integration

MCP server

The AgentPay MCP server exposes five tools over the Model Context Protocol stdio transport. Install it in any MCP-compatible runtime and your agent gains the ability to create, list, inspect, and close virtual cards.

Install

Add one block to your client's MCP config. Three clients are tested; most others follow the same pattern.

// macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
// Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "agentpay": {
      "command": "npx",
      "args": ["-y", "@agentpay/mcp-server"],
      "env": {
        "AGENTPAY_API_KEY": "sk_test_...",
        "AGENTPAY_API_URL": "https://agentpay-mvp.vercel.app/v1"
      }
    }
  }
}

Restart your client. You should see five AgentPay tools appear in the tool list.

Tools

Tool	REST equivalent	Description
create_card	POST /v1/cards	Create a virtual card. Args: amount_cents (required), agent_id, purpose.
list_cards	GET /v1/cards	List cards. Args: status, agent_id, limit.
get_card	GET /v1/cards/:id	Get card detail including PAN/CVV reveal data. Args: id.
close_card	POST /v1/cards/:id/close	Close a card and release the hold. Args: id.
check_balance	GET /v1/balance	Get spend summary: held amount, open cards, pending approvals.

How errors reach the user

When our API returns a typed error (like setup_required), the MCP server surfaces the full JSON error body to the agent verbatim as a tool error. The agent sees the message and details.setup_url fields and can relay them to the user. The canonical pattern:

User: "Buy me a domain on Cloudflare."
Agent: calls create_card({ amount_cents: 2000, agent_id: "claude-desktop" })
Tool error: {"code":"setup_required","message":"...","details":{"setup_url":"..."}}
Agent replies: "AgentPay isn't set up yet — open https://app.agentpay.dev/setup
  and finish onboarding, then I'll retry."

Troubleshooting

Tools don't appear — restart the client fully (not just reload). Check AGENTPAY_API_KEY is set. Run npx -y @agentpay/mcp-server manually to see startup errors.
All calls return 401 — the API key was revoked or deleted. Create a new one at /api-keys.
setup_required despite completing setup — your session user is different from the user that owns the API key. They must be the same. Sign in and check the dashboard shows the expected email.