Skip to main content
Glama
README.md
# x420-mcp

[Model Context Protocol](https://modelcontextprotocol.io) server for **X420**'s pay-per-call agent services at
[https://signature-theme.com](https://signature-theme.com): website audits, hail and storm history, geocoding,
DNS/TLS/RDAP lookups, government and chain data, and whatever X420 sells next. Every service becomes an MCP tool;
every paid call is settled with [x402](https://x402.org) in USDC on Base **from your own wallet**.

**X420 never sees your key.** The private key is read from your environment inside this local process, signs an
EIP-3009 USDC authorization, and only that signature leaves the machine (as the `PAYMENT-SIGNATURE` header). It is
never logged, never written to disk by this package, and never sent to X420 or anyone else.

**This spends real money.** A successful paid call moves USDC on Base mainnet. Fund a dedicated wallet with only what
you are willing to spend, keep `X420_MCP_MAX_USD` low, and rotate the key when you stop using the server.

## Install

```
npx x420-mcp
```

The server speaks MCP on stdin/stdout. On start it fetches the live catalog (`GET https://signature-theme.com/a2a/catalog`)
and registers one tool per service, named `x420_<id>` with dots replaced by underscores (`sitescan.check` →
`x420_sitescan_check`, `hail.point-history` → `x420_hail_point-history`), plus two free tools:

- `x420_catalog` — the live catalog with prices, inputs and deliverables.
- `x420_quote` — a free price quote for one service and input (no order is placed).
- `x420_spend_summary` — what this server process has paid so far (calls, total USD, last-24h USD, the caps and what
  remains under each, the verified seller pay-to address).

Nothing is hard-coded: new X420 services appear on the next start.

### Claude Desktop

`claude_desktop_config.json` (Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "x420": {
      "command": "npx",
      "args": ["-y", "x420-mcp"],
      "env": {
        "X420_MCP_WALLET_PRIVATE_KEY": "0x<your private key>",
        "X420_MCP_MAX_USD": "1.00"
      }
    }
  }
}
```

### Claude Code

```
claude mcp add x420 -e X420_MCP_WALLET_PRIVATE_KEY=0x<your private key> -e X420_MCP_MAX_USD=1.00 -- npx -y x420-mcp
```

### Cursor

`.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):

```json
{
  "mcpServers": {
    "x420": {
      "command": "npx",
      "args": ["-y", "x420-mcp"],
      "env": {
        "X420_MCP_WALLET_PRIVATE_KEY": "0x<your private key>",
        "X420_MCP_MAX_USD": "1.00"
      }
    }
  }
}
```

Without a key the server still starts: the free tools work and every paid tool returns an error explaining how to set
the key. Nothing is spent until a key is present.

## Environment

| Variable | Default | Meaning |
| --- | --- | --- |
| `X420_MCP_WALLET_PRIVATE_KEY` | unset | 0x-prefixed private key of the paying wallet (USDC on Base). Unset = paid tools refuse with instructions. Never logged, never sent. |
| `X420_MCP_MAX_USD` | `1.00` | Per-call cap in USD. A service priced above it is refused before any request; a 402 asking for more than it is refused before signing. **At the default, `sitescan.basic` ($3) and `sitescan.business` ($7) are refused** — see "Default caps" below. |
| `X420_MCP_MAX_TOTAL_USD` | `5.00` | Lifetime cap for the server process: the sum of all paid calls since it started may not exceed this. |
| `X420_MCP_MAX_DAILY_USD` | `5.00` | Rolling 24-hour cap: the sum of paid calls in the last 24 hours may not exceed this. |
| `X420_MCP_ORIGIN` | `https://signature-theme.com` | The X420 seller to talk to. |
| `X420_MCP_NETWORK` | `eip155:8453` (Base mainnet) | CAIP-2 network the payer will sign on; a 402 on any other network is refused. |

## Default caps

Out of the box the server pays at most **$1.00 per call**, **$5.00 per rolling 24 hours** and **$5.00 over the life of
the process**. Two X420 services cost more than $1.00 and are therefore **refused at the default**:

| Service | Price | At the default cap |
| --- | --- | --- |
| `sitescan.basic` | $3.00 | refused ("above the per-call cap X420_MCP_MAX_USD=$1.00") |
| `sitescan.business` | $7.00 | refused ("above the per-call cap X420_MCP_MAX_USD=$1.00") |

To allow them, raise the per-call cap in the server's `env` (and the daily/lifetime caps if several calls are planned):

```json
"env": {
  "X420_MCP_WALLET_PRIVATE_KEY": "0x<your private key>",
  "X420_MCP_MAX_USD": "7",
  "X420_MCP_MAX_DAILY_USD": "25",
  "X420_MCP_MAX_TOTAL_USD": "25"
}
```

Every refusal names the cap that blocked it, for example
`refused by X420_MCP_MAX_DAILY_USD=$5.00: paying $0.50 for sitescan.check would bring rolling 24h spend to $5.25 (spent $4.75 across 9 paid calls so far).`
`x420_spend_summary` shows the running totals at any time.

## What the server will and will not sign

Before signing anything the payer checks the seller's 402 against fixed rules; any mismatch refuses and nothing is signed:

- scheme `exact` on the configured network only (`X420_MCP_NETWORK`, default `eip155:8453`);
- the asset must be that network's canonical USDC contract, compared as an address
  (Base `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`, Base Sepolia `0x036CbD53842c5426634e7929541eC2318f3dCF7e`) — a
  token that merely calls itself "USD Coin" is refused;
- `payTo` must equal the address the seller advertises in its Agent Card (`/.well-known/agent.json`, `payments.pay_to`),
  fetched when the server starts; if the card cannot be read, paid tools refuse rather than pay an unverified recipient;
- the amount must be within `X420_MCP_MAX_USD`, and must keep the process under `X420_MCP_MAX_TOTAL_USD` and
  `X420_MCP_MAX_DAILY_USD`.

## How a paid call works

1. The tool call becomes `GET <origin>/a2a/x402/<service id>?<params>`.
2. X420 answers `402` with an x402 v2 `PAYMENT-REQUIRED` header (exact scheme, USDC on Base, amount, pay-to).
3. The server checks scheme, network, asset and amount against your cap, signs the authorization with your key
   (`@x402/fetch` + `@x402/evm`), and retries with `PAYMENT-SIGNATURE`.
4. X420's facilitator settles on Base and X420 returns the deliverable with a signed receipt; the tool result carries
   the deliverable, the receipt, the order and the settlement transaction hash from `PAYMENT-RESPONSE`.

```json
{
  "service": "sitescan.check",
  "price_usd": 0.5,
  "paid_usd": 0.5,
  "deliverable": { "target": "https://example.com", "summary": { "score": 82, "grade": "B", "findings": 3 }, "findings": [] },
  "receipt": { "receipt_id": "...", "deliverable_sha256": "...", "payee": "x420:...", "sig": "<ed25519 hex>" },
  "order": { "id": "...", "status": "delivered", "amount_usd": 0.5, "rail": "x402" },
  "settlement": { "transaction": "0x...", "network": "eip155:8453", "payer": "0x...", "success": true, "error": null }
}
```

A refused call (no key, over the cap, wrong network, non-USDC asset, missing input) returns an MCP error result with
the reason, and nothing is signed.

## No key? Use the hosted endpoint

X420 also serves the same tools over MCP Streamable HTTP at **https://signature-theme.com/mcp**. That endpoint holds
no wallet: `x420_catalog` and `x420_quote` work as above, and each paid tool validates your input and returns
**payment instructions** (price, pay-to address, network and the x402 URL) instead of the deliverable, so an agent with
its own x402 client can pay directly.

```
claude mcp add --transport http x420 https://signature-theme.com/mcp
```

## Programmatic use

```ts
import { createX420McpServer } from "x420-mcp";
const { server, tools } = await createX420McpServer({ origin: "https://signature-theme.com", maxUsd: 1, privateKey: process.env.X420_MCP_WALLET_PRIVATE_KEY ?? null });
```

`x420-mcp/hosted` exports `createHostedMcpHandler({ origin })`, the express-compatible stateless Streamable HTTP
handler behind the hosted endpoint.

## Disclaimer

Automated services on public data; not professional, legal, insurance, engineering, medical, financial or tax advice.

MIT License. Source: https://github.com/BodhiNath/x420-mcp (`packages/x420-mcp`, built from `src/mcp`).

TDQS

A3.6/5.0

Scored across 38 tools

Disambiguation3/5

Most tools target distinct services or data sources, but several clusters overlap: SiteScan check/basic/business plus HTTP and TLS checks, hail/storm reports/date finder, and hash digest/evidence timestamp. Detailed descriptions help, but an agent can still misselect within these families.

Naming Consistency3/5

All tools share an x420_ prefix and broad category grouping, which is readable. However, multiword names mix underscores and hyphens (e.g. x420_geo_reverse-geocode, x420_csv_to-json, x420_chain_wallet-balance) and use noun/verb forms inconsistently.

Tool Count2/5

38 tools is well above the practical 3-15 range; many are tiny single-purpose utilities or tiered variants that could be consolidated. The broad marketplace scope explains some breadth, but the surface is heavy and burdens selection.

Completeness4/5

The surface covers discovery, quoting, spend tracking, and many paid service categories, so core workflows are present. Gaps remain around receipt/call history, refunds, wallet/config management, and generic order lifecycle, but agents can work around them.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues