{
  "markdown": "# @suverselabs/mcp-server\n\nAn [MCP](https://modelcontextprotocol.io) server that gives Claude Desktop (or any\nMCP client) **15 tools** for SuVerse's pay-per-call US-government and freight APIs.\nCalls are paid automatically, per request, in **USDC on Base** via the\n[x402](https://x402.org) protocol — you fund a wallet once and Claude pays as it\nworks. Your private key never leaves your machine.\n\n> ✅ **Published on npm:** https://www.npmjs.com/package/@suverselabs/mcp-server\n\n## Quick Start\n\nInstall via npx (no local build needed):\n\n```bash\nnpx -y @suverselabs/mcp-server\n```\n\n### Claude Desktop Setup\n\nAdd to `claude_desktop_config.json`:\n\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"suverse\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@suverselabs/mcp-server\"],\n      \"env\": {\n        \"SUVERSE_BASE_PRIVATE_KEY\": \"0xYOUR_PRIVATE_KEY_HERE\"\n      }\n    }\n  }\n}\n```\n\nThe 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.\n\nRestart Claude Desktop. The 15 SuVerse tools will appear in Claude's tool list.\n\n## What is SuVerse?\n\n[SuVerse](https://api.suverse.io) is an x402 gateway over 128 US-government data\nservices (SEC, NPS, FBI, CMS, …) plus a freight document/routing suite. Each call\ncosts a few tenths of a cent up to $0.50; there are no accounts or API keys — you\npay per call in USDC.\n\n## Why MCP?\n\nWithout this server you'd hand-roll x402 payments to call SuVerse. With it, the\nendpoints appear as native Claude tools: ask in plain language and Claude calls\nthem, paying transparently from your funded Base wallet.\n\n## Tools\n\n### Paid (per-call USDC on Base)\n\n| Tool | Price | Purpose |\n|---|---|---|\n| `freight_parse_ratecon` | $0.10 | Rate confirmation → JSON |\n| `freight_parse_bol_pod` | $0.15 | Bill of Lading / POD → JSON |\n| `freight_parse_fuel_receipt` | $0.05 | Fuel receipt → JSON (IFTA) |\n| `freight_parse_w9` | $0.07 | IRS W-9 → JSON |\n| `freight_parse_insurance_cert` | $0.08 | ACORD 25 COI → JSON |\n| `freight_parse_permit` | $0.25 | Oversize/overweight permit → JSON |\n| `freight_truck_route` | $0.50 | Truck-legal routing + tolls + POIs |\n| `freight_calculate_tolls` | $0.10 | Toll estimate for a polyline |\n| `freight_trip_telematics` | $0.01 | GPS trip analytics |\n| `gov_query` | $0.005 | Any of 128 gov services by id |\n| `gov_cms_open_payments` | $0.01 | CMS Open Payments by NPI |\n| `gov_fbi_crime_data` | $0.01 | FBI crime stats by state/year |\n\n### Free (no payment)\n\n| Tool | Purpose |\n|---|---|\n| `gov_list_services` | Discover the 128 `gov_query` service ids + params |\n| `suverse_estimate_cost` | Price one or many calls before running them |\n| `suverse_balance` | On-chain USDC balance + calls remaining per tool |\n| `suverse_search_endpoints` | Search every x402 endpoint SuVerse knows about (own + CDP Bazaar mirror) |\n\n### Aggregated verdicts (x402, custody-free — the server never pays)\n\n| Tool | Price | Question it answers |\n|---|---|---|\n| `suverse_market_pulse` | $0.10 | What regime is the crypto market in right now? |\n| `suverse_wallet_reputation` | $0.03 | Can this Solana wallet's trading be trusted or copied? |\n| `suverse_token_check` | $0.05 | Is this Solana token sane to enter right now? |\n\nThese three work differently from the paid tools above: **this server does not\npay for them and holds no keys for them.** Called without payment they return a\nstructured `payment_required` result — what the endpoint answers, the price, and\nthe verbatim x402 challenge (`accepts` on Base, Solana, and Cosmos Noble, all\nUSDC). Your agent (or its runtime) decides whether to pay: sign one of the\naccepts with any x402 buyer client (e.g. `@suverselabs/x402-client`) and call\nthe tool again with `payment_signature` set to the base64 header value — it is\nforwarded as `PAYMENT-SIGNATURE` / `X-PAYMENT` and the full paid verdict\n(`{verdict, signals, data_quality, raw}`) comes back. Wallet and mint arguments\nare validated as base58 client-side before any network call.\n\n## Usage examples\n\n- *\"Parse the rate con at `~/Downloads/load_4471.pdf`.\"* → `freight_parse_ratecon` (`file_path`)\n- *\"What gov services can you call?\"* → `gov_list_services`\n- *\"How much would parsing 10 BOLs cost?\"* → `suverse_estimate_cost`\n- *\"What's my SuVerse balance?\"* → `suverse_balance`\n- *\"Get Apple's SEC company info.\"* → `gov_query` (`service: \"sec.company_info\"`)\n\n### `file_path` inputs\n\nDocument tools accept a local `file_path` — the server reads the file, **verifies\nit's really a PDF/image via magic bytes**, and base64-encodes it. No need to paste\nbase64 into the chat.\n\n## Cost transparency & safety\n\n- Every paid tool's description states its price; `suverse_estimate_cost` prices\n  ahead of time.\n- **Hard cap:** a single call never settles for more than\n  `SUVERSE_MAX_PAYMENT_USDC` (default **$0.60**) **and** never more than the tool's\n  published price — whichever is lower.\n- **Client-side idempotency:** an identical repeat within a short window returns the\n  cached response instead of paying twice (complements SuVerse's server-side\n  idempotency).\n\n## Security\n\n- `SUVERSE_BASE_PRIVATE_KEY` is read from the environment, used only to sign EIP-3009\n  USDC authorizations locally, and **never logged or transmitted** anywhere except\n  as a signed payment header to SuVerse.\n- All diagnostics go to **stderr** (stdout is the MCP protocol channel).\n- `file_path` reads are restricted to your home directory (override with\n  `SUVERSE_ALLOW_PATHS_OUTSIDE_HOME=true`), reject sensitive locations\n  (`.ssh`, `.aws`, `credentials`, key files, …), and are content-type verified.\n\n### Data sent off your machine\n\nThe document-parsing tools work by **uploading the file's contents** (base64-encoded,\nor whatever you pass via `pdf_base64` / `image_base64` / `text`) to `api.suverse.io`,\nwhere they're parsed. So while your private key never leaves your machine, **the\ndocuments you ask Claude to parse do.** Only pass files you're comfortable sending to\nSuVerse for processing. The `file_path` guards above (home-directory restriction,\nsensitive-location denylist, magic-byte type check) limit *which* files can be read,\nbut any file you do parse is transmitted. The free tools (`gov_list_services`,\n`suverse_estimate_cost`, `suverse_balance`) and the on-chain balance read send no\nfile data.\n\n## Configuration reference\n\n| Env var | Default | Notes |\n|---|---|---|\n| `SUVERSE_BASE_PRIVATE_KEY` | — | **Required.** 0x Base private key. |\n| `SUVERSE_API_BASE` | `https://api.suverse.io` | |\n| `SUVERSE_MAX_PAYMENT_USDC` | `0.60` | Hard per-call ceiling. |\n| `SUVERSE_BASE_RPC_URL` | viem default | For `suverse_balance` reads. |\n| `SUVERSE_ALLOW_PATHS_OUTSIDE_HOME` | `false` | Allow `file_path` outside `$HOME`. |\n| `SUVERSE_IDEMPOTENCY_TTL_MS` | `120000` | Client idempotency window. |\n\n## Development\n\nFor contributors / running from source. End users should use the `npx` [Quick Start](#quick-start) above instead.\n\n```bash\ngit clone https://github.com/sudzikcoin/suverse-mcp && cd suverse-mcp\nnpm install\nnpm run typecheck   # tsc --noEmit\nnpm test            # vitest (mocked HTTP)\nnpm run build       # tsup → dist/index.js\nnpm run dev         # run from source (tsx)\n```\n\nTo run a local build in Claude Desktop, point `command`/`args` at the built file instead of `npx`:\n\n```json\n{\n  \"mcpServers\": {\n    \"suverse\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/suverse-mcp/dist/index.js\"],\n      \"env\": { \"SUVERSE_BASE_PRIVATE_KEY\": \"0xYOUR_PRIVATE_KEY_HERE\" }\n    }\n  }\n}\n```\n\n## License\n\nMIT\n",
  "bytes": 7761,
  "sha": "bc98d7d41c22f127d4902334bce66969edd73b0a7a13818fcefa535193fe31e3",
  "repo_slug": "sudzikcoin/suverse-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sudzikcoin_mcp_server_67d20eee/readme"
}