Alienprobe Who MCP server

alienprobe-who-mcp

An MCP server that gives any agent one legal-entity fact — LEI, legal name, jurisdiction, entity and registration status — for $0.05 USDC on Base, paid per call over x402. No signup, no API key, no account. The wallet is the account.

Two tools:

Client config

Three lines. Claude Desktop (claudedesktopconfig.json) or Cursor (.cursor/mcp.json):

{ "mcpServers": { "who": { "command": "npx", "args": ["-y", "@alienprobe/who-mcp"],
  "env": { "PRIVATE_KEY": "0x...", "MAX_USD_PER_SESSION": "1.00" } } } }

Drop the env block entirely and the server still starts — whoterms works, who refuses with walletnot_configured. That is the safe way to try it.

Environment

See .env.example. Never commit a real key. Fund a wallet that holds nothing else — about $1 of USDC covers 20 lookups. This repo does not tell you how to get USDC onto Base; see https://docs.base.org/base-chain/tools/bridges/.

Spend caps

The server preflights every who call with a plain, unwrapped fetch — no signer exists on that path — reads the advertised price out of the 402, and only then decides. If the price exceeds MAXUSDPERCALL, or would push the running total past MAXUSDPERSESSION, it refuses with a result the model can read and act on:

{
  "error": "spend_cap_exceeded",
  "scope": "per_session",
  "price_usd": 0.05,
  "cap_usd": 1.0,
  "spent_usd_this_session": 1.0,
  "remaining_usd": 0.0,
  "hint": "the session budget is spent; raise MAX_USD_PER_SESSION and restart the MCP server to buy more"
}

A session is one server process. Restarting the client resets the counter, so the per-session cap is a brake, not a ledger — the wallet balance is the real ceiling. Keep it small.

What comes back

A paid hit is the API's body verbatim plus paid_usd:

{
  "schema_version": "who-lookup.v1",
  "subject": { "type": "who", "value": "apple.com" },
  "answer": {
    "lei": "HWUPKR0MPOU8FGXBT394",
    "legal_name": "Apple Inc.",
    "jurisdiction": "US-CA",
    "entity_status": "ACTIVE",
    "registration_status": "ISSUED",
    "match": { "by": "domain", "rule": "domain_exact" },
    "official_website": "https://apple.com/"
  },
  "source": { "name": "...", "vintage": "...", "coverage": "..." },
  "paid_usd": 0.05
}

q is a company name, a registrable domain, or a 20-character LEI. To disambiguate a name, append a jurisdiction in the same string: "Acme Corp;US-DE".

paid_usd is the authorized price, not the receipt

paidusd is the amount the server authorized* — the price the API advertised in its 402 and that the spend caps were judged against. It is not read back from the chain.

One case where it overstates: a wallet's first successful lookup on this pricing shelf settles at $0 (first-can-free; a property of the service, not of this client). That call still reports "paid_usd": 0.05. Every subsequent call actually moves $0.05.

The server's session counter inherits the same overstatement, which is the safe direction — it stops you early, never late. If you need the truth, the on-chain USDC Transfer from your wallet is the only receipt. Do not use paid_usd for accounting.

Free refusals

Shortened. The full README is on GitHub.