Rhumb MCP

Official

by supertrained · Python

Agent gateway for Index discovery, AN Score evaluation, and Resolve governed execution

Gateway for index discovery, evaluation scoring, and governed agent execution.

Topics

agent-nativeai-agentsapi-scoringdeveloper-toolsmcptool-discoveryan-scoreapi-evaluationagent-gatewaygoverned-executionmcp-registrymodel-context-protocol

README.md15 KBView on GitHub

Rhumb

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.

🌐 rhumb.dev · ⚡ Quickstart · 🧭 Resolve · 💵 Pricing · 📊 Leaderboard · 📖 Methodology · 🔑 Trust

For agents: See llms.txt for machine-readable documentation and agent-capabilities.json for structured capability metadata.

Start in 30 seconds

MCP (recommended)

bash

npx -y --package rhumb-mcp@latest rhumb-mcp

Zero config. Discovery tools work immediately — no signup, no governed API key.

For execution, pass your governed API key:

bash

RHUMB_API_KEY=your_key npx -y --package rhumb-mcp@latest rhumb-mcp

Get a governed API key →

API (read-only, no auth)

bash

curl "https://api.rhumb.dev/v1/services/stripe/score"

# See supported execution routes before you execute
curl "https://api.rhumb.dev/v1/capabilities/email.send/resolve"

All read endpoints are public, including Resolve readiness checks. Estimate and execute require an authenticated payment path.

What Rhumb does

Use 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.

Agents need external tools. Choosing the right one is hard — not because of feature lists, but because of:

auth and signup friction
provisioning reality vs. marketing claims
schema instability
failure recovery when no human is watching
hidden costs and rate limits

Rhumb makes those constraints visible before you commit.

Best fit today

Rhumb is strongest today for research, extraction, generation, and narrow enrichment.

Treat 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.

Rhumb Index — Discover & Evaluate

1,038 scored services across 50+ domains. Each gets an AN Score (0–10) measuring execution quality, access readiness, and agent autonomy support.

find_services — Search indexed Services by what you need them to do
get_score — Get the full AN Score breakdown for a Service: execution quality, access readiness, autonomy level, tier label, and freshness
get_alternatives — Find alternative Services, ranked by AN Score
get_failure_modes — Get known failure patterns, impact severity, and workarounds for a service
discover_capabilities — Browse Capabilities by domain or search text
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

Discovery breadth is wider than current execution coverage. The index is broader than what Rhumb can execute today.

Rhumb Resolve — Execute

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.

execute_capability — Call a Capability through Rhumb Resolve
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
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
get_receipt — Retrieve an execution receipt by ID
Budget enforcement, credential management, and execution telemetry included

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.

Repository visibility map

Surface	What it is for	Current honest boundary
Rhumb Index	Free service discovery, AN Score lookup, alternatives, and failure-mode research	Broad discovery is not the same as execution readiness
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
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
API	Public read endpoints plus authenticated execution endpoints	Use current API responses as source of truth for readiness and callable coverage

Three credential paths

Path	How it works
Rhumb-managed	Rhumb holds the credential — zero setup for the agent
BYOK	Bring your own provider API key. Rhumb routes, you authenticate
Agent Vault	Your key, encrypted and stored — Rhumb injects at call time

Payment paths

Governed API key — sign up, get a key, prepaid credits
x402 / USDC — no signup, pay per call on-chain

Resolve mental model

Service = vendor Rhumb evaluates and compares
Capability = executable action like email.send
Recipe = deterministic multi-step workflow on top of capabilities (beta, sparse public catalog)
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
Start with managed superpowers first — bring BYOK or Agent Vault only when the workflow touches your own systems
Default auth for repeat traffic = governed API key or wallet-prefund on X-Rhumb-Key
Bring BYOK or Agent Vault only when provider control is the point
Use x402 when zero-signup per-call payment matters more than repeat throughput

Canonical onboarding map: https://rhumb.dev/docs#resolve-mental-model

MCP tools

rhumb-mcp exposes 21 tools:

Discovery

find_services — Search indexed Services by what you need them to do
get_score — Get the full AN Score breakdown for a Service: execution quality, access readiness, autonomy level, tier label, and freshness
get_alternatives — Find alternative Services, ranked by AN Score
get_failure_modes — Get known failure patterns, impact severity, and workarounds for a service
discover_capabilities — Browse Capabilities by domain or search text
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

Execution

execute_capability — Call a Capability through Rhumb Resolve
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
credential_ceremony — Get step-by-step instructions to obtain API credentials for a Service
check_credentials — Inspect live credential-mode readiness, globally or for a specific Capability
rhumb_list_recipes — List the current published Rhumb Layer 3 recipe catalog
rhumb_get_recipe — Get the full published definition for a Rhumb recipe, including input/output schemas and step topology
rhumb_recipe_execute — Execute a published Rhumb Layer 3 recipe once one is live in the public catalog
get_receipt — Retrieve an execution receipt by ID

