How to Add Payment Support to an MCP Server

Your MCP server can call tools, read files, and hit APIs — but the moment one of those tools costs money, you’re stuck. Either you bolt on a shared key with no spend controls, or you build billing infrastructure from scratch.

Neither is acceptable for production agentic systems.

Quick answer: To add payment support to an MCP server, provision a per-agent payment account (handle + IOU balance + spending cap), then intercept 402 Payment Required responses inside your tool handlers using the x402 protocol. The agent pays inline, the request retries automatically, and your spending cap prevents runaway costs. ATXP provides the account layer; x402 provides the HTTP payment rail.

What MCP Server Payments Actually Require

MCP server payments need three things that standard API keys don’t provide: isolated identity, bounded spend, and inline settlement. A regular API key authenticates you — it doesn’t encode a budget, doesn’t support per-caller limits, and doesn’t have a revocation path that’s scoped to a single agent.

The x402 protocol handles the settlement layer. When a tool your MCP server calls returns a 402 Payment Required response, x402 defines exactly how to parse the payment details, authorize the charge, and retry. What x402 doesn’t provide is the account behind that payment — the handle, the balance, the cap, the revocation. That’s the gap ATXP fills.

The architecture looks like this:

Layer	Responsibility	Tool
Protocol	HTTP payment negotiation	x402
Account	Agent identity + IOU balance	ATXP
Spending control	Cap enforcement + revocation	ATXP
Tool interface	MCP tool handler	Your code

Step 1 — Provision an Agent Payment Account

Every agent that will make paid tool calls needs its own ATXP handle before it touches any paywall.

curl -X POST https://api.atxp.ai/v1/agents \
  -H "Authorization: Bearer $ATXP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "handle": "research-agent-01",
    "spending_cap_usd": 5.00,
    "description": "MCP research tool agent"
  }'

The response gives you a agent_credential token scoped to that handle. Store it per-agent — never share it across agents. This is the credential your MCP server will present when settling x402 payments.

One agent, one credential, one spending cap. If research-agent-01 goes haywire and hits every paid endpoint in a loop, it burns at most $5.00 and stops. Your other agents are unaffected.

Step 2 — Intercept 402 Responses in Your Tool Handler

The x402 intercept lives inside the tool handler, not at the MCP server’s transport layer. This keeps payment logic contained and lets you opt specific tools into paid flows.

Here’s a minimal example using the x402-fetch helper:

import { fetchWithPayment } from "@x402/client";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

const server = new McpServer({ name: "paid-tools", version: "1.0.0" });

server.tool(
  "web-search",
  { query: { type: "string" } },
  async ({ query }) => {
    const agentCredential = process.env.AGENT_CREDENTIAL; // per-agent, not shared

    const response = await fetchWithPayment(
      `https://search-api.example.com/search?q=${encodeURIComponent(query)}`,
      {
        method: "GET",
        paymentConfig: {
          credential: agentCredential,
          maxAmountUSD: 0.05, // per-call ceiling
        },
      }
    );

    const data = await response.json();
    return { content: [{ type: "text", text: JSON.stringify(data) }] };
  }
);

fetchWithPayment handles the full x402 negotiation: it reads the 402 response, constructs the payment authorization, and retries the request. From the tool’s perspective, it’s a single await.

Step 3 — Wire Spending Caps and Revocation

Set your spending cap at provision time, but audit it continuously — agents in long-running tasks can exhaust budgets faster than you expect.

ATXP exposes a balance endpoint you can poll or webhook on:

# Check remaining balance for a specific agent
curl https://api.atxp.ai/v1/agents/research-agent-01/balance \
  -H "Authorization: Bearer $ATXP_API_KEY"

When the balance hits zero, x402 payment attempts from that credential will fail with a clear error — the MCP tool handler gets a rejected payment response rather than a runaway loop.

For immediate shutdown, revocation is one call:

curl -X POST https://api.atxp.ai/v1/agents/research-agent-01/revoke \
  -H "Authorization: Bearer $ATXP_API_KEY"

That credential stops working across every paywall instantly. No code redeploy, no key rotation across shared systems.

---

Ready to give your MCP tools real payment infrastructure? Start with ATXP →

---

Step 4 — Handle Payment Failures Gracefully

Your tool handler must distinguish between a payment failure and an API error — agents shouldn’t silently skip paid steps or retry infinitely.

async ({ query }) => {
  try {
    const response = await fetchWithPayment(searchUrl, paymentConfig);
    return { content: [{ type: "text", text: await response.text() }] };
  } catch (err) {
    if (err.code === "PAYMENT_REJECTED") {
      // Surface this clearly — don't silently degrade
      return {
        content: [{
          type: "text",
          text: "Tool unavailable: payment limit reached for this agent."
        }],
        isError: true,
      };
    }
    throw err; // let other errors propagate normally
  }
}

Surfacing PAYMENT_REJECTED explicitly means the orchestrating model gets accurate signal. It can escalate, switch to a cheaper tool, or stop — rather than hallucinating a result because the actual API call was silently skipped.

What to Avoid

Three patterns that look reasonable but cause production problems:

• Shared credentials across agents. One compromised or runaway agent exposes every agent’s payment access. Always provision individually.
• Putting payment logic at the transport layer. Intercepting at the MCP server boundary means all tools get payment handling, including free ones. Put it in the tool handler.
• No per-call ceiling. The maxAmountUSD parameter in fetchWithPayment is your second line of defense after the account-level cap. Use both.

MCP Server Payments in Production

The difference between a toy MCP server and a production one is whether each agent’s financial access is isolated, bounded, and revocable. x402 gives you the protocol. ATXP gives you the account layer that makes per-agent isolation practical at any scale.

You provision an account, embed the credential in the tool handler, set a cap, and ship. If something goes wrong, you revoke one handle. The blast radius stays small.

Set up your first agent payment account at ATXP →