DocsStart

Use from an agent

Connect a coding agent to Rhumb over the Model Context Protocol, and give it the rhumb skill, so it asks which model to call.

A coding agent that writes a model id from memory writes last year's. Connect it to Rhumb and it asks instead: the same answers as the API, as tools the agent calls while it works.

Connect the MCP server

Rhumb is a remote Model Context Protocol server at https://rhumbdata.com/v1/mcp, over Streamable HTTP. It takes the same API key as the rest of the API, in the Authorization header. With your key in RHUMB_KEY, in Claude Code:

bash

claude mcp add --transport http rhumb https://rhumbdata.com/v1/mcp \
  --header "Authorization: Bearer $RHUMB_KEY"

Or in a project's .mcp.json, and the equivalent in any client that connects to a remote server with a header:

.mcp.json

{
  "mcpServers": {
    "rhumb": {
      "type": "http",
      "url": "https://rhumbdata.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${RHUMB_KEY}"
      }
    }
  }
}

Tools

Tool	What it answers	Counts
`resolve`	Which model to call for a need on your providers: one model, a team or an escalation ladder. The same as `GET /v1/resolve`.	1 call
`plan`	Reads a description of the work (a prompt, tags, attachment types) into a need, then resolves it. The same as `POST /v1/plan`.	5 calls
`list_models`	The catalog's models with offerings, prices and capabilities, 20 to a page unless asked otherwise. The same as `GET /v1/models`.	1 call
`get_model`	One model: every provider's offering, its price history and scores. The same as `GET /v1/models/{id}`.	1 call
`list_purposes`	The purpose presets resolve accepts. The same as `GET /v1/purposes`.	Free
`get_vocabulary`	Every task, capability, level and provider name the tools accept. The same as `GET /v1/vocabulary`.	Free

Each tool takes the parameters of its endpoint, described in the API reference. A list may be sent as an array.

How calls are counted

A tool call is the API call it stands for, made with your key: the key's scopes and IP allowlist apply to it, and so does its rate limit. A call that answers counts against your quota as the table says and appears in your usage under its endpoint; the two free tools, connecting and listing the tools count nothing, and the last two need no key.

An error comes back to the agent as the API's own error, so it can tell a missing key from a need nothing meets, and is not counted. no_candidate is returned as an answer, with what ruled every model out, and is not counted either.

The skill

Tools tell an agent what it can call. The rhumb agent skill tells it when to ask and how to turn a request into a need: which providers the project has, a purpose or a task, and what never to send. It is one file:

bash

mkdir -p .claude/skills/rhumb
curl -fsS https://rhumbdata.com/.well-known/agent-skills/rhumb/SKILL.md \
  -o .claude/skills/rhumb/SKILL.md

That folder is where Claude Code reads a project's skills; other agents that support the standard have their own. The site lists its skills, with a digest of each, at /.well-known/agent-skills/index.json.

What reaches Rhumb

Provider names, a task or purpose, and constraints; for plan, also tags and a prompt when the agent sends one. Never your provider keys, and never a file: plan takes an attachment's type and size only.

A prompt sent to plan is handled as on /v1/plan: it goes to the decision model that reads it, OpenAI's by default, and is never stored or logged. decision: { "allow_remote": false }, or the account's “Keep prompts on Rhumb's server” setting, has it read on Rhumb's server only.