anchor-x402-mcp

MCP server exposing 14 anchor-x402 services as tools any Claude Desktop / Cursor / Codex / Continue agent can call. Pay-per-use USDC via x402 on Base mainnet — no API keys, no subscriptions.

Two transports — pick by who holds the wallet key

This package (stdio) needs a funded EVM private key in the local process (ANCHOR_WALLET_PRIVATE_KEY) and pays for each call on your behalf. Convenient, but you are handing a hot key to a process.

Streamable HTTP — POST https://api.anchor-x402.com/mcp — needs no install and no key handover. It exposes all 18 services (four more than this package: roll_random, investigate_wallet, ledger_summary, ledger_report), and you pay per call with a PAYMENT-SIGNATURE header, so your key never leaves your side.

{
  "mcpServers": {
    "anchor-x402": { "url": "https://api.anchor-x402.com/mcp" }
  }
}

Clients that speak remote MCP natively take the url form above. For one that only launches stdio processes, bridge it:

{
  "mcpServers": {
    "anchor-x402": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.anchor-x402.com/mcp"]
    }
  }
}

Protocol revisions supported: 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26 — both the stateless era and the initialize handshake era, on one endpoint. server/discover and tools/list are free; tools/call is paid.

Payment is the ordinary x402 dance, surfaced inside MCP rather than around it: an unpaid tools/call returns a result (not a JSON-RPC error) with isError: true and the challenge in structuredContent.accepts, plus the canonical payment-required header. Sign one of the options and retry the identical call with PAYMENT-SIGNATURE. The challenge comes back as a result on purpose — an agent can read it and pay, whereas a JSON-RPC error would be swallowed by the client before the model ever saw it.

Server card: /.well-known/mcp/server-card.json. A worked client, including the adapter that bridges a stock x402 fetch wrapper to the MCP result shape, is in examples/agent/mcp-paid-call.mjs.

The rest of this README covers the stdio package.

Related MCP server: x402-bazaar-mcp

What an agent gets

Fourteen tools, $0.001–$0.05 per call.

Commodity primitives (9, $0.001–$0.01):

Universal LLM endpoints (5, $0.01–$0.05) — added in v0.2:

The investigator (/v1/investigate, $1.77 async) and the hosted chatbot at chat.anchor-x402.com are not included in the MCP — they're accessed directly via the HTTP API and the browser respectively.

The MCP server pays for itself — your wallet gets debited automatically for each call. No prepay, no API key, no account.

Install

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "anchor-x402": {
      "command": "npx",
      "args": ["-y", "anchor-x402-mcp"],
      "env": {
        "ANCHOR_WALLET_PRIVATE_KEY": "0xYOUR_BASE_WALLET_PRIVATE_KEY"
      }
    }
  }
}

Restart Claude Desktop. Ask: "Anchor the hash 7646dda1564bde0ef3f3971f4c002962df64246da4aa1d8c47247e7632494710 on mainnet" — it'll call anchor_hash and pay $0.005 USDC from your wallet.

Claude Code

Add to your project's .mcp.json:

{
  "anchor-x402": {
    "command": "npx",
    "args": ["-y", "anchor-x402-mcp"],
    "env": {
      "ANCHOR_WALLET_PRIVATE_KEY": "0xYOUR_BASE_WALLET_PRIVATE_KEY"
    }
  }
}

Codex CLI (OpenAI)

Edit ~/.codex/config.toml:

[mcp_servers.anchor-x402]
command = "npx"
args = ["-y", "anchor-x402-mcp"]

[mcp_servers.anchor-x402.env]
ANCHOR_WALLET_PRIVATE_KEY = "0xYOUR_BASE_WALLET_PRIVATE_KEY"

Restart codex. Type /mcp to confirm anchor-x402 shows in the loaded servers list.

ChatGPT Desktop

Settings → Integrations → MCP servers → Add server. Paste:

{
  "command": "npx",
  "args": ["-y", "anchor-x402-mcp"],
  "env": {
    "ANCHOR_WALLET_PRIVATE_KEY": "0xYOUR_BASE_WALLET_PRIVATE_KEY"
  }
}

Save, restart, the 14 tools appear in any chat with tool-use enabled.

Cursor

Edit ~/.cursor/mcp.json (global) or <project>/.cursor/mcp.json (project-scoped):

