Claude MCP + Payments: A Complete Integration Guide

The Model Context Protocol gave AI agents a standardized way to call external tools. AgentCard built its payment MCP server on top of MCP specifically because of this: your agent asks for a tool, the MCP server executes it against the AgentCard API, and structured results come back. No credentials in prompts. No custom parsing. A defined contract between agent and payment infrastructure.

This guide covers the AgentCard payment MCP server in depth — what the tools do and exactly what they return, how to choose between stdio and HTTP transport for your use case, the complete config for both Claude Desktop and Cursor, and a walkthrough of an autonomous Claude purchasing session from first tool call to payment record.

What MCP Is and Why It Matters for Payments

MCP (Model Context Protocol) is an open protocol, developed by Anthropic, that defines how AI models and agents communicate with external capability providers. An MCP server exposes a set of named tools with typed input and output schemas. An MCP client — Claude Desktop, Cursor, or a custom agent — discovers these tools, calls them during inference, and receives structured results.

For payments, this architecture has several properties that make it significantly safer than alternatives:

• Credentials stay out of the context window. The agent never sees your API key. It calls a tool; the MCP server (which holds the key) calls the AgentCard API on its behalf.
• Tool calls are auditable. Every tool invocation is logged. You can see exactly when an agent called get_card_details, for which card, and in which session.
• Schema enforcement. The input schema for each tool defines what parameters are required and what types are accepted. The MCP server validates inputs before they reach the API, preventing malformed requests.
• Decoupled from the agent's intelligence. Changing your card issuance logic or adding new tools does not require changing your agent's system prompt or training. You update the MCP server; the agent discovers the new tools automatically.

The alternative — embedding card credentials in environment variables or system prompts — leaks sensitive data into logs, model context, and conversation history. MCP eliminates this risk by design. The full protocol specification is available at modelcontextprotocol.io.

The Four AgentCard MCP Tools

The AgentCard MCP server exposes exactly four tools. Together they cover the full lifecycle of an agent payment session: discovery, balance verification, credential retrieval, and audit logging.

Tool 1: list_cards

Returns all virtual debit cards in your account.

{
  "name": "list_cards",
  "description": "List all your AgentCard virtual cards",
  "inputSchema": {
    "type": "object",
    "properties": {}
  }
}

No input parameters are required. The response is an array of card objects:

[
  {
    "id": "card_abc123",
    "last4": "7823",
    "balance": 50.00,
    "status": "active",
    "label": "research-agent",
    "created_at": "2026-01-06T10:14:00Z"
  },
  {
    "id": "card_def456",
    "last4": "1234",
    "balance": 0.00,
    "status": "exhausted",
    "label": "old-task",
    "created_at": "2026-03-01T08:00:00Z"
  }
]

Agents use list_cards as the entry point for any payment task. It tells them what cards exist and which have a non-zero balance. A well-designed agent will filter for "status": "active" and check balances before proceeding.

Tool 2: get_card_details

Returns full card credentials for a specific card.

{
  "name": "get_card_details",
  "description": "Get full details (including PAN and CVV) for a specific card",
  "inputSchema": {
    "type": "object",
    "properties": {
      "card_id": {
        "type": "string",
        "description": "The ID of the card to retrieve"
      }
    },
    "required": ["card_id"]
  }
}

Response includes the full PAN, CVV, expiration, billing address, and current balance:

{
  "id": "card_abc123",
  "pan": "4111111111117823",
  "cvv": "392",
  "expiry_month": "03",
  "expiry_year": "2027",
  "last4": "7823",
  "balance": 50.00,
  "status": "active",
  "billing_address": {
    "line1": "123 Agent St",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94105",
    "country": "US"
  }
}

This is the most sensitive tool. Access to full card credentials is only granted to processes running with a valid AgentCard API key. The MCP server will return an authorization error if the key is missing or revoked.

Tool 3: check_balance

Returns the current balance for a specific card, without returning credentials.

{
  "name": "check_balance",
  "description": "Check the current balance for a specific card",
  "inputSchema": {
    "type": "object",
    "properties": {
      "card_id": {
        "type": "string",
        "description": "The ID of the card to check"
      }
    },
    "required": ["card_id"]
  }
}

Response:

{
  "card_id": "card_abc123",
  "balance": 50.00,
  "currency": "USD",
  "status": "active"
}

Use check_balance when you want to confirm funds exist without triggering a full credential retrieval. A good agent pattern: call list_cards to find a candidate, call check_balance to confirm the balance covers the expected purchase amount, then call get_card_details only when ready to fill in the payment form.

Automatic Transaction Tracking

Transactions are tracked automatically via Stripe Issuing webhooks — no manual logging required. When the agent uses a card, the transaction details (amount, merchant, status) are recorded in real time as Stripe Issuing processes the charge. This means your audit trail is complete and accurate without the agent needing to call any additional tools.

Complete Integration Walkthrough

Setup

Install the CLI and authenticate:

npm install -g agent-cards
agent-cards login

Issue a card:

