{
  "markdown": "# @routescore/mcp\n\n**The read-only pre-sign evidence layer — a \"pre-sign journal\" — for onchain agents.**\n\nBefore an agent (or you) signs a swap onchain, `check_swap` returns a modeled\nread of route quality, MEV/execution exposure, and token-registry recognition as\na `clear / caution / unsupported` verdict with its caveats — and persists a\nhash-verifiable record of exactly what was known before signing, re-verifiable\noffline. That record is the pre-sign journal. It is read-only: it never signs,\nexecutes, routes funds, or custodies assets.\n\nAn [MCP](https://modelcontextprotocol.io) server (and a keyed REST API) for\nClaude, Codex, Cursor, and any MCP-capable agent — a thin, stateless wrapper\naround the Routescore public API, storing no request or response data locally.\n\n**`check_swap` is free.** A free API key runs 100 pre-sign checks/day (Pro\n1,000/day, Power 10,000/day); the modeled premium-estimate tools,\n`simulate_scenario`, and persisted-record *retrieval* are Power-tier. Generate a\nkey at **Account → Developer → API & MCP access** (`/account`) — free to mint on\nany plan. Keys look like `rs_live_…` and are shown once.\n\nSee how these modeled reads have tracked measured on-chain outcomes on the public\n[calibration surface](https://www.routescore.io/calibration) — Routescore\npublishes its own accuracy (Brier score, ECE, coverage), re-derivable from a\nbound source manifest.\n\n## Setup\n\nAdd the server to your MCP client config and set your key in the env block.\n\n**Claude Desktop** (`claude_desktop_config.json`) / **Cursor** (`.cursor/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"routescore\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@routescore/mcp\"],\n      \"env\": {\n        \"ROUTESCORE_API_KEY\": \"rs_live_your_key_here\"\n      }\n    }\n  }\n}\n```\n\n**Claude Code** (CLI):\n\n```bash\nclaude mcp add routescore --env ROUTESCORE_API_KEY=rs_live_... -- npx -y @routescore/mcp\n```\n\nOptional env:\n\n- `ROUTESCORE_API_URL` — override the API base (default `https://www.routescore.io`).\n  Useful for local development: `http://localhost:3000`.\n\nThe server checks the key at startup: if `ROUTESCORE_API_KEY` is missing or\ndoes not match the minted key shape (`rs_live_` followed by 64 lowercase hex\ncharacters), it exits immediately with an actionable error instead of\nfailing on the first tool call. The configured value is never echoed. This\nis a shape check only — real key verification stays server-side (run the\n`whoami` tool).\n\n## Tools\n\n| Tool | What it does |\n|---|---|\n| `quote_mev_cover` | Modeled premium estimate for MEV-sandwich exposure on a swap (modeled premium, expected/CVaR loss). |\n| `quote_bridge_refund` | Modeled premium estimate for cross-chain bridge execution failure vs a modeled SLA expectation. |\n| `quote_lrt_slashing` | Modeled premium estimate for slashing risk on an LRT position given AVS exposure. |\n| `simulate_scenario` | What-if Monte Carlo: modeled expected premium vs refund/loss over a horizon. |\n| `check_swap` | Pre-trade check an agent runs before it signs: modeled route quality, price-impact / slippage band, modeled MEV/execution exposure where observable, and a token registry read (recognized vs unverified), as a `clear / caution / unsupported` verdict. Supports Ethereum (1) and Robinhood Chain (4663). Recognition is not safety, sellability, rights, redemption, liquidity, or investment-quality verification. Decision support, not execution. Every keyed call also attempts to persist a hash-verifiable evidence record and returns its `record_id`, `evidence_bundle_id`, and `record_output_hash` — null, with a `record_persistence_failed` caveat, if the record store is unavailable. |\n| `get_preflight_record` | Fetch one persisted preflight evidence record by `record_id` (owner-scoped to the configured key's account). The record embeds the original check response verbatim plus a canonical-JSON SHA-256 integrity hash so the evidence can be re-verified offline. Read-only evidence: record creation rejects known execution-material keys (calldata, transaction payloads, signing material) and drops identity-shaped labels from the actor context. |\n| `get_detector_manifest` | Latest public MEV-detector run manifest (version hash + universe). |\n| `whoami` | Confirm the key works and report its plan tier. |\n\nAll `quote_*` tool results are **modeled, point-in-time premium estimates** —\ndecision support only, **not** a live cover, insurance, refund, or\npremium-acceptance offer. Routescore does not underwrite risk.\n\n## Output contract\n\nRoutescore MCP is decision support, not execution infrastructure. `check_swap`,\nquote, and scenario tool results preserve the same trust envelope as the REST API, and the\nwrapper marks output as degraded if the upstream API ever omits required trust\nfields.\n\n`check_swap` answers `verdict: unsupported` as an HTTP 422 with a full\nevaluated body — an answer, not an error. The wrapper relays those evaluated\n422 bodies as normal structured tool results (gap-state fields, caveats, and\nrecord linkage included) so agents receive \"not evaluated\" as first-class\nevidence; true errors (400/401/403/404/429/5xx and non-evaluated 422 error\nenvelopes) still surface as tool errors.\n\nDownstream agents and dashboards should render the trust-envelope fields by\ndefault (abbreviated example):\n\n```json\n{\n  \"score_state\": \"partial\",\n  \"source_freshness\": {\n    \"state\": \"partial\",\n    \"checked_at\": \"2026-06-21T00:00:00.000Z\",\n    \"sources\": [\n      { \"name\": \"routescore_backend\", \"freshness_state\": \"fresh\" },\n      { \"name\": \"bridge_risk_labels\", \"freshness_state\": \"unknown\" }\n    ]\n  },\n  \"methodology_version\": \"routescore.public_api.v1\",\n  \"confidence_band\": { \"low\": null, \"high\": null, \"unit\": \"bps\" },\n  \"caveats\": [\n    \"Modeled, point-in-time decision support. Not an execution guarantee.\",\n    \"Unsupported or stale inputs widen uncertainty instead of hiding risk.\"\n  ],\n  \"commercial_disclosure\": {\n    \"paid_placement\": false,\n    \"score_influenced_by_partner\": false\n  }\n}\n```\n\n## Local development\n\n```bash\nnpm install\nnpm run build\nROUTESCORE_API_KEY=rs_live_... ROUTESCORE_API_URL=http://localhost:3000 node dist/index.js\n```\n\nThen point [MCP Inspector](https://github.com/modelcontextprotocol/inspector)\nat the command, or wire it into a client config as above.\n\n### Public Reddit research utility\n\nThe retail-research workflow includes a standard-library parser for a saved,\npublicly rendered old Reddit thread. It extracts public handles, comment counts,\nIDs, and permalinks without logging in or attempting to recover deleted authors:\n\n```bash\npython3 scripts/scrape_reddit_public_handles.py /path/to/thread.html \\\n  --csv work/reddit-public-handles.csv \\\n  --json work/reddit-public-handles.json\n```\n\nThe input must be HTML already obtained from a public `old.reddit.com` thread.\nThe parser does not fetch pages or bypass Reddit access controls.\n\n## Notes\n\n- Scenario and quote outputs are modeled decision-support, **not investment advice**.\n- MCP does not custody assets, execute transactions, route funds, or guarantee\n  outcomes.\n- Rate limits apply per key; responses carry `X-RateLimit-*` headers.\n",
  "bytes": 7121,
  "sha": "dbfe07703b7ca72f9002ae5fb693bef1c14deca131359c15232711593430c34d",
  "repo_slug": "routescore/mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_routescore_mcp_a338f4c1/readme"
}