Billing

budget — Check or set your call spending limit
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
check_balance — Check your current Rhumb credit balance in USD
get_payment_url — Get a checkout URL to add credits to your Rhumb balance
get_ledger — Get your billing history: charges (debits), top-ups (credits), and auto-reload events

Operations

routing — Get or set how Rhumb auto-selects providers when you don't specify one in execute_capability
usage_telemetry — Get your execution analytics — calls, latency, errors, costs, and provider health for your Rhumb usage

Discovery spans 1,038 scored services, but current governed execution spans 16 callable providers.

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.

Best current fit: research, extraction, generation, and narrow enrichment. Treat general business-agent automation as future scope, not the current launch promise.

API

Base URL: https://api.rhumb.dev/v1

Endpoint	Auth	Purpose
`GET /services/{slug}/score`	No	Score breakdown
`GET /services/{slug}`	No	Service profile + metadata
`GET /services/{slug}/failures`	No	Known failure modes
`GET /search?q=...`	No	Search services
`GET /leaderboard/{category}`	No	Category rankings
`GET /capabilities`	No	Capability registry
`GET /capabilities/{id}/resolve`	No	Ranked providers + explicit `recovery_hint.*` fields
`POST /capabilities/{id}/execute`	Yes	Execute a capability
`GET /capabilities/{id}/execute/estimate`	Yes	Cost estimate
`GET /telemetry/provider-health`	No	Provider health status
`GET /telemetry/usage`	Yes	Your usage analytics
`GET /pricing`	No	Machine-readable pricing

Examples

See examples/ for runnable scripts:

Example	What it shows	Auth needed?
discover-and-evaluate.py	Search → Score → Failure modes	No
resolve-and-execute.py	Resolve → machine-readable recovery handoff → Estimate → Execute	No for resolve, yes for estimate/execute
budget-aware-routing.py	Budget + cost-optimal routing	Yes
dogfood-telemetry-loop.py	Repeatable Resolve → telemetry verification loop	Yes
mcp-quickstart.md	MCP setup for Claude, Cursor, etc.	Optional

bash

# Try discovery right now (no auth needed)
pip install httpx && python examples/discover-and-evaluate.py

# Try the resolve walkthrough right now (no auth needed for resolve)
python examples/resolve-and-execute.py

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.

Docs

Agent Accessibility Guidelines — making web interfaces usable by AI agents
AN Score Methodology — scoring dimensions, weights, and rubrics
Architecture — scoring engine design
API Reference — endpoint details
Repo Boundary — what stays public here vs. what lives in the private ops workspace
Security Policy — vulnerability reporting and security architecture

Repo structure

code

rhumb/
├── packages/
│   ├── api/         # Python API (Railway)
│   ├── astro-web/   # Public website (Vercel)
│   ├── mcp/         # MCP server (npm)
│   ├── cli/         # CLI tooling
│   └── shared/      # Shared types/constants
├── examples/        # Runnable examples
├── docs/            # Public documentation only
├── scripts/         # Product tooling + verification scripts
├── artifacts/       # Curated public datasets only (raw proof outputs stay local/private)
├── llms.txt         # Machine-readable docs for agents
└── agent-capabilities.json  # Structured capability manifest

Development

bash

# API
cd packages/api && pip install -r requirements.txt && uvicorn app:app --reload

# MCP
cd packages/mcp && npm ci && npm run dev

# Web
cd packages/astro-web && npm ci && npm run dev

Node 24+ recommended (.nvmrc included).

Score disputes

Every score is disputable. If you believe a score is inaccurate:

Read the public provider guide at rhumb.dev/providers
Open the score-dispute GitHub template with evidence
Or email providers@supertrained.ai for a private path

We target an initial response within 5 business days. Negative findings remain visible. Rhumb does not accept payment to change scores.

License

MIT

Install

Configuration

Environment variables

RHUMB_API_KEYsecret

Governed API key for authenticated repeat traffic on X-Rhumb-Key (optional — discovery works without auth; execution otherwise needs x402 payment)

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "rhumb-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "rhumb-mcp@0.8.2"
      ],
      "env": {
        "RHUMB_API_KEY": "<YOUR_RHUMB_API_KEY>"
      }
    }
  }
}

Topics

Rhumb

Start in 30 seconds

MCP (recommended)

API (read-only, no auth)

What Rhumb does

Best fit today

Rhumb Index — Discover & Evaluate

Rhumb Resolve — Execute

Repository visibility map

Three credential paths

Payment paths

Resolve mental model

MCP tools

API

Examples

Docs

Repo structure

Development

Score disputes

Links

License

Install

Configuration