SuVerse MCP Server
Provides tools for analyzing Solana wallets and tokens, including wallet reputation assessment and token safety checks, by paying per call via x402 protocol.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@SuVerse MCP Server Parse the rate con at ~/Downloads/load_4471.pdf"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@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-serverClaude Desktop Setup
Add to claude_desktop_config.json:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%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.
Related MCP server: biz.nibiashara/shelves
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 |
| $0.10 | Rate confirmation → JSON |
| $0.15 | Bill of Lading / POD → JSON |
| $0.05 | Fuel receipt → JSON (IFTA) |
| $0.07 | IRS W-9 → JSON |
| $0.08 | ACORD 25 COI → JSON |
| $0.25 | Oversize/overweight permit → JSON |
| $0.50 | Truck-legal routing + tolls + POIs |
| $0.10 | Toll estimate for a polyline |
| $0.01 | GPS trip analytics |
| $0.005 | Any of 128 gov services by id |
| $0.01 | CMS Open Payments by NPI |
| $0.01 | FBI crime stats by state/year |
Free (no payment)
Tool | Purpose |
| Discover the 128 |
| Price one or many calls before running them |
| On-chain USDC balance + calls remaining per tool |
| 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 |
| $0.10 | What regime is the crypto market in right now? |
| $0.03 | Can this Solana wallet's trading be trusted or copied? |
| $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_costprices 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_KEYis 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_pathreads are restricted to your home directory (override withSUVERSE_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 |
| — | Required. 0x Base private key. |
|
| |
|
| Hard per-call ceiling. |
| viem default | For |
|
| Allow |
|
| 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
Available Tools
19 toolsfreight_calculate_tollsB
Estimate tolls for a known route polyline given axle count and vehicle height. Cost: $0.10 USDC per call.
Inputs: polyline (required), axles, height_ft, toll_maneuvers.
freight_parse_bol_podA
Parse a Bill of Lading / Proof of Delivery (PDF or text) into structured JSON. Cost: $0.15 USDC per call.
Inputs: mode, text, file_path, pdf_base64.
freight_parse_fuel_receiptA
Parse a fuel receipt (text, PDF, or image) into structured JSON for IFTA / expense tracking. Cost: $0.05 USDC per call.
Inputs: mode, text, file_path, pdf_base64, +1 more.
freight_parse_insurance_certA
Parse an ACORD 25 Certificate of Insurance (text, PDF, or image) into structured JSON. Cost: $0.08 USDC per call.
Inputs: mode, text, file_path, pdf_base64, +1 more.
freight_parse_permitA
Parse an oversize/overweight trucking permit (PDF or image) into structured JSON across 22 US states. Cost: $0.25 USDC per call.
Inputs: text, files, file_path, pdf_base64.
freight_parse_rateconA
Parse a freight rate confirmation (PDF or text) into structured JSON: load #, broker, rate, pickup/delivery stops, equipment. Cost: $0.10 USDC per call.
Inputs: mode, text, file_path, pdf_base64.
freight_parse_w9A
Parse an IRS Form W-9 (text, PDF, or image) into structured vendor-onboarding JSON. Cost: $0.07 USDC per call.
Inputs: mode, text, file_path, pdf_base64, +1 more.
freight_trip_telematicsA
Compute trip analytics (distance, idle, harsh events, fuel burn) from an array of GPS pings. Cost: $0.01 USDC per call.
Inputs: pings (required), options.
freight_truck_routeA
Truck-legal routing between origin and destination with tolls, weigh stations, truck stops, and turn-by-turn maneuvers. Cost: $0.50 USDC per call.
Inputs: origin (required), destination (required), truck, via_points, +2 more.
gov_cms_open_paymentsB
CMS Open Payments — industry payments to a physician by NPI and year (params: physician_npi, year). Cost: $0.01 USDC per call.
Inputs: physician_npi (required), year.
gov_fbi_crime_dataB
FBI Crime Data Explorer — offense counts by state and year range (params: state, offense, from_year, to_year). Cost: $0.01 USDC per call.
Inputs: state (required), offense, to_year, from_year.
gov_list_servicesA
List all SuVerse government services callable via gov_query (id, category, description, params). FREE — no payment.
Inputs: category.
gov_queryA
Call any of SuVerse's 128 US-government data/search services by id (e.g. sec.company_info, nps.parks). Use gov_list_services to discover ids + their params. Cost: $0.005000 USDC per call.
Inputs: service (required), params.
suverse_balanceA
Read the configured Base wallet's on-chain USDC balance and how many calls remain for each tool at that balance. FREE — no payment.
Inputs: no named parameters.
suverse_estimate_costA
Estimate the USDC cost of one or more tool calls WITHOUT paying. Useful before batch operations. FREE — no payment.
Inputs: tool, calls.
suverse_market_pulseA
Answers: what regime is the crypto market in right now — is smart money accumulating or distributing relative to sentiment? The verdict is one of accumulation_on_fear, capitulation, confirmed_rally, late_stage_caution with a plain-language summary and confidence, built from the fear/greed index crossed with tracked smart-money netflow, trending coins checked against smart-money buying, BTC 24h move, and high-conviction Polymarket positioning (signals + raw data included). Cost: $0.10 USDC per call via x402; this tool does not pay — without payment_signature it returns the price and the 402 payment instructions. Note: the smart-money/elite-flow layer tracks Solana wallets (production); Base coverage is beta.
Inputs: payment_signature.
suverse_search_endpointsA
Search every paid x402 endpoint SuVerse knows about (its own + everything mirrored from CDP Bazaar + future catalogs). Returns the best matches with URL, price, accepted networks, and quality signals. FREE — no payment.
Inputs: q (required), sort, limit, offset, +2 more.
suverse_token_checkA
Answers: is this Solana token sane to enter right now? The verdict contains a risk level with flags from exit cost (a real $500 sell quote), top-10 holder concentration with pools excluded, token age, mint/freeze authority checks, 24h momentum, and whether tracked elite smart-money wallets bought or sold it in the last 30 days. Cost: $0.05 USDC per call via x402; this tool does not pay — without payment_signature it returns the price and the 402 payment instructions. Note: the elite-flow signal exists for Solana only and most tokens have zero elite touches; the verdict then rests on the safety and liquidity checks alone.
Inputs: token (required), payment_signature.
suverse_wallet_reputationA
Answers: can this Solana wallet's trading be trusted or copied? The verdict contains a skill tier (elite | skilled | average | weak | unknown), an activity class, trading-style flags, 24h/7d/30d trade stats, and recent classified trades — on-chain data only. Cost: $0.03 USDC per call via x402; this tool does not pay — without payment_signature it returns the price and the 402 payment instructions. Note: skill tiers come from SuVerse's elite-flow tracking layer, which exists for Solana only; a wallet it has never indexed returns tier 'unknown', not an error.
Inputs: wallet (required), payment_signature.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Most tools have clear, distinct purposes, especially within the freight parse family where each handles a specific document type. However, there is some overlap potential between gov_query and the specific gov_cms_open_payments / gov_fbi_crime_data tools, which may confuse agents about which to use. Overall, tools are distinguishable.
The server uses a prefix system (freight_, gov_, suverse_) but the verb-noun pattern is inconsistent across tools. For example, freight_parse_bol_pod and gov_list_services follow verb_noun, while freight_truck_route, gov_cms_open_payments, and suverse_market_pulse are noun-based. The naming is readable but mixes conventions.
With 19 tools, the server is slightly heavy but justified given its multi-domain scope: freight processing, government data access, and crypto analytics. Each tool serves a distinct function and the count remains manageable. It is not excessive enough to be overwhelming.
The tool surface covers the main workflows for its three core domains: freight document parsing and routing, government data querying, and SuVerse crypto intelligence plus payment management. Minor gaps exist, such as no tool for load posting or transaction simulation, but these are not core to the server's apparent purpose. Overall, the coverage is solid.
Maintenance
Related MCP Connectors
Pay-per-use tool API for AI agents. Free tier, x402 USDC micropayments, or API key.
17 pay-per-call web, finance, legal and onchain tools for AI agents. USDC on Base via x402/MPP.
Pay-per-call web, email, domain, security, code & image tools for AI agents. USDC on Base (x402).
Pay-per-call tools for autonomous agents, settled in USDC on Base via x402.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceProvides supply chain and shipping tools including shipment tracking, route optimization, warehouse inventory management, delivery ETA estimation, and customs documentation. Enables logistics operations through natural language interactions with Claude.2 npm48 PyPI1MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to run pay-per-call checks on US freight carriers and brokers, OFAC sanctions lists, and African FX rates using x402 micropayments or a prepaid pass without an API key.22 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables Claude to autonomously purchase business location data and pay for it with USDC on Base via x402, while enforcing per-call and per-session spending limits.MIT
- AlicenseAqualityCmaintenanceEnables agents to call paid utilities for DNS/SSL checks, site status, summarization, keyphrase extraction, decision advice, data cleanup, claim verification, and grounding via per-call USDC payments over x402, with free discovery tools and no signup or API key.10MIT