$ agent-cards cards create --amount 100
✓ Card issued in 8 seconds
Card ID: card_abc123
Last 4:  7823
Expires: 03/2027
Amount:  $100.00
Status:  active

Register the AgentCard MCP server:

claude mcp add --transport http agent-cards https://mcp.agentcard.sh/mcp \
  --header "Authorization: Bearer <your-token>"

Replace <your-token> with your AgentCard API token (found in ~/.config/agent-cards/config.json after login). The MCP server is now available to your agent immediately.

Claude Autonomous Purchasing: Example Workflow

Here is a realistic example of what a Claude session looks like when it makes an autonomous purchase. You give Claude this task:

"I need a subscription to the Perplexity API — they have a $20/month Standard plan. Use an Agent Card to subscribe. Check the balance first and record the payment after."

Claude's internal reasoning and tool call sequence:

1. Claude calls list_cards to see what's available.

   Tool: list_cards
   Input: {}
   Result: [{"id":"card_abc123","last4":"7823","balance":100.00,"status":"active","label":"claude-agent"}]

2. Claude calls check_balance to confirm sufficient funds.

   Tool: check_balance
   Input: {"card_id": "card_abc123"}
   Result: {"card_id":"card_abc123","balance":100.00,"status":"active"}

3. Claude navigates to the Perplexity API pricing page, locates the Standard plan, and clicks through to checkout.

4. Claude calls get_card_details to retrieve credentials for the payment form.

   Tool: get_card_details
   Input: {"card_id": "card_abc123"}
   Result: {"pan":"4111111111117823","cvv":"392","expiry_month":"03","expiry_year":"2027",...}

5. Claude fills in the payment form and submits. Checkout completes successfully.

6. Claude reports back to you: "Done. I subscribed to the Perplexity API Standard plan for $20.00 using card ending in 7823. The transaction is being tracked automatically."

The entire sequence from your instruction to confirmation takes around 90 seconds on a good checkout flow.

Security Considerations

Never commit API keys

The AgentCard API key lives in ~/.config/agent-cards/config.json. The MCP server reads it from there. Never paste it into a system prompt, a config file you commit to git, or a shared document. If you need the key available in a CI environment, use a secrets manager or encrypted environment variable. See Anthropic's MCP documentation for security best practices when configuring MCP servers.

Principle of least balance

Issue cards with the minimum balance needed for the task. A $20 card for a $20 subscription. A $5 card for a $4 API call. The balance ceiling is the most important control you have. Keep it tight.

Issue single-use cards for one-off tasks

For one-off agent tasks, issue a card loaded with exactly the expected spend. Once the task is done, the card's remaining balance is protection against further unauthorized use.

Troubleshooting Common Issues

Agent says no payment tools are available

Check that the MCP server was added correctly by running claude mcp list. If it is not listed, re-run the claude mcp add command. Ensure your API token is valid by running agent-cards whoami.

get_card_details returns authorization error

The MCP server cannot find a valid API key. Run agent-cards whoami to confirm you are authenticated. If the token has expired, run agent-cards login again.

Card declines during checkout

Run check_balance to confirm the card has sufficient funds. If balance is correct, the decline may be merchant-side (some merchants block virtual debit cards) or triggered by AVS mismatch. The billing address returned by get_card_details must match what you enter at checkout.

Frequently Asked Questions

What is MCP and why does it matter for AI agent payments?

The Model Context Protocol is an open standard that lets AI models call external tools in a structured, auditable way. For payments, it means an agent can look up card details, check balances, and log transactions through defined tool interfaces rather than having credentials embedded in prompts or environment variables.

What is the difference between stdio and HTTP MCP transport?

Stdio transport runs the MCP server as a local subprocess of the AI client, communicating over standard input/output. HTTP transport runs the MCP server as a standalone HTTP process that remote agents or custom integrations can reach over the network. Stdio is simpler and more secure for local use; HTTP is necessary for remote agents.

Can multiple agents share the same MCP server?

Yes. With HTTP transport, multiple agent processes can connect to a single AgentCard MCP server endpoint. Each request is authenticated with the same API key, so all agents share access to the same card pool. Use card labels or separate accounts to maintain isolation between agents.

Does Claude log card details from MCP tool responses?

By default, Claude does not persist tool response content beyond the active conversation context. Card details returned by get_card_details exist only in-context for the current session. They are not written to disk or sent to Anthropic's servers as training data.

Is there a payment MCP server for Claude?

Yes. AgentCard provides a native MCP payment server that works with Claude Desktop, Claude Code, and Cursor. It exposes tools for listing cards, retrieving card details, checking balances, and closing cards. Install the agent-cards CLI, run agent-cards setup-mcp, and the payment tools are immediately available to Claude.

Next Steps

With a solid understanding of MCP transport and the four tools, you have everything you need to build reliable agent payment workflows. For the step-by-step quickstart if you have not yet set up your first card, see How to Give an AI Agent a Credit Card.

For guidance on managing spending limits across multiple agents and longer-running workflows, read Setting Spending Limits for AI Agents. For a quick 5-minute setup guide specifically for Claude Code, see How to Give Claude Code a Virtual Card.