@suverselabs/mcp-server

An MCP server that gives Claude Desktop (or any MCP client) 15 tools for SuVerse's pay-per-call US-government and freight APIs. Calls are paid automatically, per request, in USDC on Base via the x402 protocol — you fund a wallet once and Claude pays as it works. Your private key never leaves your machine.

✅ Published on npm: https://www.npmjs.com/package/@suverselabs/mcp-server

Quick Start

Install via npx (no local build needed):

npx -y @suverselabs/mcp-server

Claude Desktop Setup

Add to claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "suverse": {
      "command": "npx",
      "args": ["-y", "@suverselabs/mcp-server"],
      "env": {
        "SUVERSE_BASE_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY_HERE"
      }
    }
  }
}

The private key controls a Base wallet that pays for tool calls in USDC. Fund it with ~$5-10 USDC on Base. You don't need ETH for gas — Base settlements are gas-sponsored. Check your balance anytime with the free suverse_balance tool.

Restart Claude Desktop. The 15 SuVerse tools will appear in Claude's tool list.

What is SuVerse?

SuVerse is an x402 gateway over 128 US-government data services (SEC, NPS, FBI, CMS, …) plus a freight document/routing suite. Each call costs a few tenths of a cent up to $0.50; there are no accounts or API keys — you pay per call in USDC.

Why MCP?

Without this server you'd hand-roll x402 payments to call SuVerse. With it, the endpoints appear as native Claude tools: ask in plain language and Claude calls them, paying transparently from your funded Base wallet.

Tools

Paid (per-call USDC on Base)

| Tool | Price | Purpose | |---|---|---| | freight_parse_ratecon | $0.10 | Rate confirmation → JSON | | freight_parse_bol_pod | $0.15 | Bill of Lading / POD → JSON | | freight_parse_fuel_receipt | $0.05 | Fuel receipt → JSON (IFTA) | | freight_parse_w9 | $0.07 | IRS W-9 → JSON | | freight_parse_insurance_cert | $0.08 | ACORD 25 COI → JSON | | freight_parse_permit | $0.25 | Oversize/overweight permit → JSON | | freight_truck_route | $0.50 | Truck-legal routing + tolls + POIs | | freight_calculate_tolls | $0.10 | Toll estimate for a polyline | | freight_trip_telematics | $0.01 | GPS trip analytics | | gov_query | $0.005 | Any of 128 gov services by id | | gov_cms_open_payments | $0.01 | CMS Open Payments by NPI | | gov_fbi_crime_data | $0.01 | FBI crime stats by state/year |

Free (no payment)

| Tool | Purpose | |---|---| | gov_list_services | Discover the 128 gov_query service ids + params | | suverse_estimate_cost | Price one or many calls before running them | | suverse_balance | On-chain USDC balance + calls remaining per tool | | suverse_search_endpoints | Search every x402 endpoint SuVerse knows about (own + CDP Bazaar mirror) |

Aggregated verdicts (x402, custody-free — the server never pays)

| Tool | Price | Question it answers | |---|---|---| | suverse_market_pulse | $0.10 | What regime is the crypto market in right now? | | suverse_wallet_reputation | $0.03 | Can this Solana wallet's trading be trusted or copied? | | suverse_token_check | $0.05 | Is this Solana token sane to enter right now? |

These three work differently from the paid tools above: this server does not pay for them and holds no keys for them. Called without payment they return a structured payment_required result — what the endpoint answers, the price, and the verbatim x402 challenge (accepts on Base, Solana, and Cosmos Noble, all USDC). Your agent (or its runtime) decides whether to pay: sign one of the accepts with any x402 buyer client (e.g. @suverselabs/x402-client) and call the tool again with payment_signature set to the base64 header value — it is forwarded as PAYMENT-SIGNATURE / X-PAYMENT and the full paid verdict ({verdict, signals, data_quality, raw}) comes back. Wallet and mint arguments are validated as base58 client-side before any network call.

Usage examples

• "Parse the rate con at ~/Downloads/load_4471.pdf." → freight_parse_ratecon (file_path)
• "What gov services can you call?" → gov_list_services
• "How much would parsing 10 BOLs cost?" → suverse_estimate_cost
• "What's my SuVerse balance?" → suverse_balance
• "Get Apple's SEC company info." → gov_query (service: "sec.company_info")

file_path inputs

Document tools accept a local file_path — the server reads the file, verifies it's really a PDF/image via magic bytes, and base64-encodes it. No need to paste base64 into the chat.

Cost transparency & safety

• Every paid tool's description states its price; suverse_estimate_cost prices ahead of time.
• Hard cap: a single call never settles for more than SUVERSE_MAX_PAYMENT_USDC (default $0.60) and never more than the tool's published price — whichever is lower.
• Client-side idempotency: an identical repeat within a short window returns the cached response instead of paying twice (complements SuVerse's server-side idempotency).

Security

• SUVERSE_BASE_PRIVATE_KEY is read from the environment, used only to sign EIP-3009 USDC authorizations locally, and never logged or transmitted anywhere except as a signed payment header to SuVerse.
• All diagnostics go to stderr (stdout is the MCP protocol channel).
• file_path reads are restricted to your home directory (override with SUVERSE_ALLOW_PATHS_OUTSIDE_HOME=true), reject sensitive locations (.ssh, .aws, credentials, key files, …), and are content-type verified.

Data sent off your machine

The document-parsing tools work by uploading the file's contents (base64-encoded, or whatever you pass via pdf_base64 / image_base64 / text) to api.suverse.io, where they're parsed. So while your private key never leaves your machine, the documents you ask Claude to parse do. Only pass files you're comfortable sending to SuVerse for processing. The file_path guards above (home-directory restriction, sensitive-location denylist, magic-byte type check) limit which files can be read, but any file you do parse is transmitted. The free tools (gov_list_services, suverse_estimate_cost, suverse_balance) and the on-chain balance read send no file data.

Configuration reference

| Env var | Default | Notes | |---|---|---| | SUVERSE_BASE_PRIVATE_KEY | — | Required. 0x Base private key. | | SUVERSE_API_BASE | https://api.suverse.io | | | SUVERSE_MAX_PAYMENT_USDC | 0.60 | Hard per-call ceiling. | | SUVERSE_BASE_RPC_URL | viem default | For suverse_balance reads. | | SUVERSE_ALLOW_PATHS_OUTSIDE_HOME | false | Allow file_path outside $HOME. | | SUVERSE_IDEMPOTENCY_TTL_MS | 120000 | Client idempotency window. |

Development

For contributors / running from source. End users should use the npx Quick Start above instead.

git clone https://github.com/sudzikcoin/suverse-mcp && cd suverse-mcp
npm install
npm run typecheck   # tsc --noEmit
npm test            # vitest (mocked HTTP)
npm run build       # tsup → dist/index.js
npm run dev         # run from source (tsx)

To run a local build in Claude Desktop, point command/args at the built file instead of npx:

{
  "mcpServers": {
    "suverse": {
      "command": "node",
      "args": ["/absolute/path/to/suverse-mcp/dist/index.js"],
      "env": { "SUVERSE_BASE_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY_HERE" }
    }
  }
}

License

MIT