MCP

The MCP integration turns your Key0 seller into an MCP server. Agents connect over Streamable HTTP, discover your plans, and pay for access tokens using the x402 protocol — all without leaving the tool-call flow.

Enable MCP

Set mcp: true in your SellerConfig. The Express router automatically mounts all MCP routes alongside the existing A2A and x402 HTTP endpoints.

import express from "express";
import { key0Router } from "@key0ai/key0/express";

const app = express();

const config: SellerConfig = {
  mcp: true,
  agentName: "My Service",
  agentDescription: "A payment-gated API",
  agentUrl: "https://my-service.example.com",
  walletAddress: "0x...",
  network: "mainnet",
  plans: [
    { planId: "basic", unitAmount: "1.00", description: "Basic plan" },
  ],
  fetchResourceCredentials: async ({ planId }) => {
    return { apiKey: "sk-..." };
  },
};

app.use(key0Router({ config, adapter, store, seenTxStore }));
app.listen(3000);

Routes

The integration mounts four routes on the Express router:

Route	Method	Purpose
`/.well-known/mcp.json`	GET	MCP discovery document (name, description, transport URL)
`/mcp`	POST	Streamable HTTP transport — handles all tool calls
`/mcp`	GET	Returns 405 (SSE not supported in stateless mode)
`/mcp`	DELETE	Returns 405 (session management not supported in stateless mode)

Tools

The MCP server exposes two tools:

Tool	Gated?	Purpose
`discover_plans`	Free	Browse the plan catalog: plan IDs, prices (USDC), wallet address, chain ID
`request_access`	x402	Purchase an access token for a plan

discover_plans

Takes no arguments. Returns the full plan catalog as JSON:

{
  "agent": "My Service",
  "description": "A payment-gated API",
  "network": "mainnet",
  "chainId": 8453,
  "walletAddress": "0x...",
  "asset": "USDC",
  "plans": [
    {
      "planId": "basic",
      "unitAmount": "1.00",
      "description": "Basic plan"
    }
  ]
}

request_access

Takes planId (required) and resourceId (optional, defaults to "default"). When called without payment, it returns a PaymentRequired response. When called with a valid x402 payment, it settles on-chain and returns an access grant.

Payment Flow

There are two paths to complete a payment, depending on the client’s capabilities.

Path A: HTTP x402 (Current Clients)
Path B: Native x402 MCP (Future Clients)

This is the path used by current MCP clients like Claude Desktop, Claude Code, and Cursor. The agent uses a companion payment tool (such as Coinbase’s payments-mcp) to settle via HTTP.Step-by-step:

Agent calls discover_plans to get the catalog
Agent calls request_access({ planId: "basic" }) with no payment attached
Server returns isError: true with a PaymentRequired response containing x402PaymentUrl and paymentInstructions
Agent calls make_http_request_with_x402 (from payments-mcp) to POST to the x402PaymentUrl
payments-mcp signs an EIP-3009 authorization off-chain and sends it as a PAYMENT-SIGNATURE header
The /x402/access endpoint settles the payment on-chain and returns an AccessGrant with a JWT

PaymentRequired response:

{
  "isError": true,
  "structuredContent": {
    "x402Version": 2,
    "error": "Payment required to access this resource",
    "resource": {
      "url": "https://my-service.example.com/x402/access",
      "description": "Basic plan",
      "mimeType": "application/json"
    },
    "accepts": [
      {
        "scheme": "exact",
        "network": "eip155:8453",
        "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "amount": "1000000",
        "payTo": "0x...",
        "maxTimeoutSeconds": 900,
        "extra": {
          "name": "USDC",
          "version": "2",
          "planId": "basic",
          "description": "Basic plan"
        }
      }
    ],
    "extensions": {
      "key0": {
        "inputSchema": { "...": "..." },
        "outputSchema": { "...": "..." },
        "description": "..."
      }
    }
  },
  "content": [
    {
      "type": "text",
      "text": "{ ... x402PaymentUrl, paymentInstructions ... }"
    }
  ]
}

