x402 MCP Server

Pay-per-use APIs for AI agents. One npm install, automatic USDC micropayments on Base.

Tools

Quick Start — Free Mode

No wallet or private key needed. Add the server to your MCP client config:

{
  "mcpServers": {
    "x402": {
      "command": "npx",
      "args": ["-y", "github:jameswilliamwisdom/x402-mcp-server"]
    }
  }
}

Free mode limitations:

• Screenshots limited to example.com, example.org, and httpbin.org
• PDF extraction limited to first 3 pages
• Sentiment returns mock data with real market structure

Quick Start — Paid Mode

Requires a Base wallet funded with USDC.

{
  "mcpServers": {
    "x402": {
      "command": "npx",
      "args": ["-y", "github:jameswilliamwisdom/x402-mcp-server"],
      "env": {
        "X402_PRIVATE_KEY": "your-private-key-here"
      }
    }
  }
}

Never commit your private key. Store it in your system environment or a local .env file loaded by your shell.

You need USDC on the Base network. Base is an Ethereum L2 with low transaction fees. See the full wallet setup guide for detailed instructions.

MCP Client Configs

Omit the env block entirely for free mode.

Claude Desktop

Config file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "x402": {
      "command": "npx",
      "args": ["-y", "github:jameswilliamwisdom/x402-mcp-server"],
      "env": {
        "X402_PRIVATE_KEY": "your-private-key-here"
      }
    }
  }
}

Claude Code

claude mcp add --transport stdio x402 -- npx -y github:jameswilliamwisdom/x402-mcp-server

Then set X402_PRIVATE_KEY in your environment.

Cursor

Config file: ~/.cursor/mcp.json

{
  "mcpServers": {
    "x402": {
      "command": "npx",
      "args": ["-y", "github:jameswilliamwisdom/x402-mcp-server"],
      "env": {
        "X402_PRIVATE_KEY": "your-private-key-here"
      }
    }
  }
}

Windsurf

Config file: ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "x402": {
      "command": "npx",
      "args": ["-y", "github:jameswilliamwisdom/x402-mcp-server"],
      "env": {
        "X402_PRIVATE_KEY": "your-private-key-here"
      }
    }
  }
}

How It Works

1. Your AI agent calls a tool (e.g., x402_screenshot)
2. The MCP server makes an HTTP request to the API
3. The API responds with 402 Payment Required
4. x402-fetch automatically signs a USDC payment on Base and retries
5. The API returns the result

The payment flow is handled by x402-fetch — your agent never needs to manage transactions directly.

License

MIT