{
  "markdown": "# Rhumb\n\n[![npm version](https://img.shields.io/npm/v/rhumb-mcp)](https://www.npmjs.com/package/rhumb-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![MCP Registry](https://img.shields.io/badge/MCP-Registry-green)](https://registry.modelcontextprotocol.io/v0/servers?search=rhumb)\n\n**Index ranks. Resolve routes.** Rhumb is an agent gateway for external tools: Index scores and compares services; Resolve routes supported capability calls through governed execution rails with receipts.\n\n🌐 [rhumb.dev](https://rhumb.dev) · ⚡ [Quickstart](https://rhumb.dev/quickstart) · 🧭 [Resolve](https://rhumb.dev/resolve) · 💵 [Pricing](https://rhumb.dev/pricing) · 📊 [Leaderboard](https://rhumb.dev/leaderboard) · 📖 [Methodology](https://rhumb.dev/methodology) · 🔑 [Trust](https://rhumb.dev/trust)\n\n> **For agents:** See [`llms.txt`](llms.txt) for machine-readable documentation and [`agent-capabilities.json`](agent-capabilities.json) for structured capability metadata.\n\n---\n\n## Start in 30 seconds\n\n### MCP (recommended)\n\n```bash\nnpx -y --package rhumb-mcp@latest rhumb-mcp\n```\n\nZero config. Discovery tools work immediately — no signup, no governed API key.\n\nFor execution, pass your governed API key:\n\n```bash\nRHUMB_API_KEY=your_key npx -y --package rhumb-mcp@latest rhumb-mcp\n```\n\n[Get a governed API key →](https://rhumb.dev/auth/login)\n\n### API (read-only, no auth)\n\n```bash\ncurl \"https://api.rhumb.dev/v1/services/stripe/score\"\n\n# See supported execution routes before you execute\ncurl \"https://api.rhumb.dev/v1/capabilities/email.send/resolve\"\n```\n\nAll read endpoints are public, including Resolve readiness checks. Estimate and execute require an authenticated payment path.\n\n---\n\n## What Rhumb does\n\nUse Rhumb Index when an agent needs to discover and evaluate services. Use Rhumb Resolve when the task is on a supported capability path and you want governed execution with an explicit receipt.\n\nAgents need external tools. Choosing the right one is hard — not because of feature lists, but because of:\n\n- auth and signup friction\n- provisioning reality vs. marketing claims\n- schema instability\n- failure recovery when no human is watching\n- hidden costs and rate limits\n\nRhumb makes those constraints visible before you commit.\n\n### Best fit today\n\nRhumb is strongest today for **research, extraction, generation, and narrow enrichment**.\n\nTreat broader multi-system business automation as future scope, not the current launch promise. Use Layer 2 capabilities for real work now, and treat Layer 3 as beta with an intentionally sparse public catalog.\n\n<!-- GENERATED:README_PRODUCT_SURFACE_START -->\n### Rhumb Index — Discover & Evaluate\n\n**1,038 scored services** across 50+ domains. Each gets an [AN Score](https://rhumb.dev/methodology) (0–10) measuring execution quality, access readiness, and agent autonomy support.\n\n- `find_services` — Search indexed Services by what you need them to do\n- `get_score` — Get the full AN Score breakdown for a Service: execution quality, access readiness, autonomy level, tier label, and freshness\n- `get_alternatives` — Find alternative Services, ranked by AN Score\n- `get_failure_modes` — Get known failure patterns, impact severity, and workarounds for a service\n- `discover_capabilities` — Browse Capabilities by domain or search text\n- `resolve_capability` — Given a Capability ID, and optionally a credential mode, returns ranked providers with health status, cost per call, auth methods, endpoint patterns, execute guidance, and machine-readable recovery fields like recovery_hint.resolve_url, recovery_hint.credential_modes_url, and, when applicable, recovery_hint.alternate_execute_hint or recovery_hint.setup_handoff, plus typo recovery when the capability ID is wrong\n\n> Discovery breadth is wider than current execution coverage. The index is broader than what Rhumb can execute today.\n\n### Rhumb Resolve — Execute\n\n**415 capability definitions** across **16 callable providers today**. Resolve chooses the best-fit supported provider for the call using AN Score, availability / circuit state, estimated cost, latency proxy, credential mode, and explicit policy constraints.\n\n- `execute_capability` — Call a Capability through Rhumb Resolve\n- `resolve_capability` — Given a Capability ID, and optionally a credential mode, returns ranked providers with health status, cost per call, auth methods, endpoint patterns, execute guidance, and machine-readable recovery fields like recovery_hint.resolve_url, recovery_hint.credential_modes_url, and, when applicable, recovery_hint.alternate_execute_hint or recovery_hint.setup_handoff, plus typo recovery when the capability ID is wrong\n- `estimate_capability` — Estimate the active execution rail, cost, and health before a Capability call; anonymous direct system-of-record paths also preserve machine-readable execute_readiness handoffs\n- `get_receipt` — Retrieve an execution receipt by ID\n- Budget enforcement, credential management, and execution telemetry included\n\n> Best current fit: research, extraction, generation, and narrow enrichment. Treat general business-agent automation and broad multi-system orchestration as future scope, not the current launch promise.\n<!-- GENERATED:README_PRODUCT_SURFACE_END -->\n\n### Repository visibility map\n\n| Surface | What it is for | Current honest boundary |\n|---------|----------------|-------------------------|\n| **Rhumb Index** | Free service discovery, AN Score lookup, alternatives, and failure-mode research | Broad discovery is not the same as execution readiness |\n| **Rhumb Resolve** | Governed execution for supported capabilities with estimates, receipts, budgets, and telemetry | 18 runtime-callable providers today; best fit is research, extraction, generation, and narrow enrichment |\n| **MCP package** | Agent-native entry point for Claude, Cursor, and other MCP clients | Discovery works without auth; execution needs a governed key, wallet-prefund, or x402 where supported |\n| **API** | Public read endpoints plus authenticated execution endpoints | Use current API responses as source of truth for readiness and callable coverage |\n\n### Three credential paths\n\n| Path | How it works |\n|------|-------------|\n| **Rhumb-managed** | Rhumb holds the credential — zero setup for the agent |\n| **BYOK** | Bring your own provider API key. Rhumb routes, you authenticate |\n| **Agent Vault** | Your key, encrypted and stored — Rhumb injects at call time |\n\n### Payment paths\n\n- **Governed API key** — sign up, get a key, prepaid credits\n- **x402 / USDC** — no signup, pay per call on-chain\n\n### Resolve mental model\n\n- **Service** = vendor Rhumb evaluates and compares\n- **Capability** = executable action like `email.send`\n- **Recipe** = deterministic multi-step workflow on top of capabilities (beta, sparse public catalog)\n- **Layer 2 is the default path** — start with governed API key or wallet-prefund on `X-Rhumb-Key`, discover a Service, choose a Capability, estimate, then execute\n- **Start with managed superpowers first** — bring BYOK or Agent Vault only when the workflow touches your own systems\n- **Default auth for repeat traffic** = governed API key or wallet-prefund on `X-Rhumb-Key`\n- **Bring BYOK or Agent Vault** only when provider control is the point\n- **Use x402** when zero-signup per-call payment matters more than repeat throughput\n\nCanonical onboarding map: <https://rhumb.dev/docs#resolve-mental-model>\n\n---\n\n## MCP tools\n\n<!-- GENERATED:README_MCP_TOOLS_START -->\n`rhumb-mcp` exposes **21 tools**:\n\n**Discovery**\n- `find_services` — Search indexed Services by what you need them to do\n- `get_score` — Get the full AN Score breakdown for a Service: execution quality, access readiness, autonomy level, tier label, and freshness\n- `get_alternatives` — Find alternative Services, ranked by AN Score\n- `get_failure_modes` — Get known failure patterns, impact severity, and workarounds for a service\n- `discover_capabilities` — Browse Capabilities by domain or search text\n- `resolve_capability` — Given a Capability ID, and optionally a credential mode, returns ranked providers with health status, cost per call, auth methods, endpoint patterns, execute guidance, and machine-readable recovery fields like recovery_hint.resolve_url, recovery_hint.credential_modes_url, and, when applicable, recovery_hint.alternate_execute_hint or recovery_hint.setup_handoff, plus typo recovery when the capability ID is wrong\n\n**Execution**\n- `execute_capability` — Call a Capability through Rhumb Resolve\n- `estimate_capability` — Estimate the active execution rail, cost, and health before a Capability call; anonymous direct system-of-record paths also preserve machine-readable execute_readiness handoffs\n- `credential_ceremony` — Get step-by-step instructions to obtain API credentials for a Service\n- `check_credentials` — Inspect live credential-mode readiness, globally or for a specific Capability\n- `rhumb_list_recipes` — List the current published Rhumb Layer 3 recipe catalog\n- `rhumb_get_recipe` — Get the full published definition for a Rhumb recipe, including input/output schemas and step topology\n- `rhumb_recipe_execute` — Execute a published Rhumb Layer 3 recipe once one is live in the public catalog\n- `get_receipt` — Retrieve an execution receipt by ID\n\n**Billing**\n- `budget` — Check or set your call spending limit\n- `spend` — Get your spending breakdown for a billing period: total USD spent, call count, average cost per call, broken down by Capability and by provider\n- `check_balance` — Check your current Rhumb credit balance in USD\n- `get_payment_url` — Get a checkout URL to add credits to your Rhumb balance\n- `get_ledger` — Get your billing history: charges (debits), top-ups (credits), and auto-reload events\n\n**Operations**\n- `routing` — Get or set how Rhumb auto-selects providers when you don't specify one in execute_capability\n- `usage_telemetry` — Get your execution analytics — calls, latency, errors, costs, and provider health for your Rhumb usage\n\n> Discovery spans 1,038 scored services, but current governed execution spans 16 callable providers.\n\n> Note: Layer 3 recipe tooling is live, but the public catalog can still be empty. Use `rhumb_list_recipes` or visit `/recipes` before assuming a workflow exists.\n\n> Best current fit: research, extraction, generation, and narrow enrichment. Treat general business-agent automation as future scope, not the current launch promise.\n<!-- GENERATED:README_MCP_TOOLS_END -->\n\n---\n\n## API\n\nBase URL: `https://api.rhumb.dev/v1`\n\n| Endpoint | Auth | Purpose |\n|----------|------|---------|\n| `GET /services/{slug}/score` | No | Score breakdown |\n| `GET /services/{slug}` | No | Service profile + metadata |\n| `GET /services/{slug}/failures` | No | Known failure modes |\n| `GET /search?q=...` | No | Search services |\n| `GET /leaderboard/{category}` | No | Category rankings |\n| `GET /capabilities` | No | Capability registry |\n| `GET /capabilities/{id}/resolve` | No | Ranked providers + explicit `recovery_hint.*` fields |\n| `POST /capabilities/{id}/execute` | Yes | Execute a capability |\n| `GET /capabilities/{id}/execute/estimate` | Yes | Cost estimate |\n| `GET /telemetry/provider-health` | No | Provider health status |\n| `GET /telemetry/usage` | Yes | Your usage analytics |\n| `GET /pricing` | No | Machine-readable pricing |\n\n---\n\n## Examples\n\nSee [`examples/`](examples/) for runnable scripts:\n\n| Example | What it shows | Auth needed? |\n|---------|--------------|-------------|\n| [discover-and-evaluate.py](examples/discover-and-evaluate.py) | Search → Score → Failure modes | No |\n| [resolve-and-execute.py](examples/resolve-and-execute.py) | Resolve → machine-readable recovery handoff → Estimate → Execute | No for resolve, yes for estimate/execute |\n| [budget-aware-routing.py](examples/budget-aware-routing.py) | Budget + cost-optimal routing | Yes |\n| [dogfood-telemetry-loop.py](examples/dogfood-telemetry-loop.py) | Repeatable Resolve → telemetry verification loop | Yes |\n| [mcp-quickstart.md](examples/mcp-quickstart.md) | MCP setup for Claude, Cursor, etc. | Optional |\n\n```bash\n# Try discovery right now (no auth needed)\npip install httpx && python examples/discover-and-evaluate.py\n\n# Try the resolve walkthrough right now (no auth needed for resolve)\npython examples/resolve-and-execute.py\n```\n\n`resolve-and-execute.py` will still show the ranked providers plus any machine-readable recovery handoff Rhumb already identified. Set `RHUMB_API_KEY` only when you want to continue into estimate and execute.\n\n---\n\n## Docs\n\n- [Agent Accessibility Guidelines](docs/AGENT-ACCESSIBILITY-GUIDELINES.md) — making web interfaces usable by AI agents\n- [AN Score Methodology](docs/AN-SCORE-V2-SPEC.md) — scoring dimensions, weights, and rubrics\n- [Architecture](docs/ARCHITECTURE.md) — scoring engine design\n- [API Reference](docs/API.md) — endpoint details\n- [Repo Boundary](docs/REPO-BOUNDARY.md) — what stays public here vs. what lives in the private ops workspace\n- [Security Policy](SECURITY.md) — vulnerability reporting and security architecture\n\n---\n\n## Repo structure\n\n```\nrhumb/\n├── packages/\n│   ├── api/         # Python API (Railway)\n│   ├── astro-web/   # Public website (Vercel)\n│   ├── mcp/         # MCP server (npm)\n│   ├── cli/         # CLI tooling\n│   └── shared/      # Shared types/constants\n├── examples/        # Runnable examples\n├── docs/            # Public documentation only\n├── scripts/         # Product tooling + verification scripts\n├── artifacts/       # Curated public datasets only (raw proof outputs stay local/private)\n├── llms.txt         # Machine-readable docs for agents\n└── agent-capabilities.json  # Structured capability manifest\n```\n\n---\n\n## Development\n\n```bash\n# API\ncd packages/api && pip install -r requirements.txt && uvicorn app:app --reload\n\n# MCP\ncd packages/mcp && npm ci && npm run dev\n\n# Web\ncd packages/astro-web && npm ci && npm run dev\n```\n\nNode 24+ recommended (`.nvmrc` included).\n\n---\n\n## Score disputes\n\nEvery score is disputable. If you believe a score is inaccurate:\n\n1. Read the public provider guide at [rhumb.dev/providers](https://rhumb.dev/providers)\n2. [Open the score-dispute GitHub template](https://github.com/supertrained/rhumb/issues/new?template=score-dispute.md) with evidence\n3. Or email [providers@supertrained.ai](mailto:providers@supertrained.ai?subject=Score%20Dispute) for a private path\n\nWe target an initial response within 5 business days. Negative findings remain visible. Rhumb does not accept payment to change scores.\n\n---\n\n## Links\n\n- **Website:** [rhumb.dev](https://rhumb.dev)\n- **npm:** [rhumb-mcp](https://www.npmjs.com/package/rhumb-mcp)\n- **MCP Registry:** [Rhumb on MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=rhumb)\n- **X:** [@pedrorhumb](https://x.com/pedrorhumb)\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 14831,
  "sha": "734514804ba119965b9712a9c5e94f38240d9c786166bdcd8432c3d55549f9ff",
  "repo_slug": "supertrained/rhumb",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_supertrained_rhumb_mcp_3c92c150/readme"
}