The content[0].text field contains x402PaymentUrl and human-readable paymentInstructions so that LLM agents can parse the next step even without structured content support.

This path is for future x402-aware MCP clients that handle payment natively within the MCP protocol.Step-by-step:

Agent calls request_access({ planId: "basic" }) with no payment
Server returns PaymentRequired with structuredContent
The x402-aware client automatically signs an EIP-3009 authorization
Client retries request_access with the signed payload in _meta["x402/payment"]
Server calls settlePayment() to settle on-chain
Server returns AccessGrant in content[0].text and settlement receipt in _meta["x402/payment-response"]

AccessGrant response:

{
  "content": [
    {
      "type": "text",
      "text": "{\"status\": \"access_granted\", \"type\": \"AccessGrant\", \"challengeId\": \"mcp-...\", \"requestId\": \"mcp-...\", \"accessToken\": \"eyJ...\", \"tokenType\": \"Bearer\", \"resourceEndpoint\": \"https://my-service.example.com/api/resource\", \"resourceId\": \"default\", \"planId\": \"basic\", \"txHash\": \"0x...\", \"explorerUrl\": \"https://basescan.org/tx/0x...\"}"
    }
  ],
  "_meta": {
    "x402/payment-response": {
      "success": true,
      "transaction": "0x...",
      "network": "eip155:8453",
      "payer": "0xBuyer..."
    }
  }
}

The _meta["x402/payment"] payload is validated against a Zod schema. If the payload is present but malformed, the server returns an isError response with Zod validation details.

Error Handling

Error	Response
Plan not found	`isError: true` with Key0Error JSON (`TIER_NOT_FOUND`)
Malformed `_meta["x402/payment"]`	`isError: true` with Key0Error JSON (Zod validation details)
Payment failed / settlement error	`isError: true` with `structuredContent` containing error message and `accepts[]` array for retry
Already redeemed tx	Cached AccessGrant returned (idempotent — no double-charge)

Already-redeemed transactions return the original AccessGrant. The requestId is derived deterministically from the payment signature, so retries with the same payment always resolve to the same challenge.

Connecting from Claude Code

Add your MCP server to .mcp.json in your project root:

{
  "mcpServers": {
    "my-service": {
      "type": "http",
      "url": "https://my-service.example.com/mcp"
    }
  }
}

Claude Code connects over Streamable HTTP and discovers the discover_plans and request_access tools automatically.

Testing with curl

List available tools:

curl -X POST https://my-service.example.com/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Call discover_plans:

curl -X POST https://my-service.example.com/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "discover_plans",
      "arguments": {}
    }
  }'

You must include both application/json and text/event-stream in the Accept header. Without both values, the MCP SDK returns a 406 Not Acceptable response.

Why Stateless?

The MCP transport creates a fresh McpServer and StreamableHTTPServerTransport for every request. This is intentional:

Tools are pure request/response. There is no streaming, subscriptions, or server-initiated messages.
All state lives in external stores. ChallengeStore and SeenTxStore (Redis or Postgres) hold challenge state and double-spend records.
Horizontal scaling. No sticky sessions, no in-memory state, no affinity requirements. Put it behind any load balancer.
No memory leaks. Each server instance is created, used, and closed within a single request lifecycle.

Getting Started

Protocols

Architecture

Integrations

Guides

Deployment

Enable MCP

Routes

Tools

discover_plans

request_access

Payment Flow

Error Handling

Connecting from Claude Code

Testing with curl

Why Stateless?

​Enable MCP

​Routes

​Tools

​discover_plans

​request_access

​Payment Flow

​Error Handling

​Connecting from Claude Code

​Testing with curl

​Why Stateless?

Enable MCP

Routes

Tools

discover_plans

request_access

Payment Flow

Error Handling

Connecting from Claude Code

Testing with curl

Why Stateless?