x402score-mcp

x402score-mcp

MCP server exposing x402Score's reputation data as agent tools — check an x402-paid API endpoint's trust score before paying it, from inside any MCP-compatible client (Claude Desktop, Claude Code, etc.).

Published to npm, not yet submitted to any MCP registry. The package itself (x402score-mcp) is installable now — what's being held is the registry listing (Claude's, Smithery, etc.), until the on-chain modifier's calibration gate closes (~2026-10-19); see the main project README for why. Registry listing content is pre-written in REGISTRY_SUBMISSION.md, ready to copy-paste the moment the gate closes. Last re-verified end-to-end against live production (real stdio MCP client, all 5 tools + the methodology resource, confirmed structured output, error handling, and tool annotations all work correctly): 2026-10-10.

Tools

• check_endpoint_score — score, grade, and credible interval for one endpoint. Pass url directly (preferred — the endpointId is derived locally, no separate lookup) or endpointId if already known.
• search_leaderboard — search/browse tracked endpoints by name/domain/url/id and/or vertical, sortable by score (default), price, uptime, or latency.
• get_calibration_report — is the scoring formula actually predictive?
• submit_endpoint — add a new x402 endpoint to the monitoring queue.
• ping — cheap reachability/latency check, useful as a first call when connecting.

All tools declare readOnlyHint/destructiveHint/idempotentHint/openWorldHint annotations and a matching outputSchema, and all return structured errors (isError: true with a clear message, including the backend's own error text where available — e.g. a rate-limit message, not just an HTTP status) instead of letting a network failure or backend timeout kill the connection. A x402score://methodology resource explains what the score, grade, credible interval, and on-chain modifier actually mean — read once per session rather than inferred from tool descriptions alone. Requests time out client-side after 10s so a slow or degraded backend fails fast and visibly instead of hanging the caller. See CHANGELOG.md for the version history.

Install & run

npm install -g x402score-mcp
x402score-mcp

Or from source:

cd mcp && npm install && npm run build
npm start

Use from Claude Desktop / Claude Code

Add to your MCP client config:

{
  "mcpServers": {
    "x402score": {
      "command": "npx",
      "args": ["-y", "x402score-mcp"]
    }
  }
}

Or point command/args at a local node/dist/server.js build instead, same as before.

Optionally set X402SCORE_BASE_URL in the server's env to point at a local wrangler dev or staging deployment instead of production. This redirects all of the server's traffic to whatever URL you give it, so only set it to a backend you control and trust.

Development

Tool logic (src/tools.ts) is separated from MCP protocol wiring (src/server.ts) specifically so it's testable without a real MCP transport — tests run via the main project's vitest (from the repo root: npm test). src/server.ts wires those same functions into @modelcontextprotocol/sdk's McpServer, connected over stdio.