X402 MCP Template Server

This MCP server enables AI agents to consume X402 protected APIs with gasless micropayments, while abstracting away the payment complexity. It provides a production‑ready path to query protected APIs, manage payments automatically, and integrate with Claude Desktop for streamlined tool usage.

How to use

You use this MCP server by running it as a local process or connecting to it from an MCP client like Claude Desktop. It supports two modes: Demo Mode, which returns sample data without needing a wallet, and Payment Mode, which makes real X402 protected API calls and handles payments automatically. When you start in Payment Mode, you simply provide your wallet private key and USDC balance; the server handles the 402 flow, including signature generation and retry.

How to install

Prerequisites: Node.js and npm installed on your machine. You will also need a wallet with USDC for Payment Mode and access to an X402 API endpoint.

# 1. Clone or obtain the template project
# (Assuming you have the MCP server project available locally)

# 2. Install dependencies
npm install

# 3. Copy environment variables template
cp .env.example .env

# 4. Build the TypeScript project (if you are using TypeScript)
npm run build

# 5. Run in development or production mode as needed
npm run dev

Configuration and startup

Configure environment variables to switch between Demo Mode and Payment Mode. The server reads PRIVATE_KEY, RESOURCE_SERVER_URL, and NETWORK to determine behavior and API access.

# Demo Mode (no real payments)
PRIVATE_KEY=
RESOURCE_SERVER_URL=https://places-api.x402hub.xyz
NETWORK=base-sepolia

# Payment Mode (enabled payments)
PRIVATE_KEY=0x1234567890abcdef...
RESOURCE_SERVER_URL=https://places-api.x402hub.xyz
NETWORK=base-sepolia

Claude Desktop integration

To connect Claude Desktop, configure the MCP server as a local stdio process so Claude can spawn and communicate with it. The example below shows how to point Claude Desktop to a local build of the MCP server.

{
  "mcpServers": {
    "x402_your_api": {
      "command": "node",
      "args": ["/absolute/path/to/Template-x402-Mcp/build/index.js"],
      "env": {
        "PRIVATE_KEY": "0x...",
        "RESOURCE_SERVER_URL": "https://your-x402-api.example.com",
        "NETWORK": "base-sepolia"
      }
    }
  }
}

Security and best practices

Never commit private keys or sensitive credentials. Use separate wallets for testnet and mainnet environments. Monitor USDC balances and validate all API responses before presenting data to users.

Monitoring and testing

You can inspect the MCP server locally using the MCP Inspector and run tests in development mode. Check logs for payment initialization, wallet address, and network details to ensure that the payment flow is functioning correctly.

Troubleshooting

If you encounter issues with the Payment flow, verify that you have valid USDC in the correct network, that PRIVATE_KEY is correctly configured, and that RESOURCE_SERVER_URL is reachable. Use the service discovery tool to confirm API metadata and health checks.

Notes

This server is designed to be production‑ready with support for both testnet and mainnet environments. It includes automatic 402 retry with payment authorization and compatible tooling for MCP inspection and Claude Desktop integration.

Available tools

example_api_call

Template tool for making example calls to an X402 API and returning the response data in a structured format

service_info

Tool to fetch API service discovery metadata and capabilities from the X402 API

health_check

Tool to verify API availability and responsiveness