x402 Claude MCP Server

A reusable MCP (Model Context Protocol) server that enables LLM agents to autonomously call x402-protected APIs using CDP embedded wallets. This server exposes configured x402 endpoints as MCP tools, allowing agents to discover and use paid APIs without manual payment handling.

Features

• Autonomous Payments: Automatic x402 payment handling using CDP embedded wallets
• Dynamic Discovery: Agents discover available endpoints through MCP tool definitions
• Flexible Configuration: JSON-based endpoint configuration with environment variable support
• Security First: Trust model ensures only approved endpoints can be called
• Multi-Network Support: Works with Base, Base Sepolia, Ethereum, and Sepolia testnets
• Universal Compatibility: Works with Claude Desktop, Claude Code, Codex, Gemini, and other MCP clients

Prerequisites

• Node.js >= 18.0.0
• A CDP embedded wallet with USDC balance
• An MCP-compatible client (Claude Desktop, Claude Code, etc.)

Quick Start (Recommended)

The easiest way to get started is with the interactive setup wizard:

npx x402-claude-mcp setup

Alternative ways to run setup:

# If installed globally
npm install -g x402-claude-mcp
x402-claude-mcp setup

# Or with short flag
npx x402-claude-mcp --setup
npx x402-claude-mcp -s

# Or from local installation
npm run setup

What the setup wizard does:

• ✅ Creates ~/.x402-claude-mcp/ directory
• ✅ Generates endpoints.json with pre-configured x402 APIs (QR codes, metadata extraction, GIF search, etc.)
• ✅ Prompts for your CDP wallet private key
• ✅ Updates ~/Library/Application Support/Claude/claude_desktop_config.json automatically
• ✅ Configures the MCP server with proper environment variables

That's it! After restarting Claude Desktop, you'll have a wallet and can start using x402-protected APIs.

Look for the 🔌 icon in Claude Desktop to verify the server is running.

Installation

Global Installation

npm install -g x402-claude-mcp

Or Use with npx

npx x402-claude-mcp

Manual Configuration

Note: We recommend using npx x402-claude-mcp setup instead of manual configuration. Use this section only if you prefer manual setup or need custom configuration.

1. Create Configuration Directory

mkdir -p ~/.x402-claude-mcp

2. Create Endpoint Configuration

Create ~/.x402-claude-mcp/endpoints.json:

{
  "wallet": {
    "provider": "cdp-embedded",
    "network": "base",
    "privateKey": "${PRIVATE_KEY}"
  },
  "endpoints": [
    {
      "id": "minifetch_extract_metadata",
      "name": "Extract URL Metadata",
      "url": "https://minifetch.com/api/v1/x402/extract/url-metadata",
      "method": "GET",
      "description": "Fetch and extract HTML metadata from a specified URL. Returns all HTML meta tags, Open Graph tags, Twitter tags, headings, image tags, and response headers. Set includeResponseBody=true to return entire response body as a string. Useful for SEO and AI research projects.",
      "category": "web-scraping",
      "parameters": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "The URL from which to extract HTML metadata"
          },
          "includeResponseBody": {
            "type": "string",
            "description": "If set to 'true', includes the full HTML response body as a string in the result"
          }
        },
        "required": ["url"]
      },
      "estimatedCost": "$0.01",
      "trusted": true
    }
  ]
}

See config/endpoints.example.json for a complete example with multiple endpoints.

3. Set Environment Variables

Create a .env file or set environment variables:

export PRIVATE_KEY="0x..."
export X402_CONFIG_PATH="~/.x402-claude-mcp/endpoints.json"  # Optional, defaults to this
export DEBUG="false"  # Set to "true" for debug logging

4. Configure Your MCP Client

Claude Desktop (macOS)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "x402-claude-mcp": {
      "command": "npx",
      "args": ["-y", "x402-claude-mcp"],
      "env": {
        "PRIVATE_KEY": "0x...",
        "X402_CONFIG_PATH": "~/.x402-claude-mcp/endpoints.json"
      }
    }
  }
}

Claude Code

Edit ~/.claude/settings.json:

{
  "mcp": {
    "x402-claude-mcp": {
      "command": "npx x402-claude-mcp",
      "env": {
        "PRIVATE_KEY": "0x...",
        "X402_CONFIG_PATH": "~/.x402-claude-mcp/endpoints.json"
      }
    }
  }
}

Codex CLI

Edit ~/.codex/config.toml:

[[mcpServers]]
name = "x402-claude-mcp"
command = "npx"
args = ["x402-claude-mcp"]

[mcpServers.env]
PRIVATE_KEY = "0x..."
X402_CONFIG_PATH = "~/.x402-claude-mcp/endpoints.json"

Usage

Once configured, your LLM agent can autonomously use the endpoints:

User: "Extract metadata from https://example.com and tell me about the page"

Agent: [Calls minifetch_extract_metadata tool]
       [Payment automatically handled via x402]
       [Receives metadata and summarizes]

The agent will:

1. Discover available tools via tools/list
2. Call endpoints via tools/call
3. Handle 402 payment responses automatically
4. Return results to the user

Production Deployment

For Node.js Applications

Install the MCP SDK and integrate the x402 agent into your backend:

npm install @modelcontextprotocol/sdk

import { spawn } from 'child_process';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

// Start MCP server as a child process
const transport = new StdioClientTransport({
  command: 'npx',
  args: ['x402-claude-mcp'],
  env: {
    PRIVATE_KEY: process.env.PRIVATE_KEY,
    X402_CONFIG_PATH: './x402-endpoints.json'
  }
});