{
  "mcpServers": {
    "anchor-x402": {
      "command": "npx",
      "args": ["-y", "anchor-x402-mcp"],
      "env": {
        "ANCHOR_WALLET_PRIVATE_KEY": "0xYOUR_BASE_WALLET_PRIVATE_KEY"
      }
    }
  }
}

OpenAI Agents SDK (programmatic)

from openai_agents import Agent, MCPServerStdio

mcp = MCPServerStdio(
    command="npx",
    args=["-y", "anchor-x402-mcp"],
    env={"ANCHOR_WALLET_PRIVATE_KEY": "0xYOUR_BASE_WALLET_PRIVATE_KEY"},
)
agent = Agent(name="researcher", model="gpt-4o", mcp_servers=[mcp])

Same package, same env, programmatic instead of config-driven.

Continue / Smithery / generic MCP client

Same shape — command: npx, args: [-y, anchor-x402-mcp], env carries your wallet key. The MCP SDK handles transport.

Or install via Smithery one-liner:

npx -y @smithery/cli install anchor-x402-mcp --client claude

(replace --client claude with cursor, codex, windsurf, etc.)

Run standalone

ANCHOR_WALLET_PRIVATE_KEY=0xYOUR_KEY npx anchor-x402-mcp

Speaks MCP over stdio. Pipe into any MCP-compatible client.

Funding your wallet

The wallet you set as ANCHOR_WALLET_PRIVATE_KEY needs USDC on Base mainnet. Any amount works — even $1 buys 100 anchor calls or 1000 commodity-tier calls. Send USDC to your wallet's Base address:

• USDC contract on Base: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

• Bridge from Ethereum mainnet via bridge.base.org

• Buy directly on Coinbase and withdraw to Base

The MCP server signs payments via x402 — Coinbase's open HTTP-native micropayments protocol. Each request:

1. Hits an anchor-x402 endpoint

2. Gets a 402 with payment requirements

3. Server signs a USDC transfer authorization with your private key

4. Retries the request with the signed payment — the API settles via Coinbase's facilitator

You see the response, your wallet's USDC balance ticks down by the call price. Sub-second, no ledger, no account.

Environment variables

If ANCHOR_WALLET_PRIVATE_KEY is unset, paid tool calls return a friendly 402 message explaining how to set it. /health and /openapi.json (not exposed as tools, but reachable via direct curl) work without payment.

Security notes

• The private key lives in your MCP client's config file. Treat it like a hot wallet — only fund what you're willing to spend autonomously.

• Recommended: generate a fresh wallet specifically for agent use. Top up periodically; don't reuse a wallet that holds significant funds.

• The MCP server only signs USDC payment authorizations to anchor-x402's known treasury addresses (visible in the 402 response). It cannot drain your wallet to arbitrary addresses.

• Source code is fully open at github.com/hypeprinter007-stack/anchor-x402-mcp. Audit before installing.

Verifying anchor receipts

Every anchor_hash and attest_decision call returns Base + Solana tx URLs. These are independently verifiable on the public block explorers — agents can confirm an anchor exists without re-paying:

• Base: https://basescan.org/tx/<base.tx> — Input Data field contains the merkle root

• Solana: https://solscan.io/tx/<solana.tx> — Memo program data contains the same hex

The on-chain bytes are the receipt; the API response is just a convenience wrapper around them. See the on-chain verifiability primer for the full verification recipe.

Troubleshooting

"Payment required (402). Set ANCHOR_WALLET_PRIVATE_KEY..." You haven't configured a wallet. Add the env var to your MCP config and restart Claude Desktop.

"Payment failed (402). The wallet may be out of USDC..." Your wallet ran out. Send USDC on Base to the wallet address shown in the server's startup log (it logs payer=0x… to stderr).

"anchor-x402 request failed: ..." Network or DNS issue. Check https://api.anchor-x402.com/health returns 200; if not, see the status page.

Links

• Live API: https://api.anchor-x402.com

• MCP over HTTP: https://api.anchor-x402.com/mcp — all 18 tools, no key handover

• MCP server card: https://anchor-x402.com/.well-known/mcp/server-card.json

• Site / trust portal: https://anchor-x402.com

• Status: https://anchor-x402.betteruptime.com

• Server source: https://github.com/hypeprinter007-stack/anchor-x402

• MCP server source (this repo): https://github.com/hypeprinter007-stack/anchor-x402-mcp

• x402 protocol: https://github.com/coinbase/x402

• MCP spec: https://modelcontextprotocol.io

License

MIT