MCP Server

Use AgentPay through any MCP client

AgentPay ships an official Model Context Protocol server. Drop it into Claude Desktop, Cursor, Continue, or any MCP-compatible host and your agent gets three new tools that exercise the full AgentPay policy engine — same gates, same anomaly detection, same audit trail as our REST API.

npm: @agentpay-run/mcp-server Source on GitHub

Install in Claude Desktop

Open ~/Library/Application Support/Claude/claude_desktop_config.json (Settings → Developer → Edit Config). Add the agentpay server block:

json

{
  "mcpServers": {
    "agentpay": {
      "command": "npx",
      "args": ["-y", "@agentpay-run/mcp-server"],
      "env": {
        "AGENTPAY_API_KEY": "ap_live_..."
      }
    }
  }
}

Restart Claude Desktop. The MCP indicator at the bottom right of the chat should show agentpay with three tools available.

Install in Cursor

Cursor reads MCP servers from ~/.cursor/mcp.json. Same shape:

json

{
  "mcpServers": {
    "agentpay": {
      "command": "npx",
      "args": ["-y", "@agentpay-run/mcp-server"],
      "env": {
        "AGENTPAY_API_KEY": "ap_live_..."
      }
    }
  }
}

Install programmatically

For your own MCP host (Node, Python, anything that spawns subprocesses):

bash

AGENTPAY_API_KEY=ap_live_... npx -y @agentpay-run/mcp-server

The server speaks MCP over stdio. Pipe a JSON-RPC tools/list request to confirm:

bash

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | AGENTPAY_API_KEY=ap_live_... npx -y @agentpay-run/mcp-server

Tool reference

Three tools. All take their auth from the env-var key.

chargeIssue a payment against your wallet.

parameters

name	type	required	description
`vendor`	string	yes	Vendor identifier. Domain form preferred ('openai.com').
`amount_cents`	integer	yes	Amount in USD cents. 1200 = $12.00.
`idempotency_key`	string	no	Prevents double-charging on retries.
`metadata`	object	no	Free-form tagging stored on the transaction.

example response

json

{
  "transaction_id": 4197,
  "status": "approved",
  "policy_matched": "vendor_allowlist",
  "remaining_budget_cents": 348800,
  "anomalies_flagged": 0
}

Note: status='denied' is a normal response, not an error — the policy engine blocked the charge but the wallet wasn't affected. The denial_reason field tells you which policy fired.

get_walletRead-only wallet snapshot. Use before a charge to reason about budget.

example response

json

{
  "wallet_id": "wal_...",
  "name": "research-agent",
  "is_active": true,
  "budget_limit_cents": 500000,
  "spent_cents": 152000,
  "remaining_budget_cents": 348000,
  "per_transaction_limit_cents": 5000,
  "vendor_whitelist": ["openai.com", "anthropic.com"]
}

Note: Same scope as the API key: read-only keys can call this; full-scope keys can also call charge.

get_quotaAccount tier + remaining quota for the day. Use to back off before a 429.

example response

json

{
  "tier": "team",
  "wallets_used": 3,
  "wallets_cap": null,
  "wallets_remaining": null,
  "charges_today": 47,
  "charges_cap": null,
  "charges_remaining": null,
  "audit_retention_days": 30,
  "charges_at_cap": false,
  "wallets_at_cap": false
}

Note: Caps are null on tiers with no limit (Team and above). charges_at_cap is the most useful field for decision-making.

list_transactionsList recent transactions for the wallet, newest first.

parameters

name	type	required	description
`limit`	integer	no	Max rows to return (1-100). Defaults to 20.
`status`	string	no	Filter: 'all' \| 'approved' \| 'denied'. Defaults to 'all'.
`since`	string	no	ISO 8601 timestamp. Only return transactions created after this time.

example response

json

{
  "wallet_id": "wal_...",
  "count": 3,
  "transactions": [
    {
      "transaction_id": 4197,
      "status": "approved",
      "policy_matched": "vendor_allowlist",
      "denial_reason": null,
      "vendor": "openai.com",
      "amount_cents": 1200,
      "created_at": "2026-05-08T13:42:11.000Z"
    },
    {
      "transaction_id": 4196,
      "status": "denied",
      "policy_matched": "vendor_allowlist",
      "denial_reason": "vendor not in allowlist",
      "vendor": "sketchy-vendor.io",
      "amount_cents": 5000,
      "created_at": "2026-05-08T13:39:02.000Z"
    }
  ]
}

Note: Use the 'since' parameter for incremental syncing — pass the most recent created_at you've seen and you'll only get newer transactions.

Configuration

Two env vars. Only the first is required.

env var	required	default	notes
AGENTPAY_API_KEY	yes	—	Wallet API key. `ap_test_` for dev, `ap_live_` for production wallets.
AGENTPAY_BASE_URL	no	https://agentpay.run	Override for self-hosted or local dev.

Security

The wallet API key is the only secret. It's wallet-scoped — even if compromised, the blast radius is bounded by the policy on that wallet (per-tx cap, monthly budget, vendor allowlist).
The MCP server is stateless. Every tool call re-queries AgentPay; nothing is cached locally.
For production agents, use ap_live_ keys with strict per-tx caps and a vendor allowlist. Treat them like API tokens — rotate from the dashboard if exposed.
Read-only keys (scope="read_only", Team tier and above) can only call get_wallet and get_quota. Use these for agents that need to inspect state but not spend.

Versioning

The MCP server follows semver. Breaking changes only land on major bumps. Latest version + changelog: see the npm page.

Need an API key?

Get started free →Read the API docs