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.

What an agent gets

Fourteen tools, $0.001–$0.05 per call.

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

| Tool | Price | What it does | |---|---|---| | anchor_hash | $0.005 | Anchor any 32-byte hash to Base + Solana mainnet in parallel; returns both tx URLs | | screen_wallet | $0.001 | OFAC SDN sanctions screening for any EVM or Solana wallet | | attest_decision | $0.010 | Verify a wallet signature over (input_hash, output_hash, decision); dual-chain anchor the result | | decode_tx | $0.001 | Structured decode of any mainnet tx (Base / Ethereum / Solana) | | resolve_name | $0.001 | Cross-chain name resolution (ENS, Bonfida SNS) | | token_price | $0.001 | USD spot price for any token by symbol or chain+contract | | decode_calldata | $0.001 | 4byte selector + ABI param decode for raw EVM calldata | | parse_datetime | $0.001 | Freeform datetime string → structured ISO 8601 | | intel_wallet | $0.005 | Bundled wallet intelligence: balances + activity + identity + sanctions in one call |

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

| Tool | Price | What it does | |---|---|---| | roast | $0.05 | Witty 3-5 paragraph roast of any target — wallet, tweet, code, idea, anything | | oracle | $0.05 | Yes/no oracle. Returns YES/NO/MAYBE + reason + dual-chain anchored (question \| answer \| timestamp) hash. Cryptographic receipt of when you asked. | | tldr | $0.01 | Summarize a URL (fetches up to 500KB) or pasted text into 3-5 concise bullets | | aura | $0.01 | Returns color, tier (S/A/B/C/D/F), score 0-9999, and a punchy 2-3 sentence aura read | | grade | $0.01 | Academic letter grade (A+ to F) with red-pen marginalia and one-paragraph summary |

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:

Hits an anchor-x402 endpoint
Gets a 402 with payment requirements
Server signs a USDC transfer authorization with your private key
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

| Variable | Required? | Purpose | |---|---|---| | ANCHOR_WALLET_PRIVATE_KEY | Yes for paid calls | EVM private key. The wallet pays for x402 calls. | | ANCHOR_API_URL | No | Override the API base URL. Default: https://api.anchor-x402.com. Useful for development against a self-hosted fork. |

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.

License

MIT

anchor-x402-mcp

anchor-x402-mcp

Two transports — pick by who holds the wallet key

What an agent gets

Install

Claude Desktop

Claude Code

Codex CLI (OpenAI)

ChatGPT Desktop

Cursor

OpenAI Agents SDK (programmatic)

Continue / Smithery / generic MCP client

Run standalone

Funding your wallet

Environment variables

Security notes

Verifying anchor receipts

Troubleshooting

Links

License

Score

Proud of your score? Add this badge to your README.

anchor-x402-mcp FAQ

How do I install anchor-x402-mcp?

Is anchor-x402-mcp an official MCP server?

Related MCP servers

Related guides