const client = new Client({ name: 'my-app', version: '1.0.0' }, {});
await client.connect(transport);

// Call x402-protected endpoints
const result = await client.callTool({
  name: 'minifetch_extract_metadata',
  arguments: { url: 'https://example.com' }
});

console.log('Result:', result.content);
console.log('Transaction:', result.txHash);
console.log('BaseScan:', `https://basescan.org/tx/${result.txHash}`);

Configuration Paths

The server looks for endpoints.json in the following order:

1. X402_CONFIG_PATH environment variable (explicit path)
2. ./x402-endpoints.json (project root)
3. ./config/endpoints.json (config folder)
4. ~/.x402-claude-mcp/endpoints.json (user home, fallback)

Production Best Practices

When deploying to production:

1. Add x402-endpoints.json to your repo (without secrets - use ${PRIVATE_KEY} template)
2. Set PRIVATE_KEY as environment variable in your deployment platform
3. Run the MCP server as a child process from your backend
4. Monitor wallet balance and set up alerts for low USDC
5. Use separate wallets for dev/staging/prod environments

Configuration Reference

Wallet Configuration

| Field | Type | Description | Required | |-------|------|-------------|----------| | provider | string | Wallet provider (only "cdp-embedded" supported) | Yes | | network | string | Network: "base", "base-sepolia", "ethereum", "sepolia" | Yes | | privateKey | string | Private key (hex or ${ENV_VAR}) | Yes |

Endpoint Configuration

| Field | Type | Description | Required | |-------|------|-------------|----------| | id | string | Unique identifier (snake_case) | Yes | | name | string | Human-readable name | Yes | | url | string | HTTPS URL of x402 endpoint | Yes | | method | string | HTTP method (GET, POST, PUT, PATCH, DELETE) | Yes | | description | string | Tool description (min 20 chars) | Yes | | parameters | object | JSON Schema for parameters | Yes | | trusted | boolean | Allow autonomous execution | Yes | | category | string | Endpoint category | No | | estimatedCost | string | Estimated cost per call | No |

Environment Variables

• PRIVATE_KEY: Your CDP wallet private key (required)
• X402_CONFIG_PATH: Path to endpoints.json (default: ~/.x402-claude-mcp/endpoints.json)
• DEBUG: Enable debug logging (default: false)

Development

Build from Source

# Clone the repository
git clone https://github.com/Must-be-Ash/x402-claude-mcp.git
cd x402-claude-mcp

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

Project Structure

x402-claude-mcp/
├── src/
│   ├── index.ts              # Main entry point
│   ├── server.ts             # MCP server setup
│   ├── handlers/
│   │   ├── listTools.ts      # tools/list handler
│   │   └── callTool.ts       # tools/call handler
│   ├── registry/
│   │   ├── types.ts          # TypeScript types
│   │   ├── EndpointRegistry.ts
│   │   └── validator.ts      # Config validation
│   ├── payment/
│   │   ├── WalletManager.ts  # CDP wallet
│   │   └── PaymentHandler.ts # x402 integration
│   └── utils/
│       ├── errors.ts         # Error classes
│       ├── logger.ts         # Logging
│       └── retry.ts          # Retry logic
├── config/
│   └── endpoints.example.json
└── package.json

Troubleshooting

Server Not Starting

• Check that Node.js >= 18.0.0 is installed: node --version
• Verify PRIVATE_KEY is set correctly
• Check configuration file syntax: cat ~/.x402-claude-mcp/endpoints.json | jq

Endpoints Not Appearing

• Restart your MCP client after configuration changes
• Check server logs for errors (set DEBUG=true)
• Verify trusted: true is set in endpoint config

Payment Failures

• Ensure wallet has sufficient USDC balance
• Check network matches endpoint requirements
• Verify private key has correct format (0x...)

Configuration Errors

• Validate JSON syntax
• Ensure all required fields are present
• Check endpoint URLs use HTTPS
• Verify parameter schemas are valid JSON Schema

Security

Trust Model

Only endpoints with "trusted": true can be called autonomously. This prevents:

• Unauthorized spending on unknown endpoints
• Malicious endpoint injection
• Unintended payment execution

Review endpoints carefully before setting trusted: true!

Private Key Safety

✅ DO:

• Use environment variables for private keys (${PRIVATE_KEY})
• Use separate wallets for dev/staging/prod
• Monitor wallet balance and set up alerts
• Keep private keys in secure secret management systems
• Rotate keys periodically

❌ DON'T:

• Commit private keys to git
• Hardcode private keys in endpoints.json
• Share wallets between different applications
• Use production wallets for testing

Network Security

• All endpoints must use HTTPS
• Configuration files should have restricted permissions: chmod 600 ~/.x402-claude-mcp/endpoints.json

Production Security Checklist

• [ ] PRIVATE_KEY set as environment variable (not in code)
• [ ] endpoints.json uses ${PRIVATE_KEY} template
• [ ] Wallet has sufficient USDC balance for expected usage
• [ ] Endpoints are marked trusted: true only after verification
• [ ] Monitor transaction logs for unexpected payments
• [ ] Set up alerts for low USDC balance
• [ ] Test on testnet (base-sepolia) before production
• [ ] Use separate wallets for different environments

License

Apache-2.0

Contributing

Contributions are welcome! Please open an issue or pull request.

Support

For issues and questions:

• GitHub Issues: https://github.com/Must-be-Ash/x402-claude-mcp/issues
• Documentation: https://docs.cdp.coinbase.com/x402/

Related Projects

• x402 Protocol
• Coinbase Developer Platform
• Model Context Protocol

x402-claude-mcp