anchor-x402-mcp

# anchor-x402-mcp

> MCP server exposing 14 [anchor-x402](https://anchor-x402.com) 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.

```json
{
  "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:

```json
{
  "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`](https://anchor-x402.com/.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`](https://github.com/hypeprinter007-stack/anchor-x402/blob/main/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](https://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):

```json
{
  "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`:

```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`:

```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:

```json
{
  "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):

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

### OpenAI Agents SDK (programmatic)

```python
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](https://smithery.ai) one-liner:
```
npx -y @smithery/cli install anchor-x402-mcp --client claude
```
(replace `--client claude` with `cursor`, `codex`, `windsurf`, etc.)

### Run standalone

```bash
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](https://bridge.base.org)
- Buy directly on Coinbase and withdraw to Base

The MCP server signs payments via [x402](https://github.com/coinbase/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

| 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](https://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](https://anchor-x402.com/trust/on-chain-verifiability) for the full verification recipe.

## Troubleshooting

**"Payment required (402). Set ANCHOR_WALLET_PRIVATE_KEY..."**
You haven't configured a wallet. Add the env var