Skip to the content

DocsStart

Use from a coding agent

Install Rhumb in Claude Code or another coding agent: the MCP server and the rhumb skill, so it asks which model to call and what an agent connects.

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.

Install in Claude Code

Two parts, and either works without the other: the MCP server gives Claude the tools, and the rhumb skill tells it when to ask and what to do with the answer. With both, you ask in your own words while you build and the decision comes from the catalog.

  1. A key. Create an account, which is free, make a key under API keys and put it in your shell as RHUMB_KEY.
  2. The server. Add it with the key in a header. Add --scope user to have it in every project, and check it with claude mcp list.
    bash
    claude mcp add --transport http rhumb https://rhumbdata.com/v1/mcp \
      --header "Authorization: Bearer $RHUMB_KEY"
  3. The skill. A folder, rhumb.tar.gz (SKILL.md and its references), unpacked into a folder named rhumb where Claude Code reads skills: your own, for every project,
    bash
    mkdir -p ~/.claude/skills/rhumb
    curl -fsS https://rhumbdata.com/.well-known/agent-skills/rhumb.tar.gz \
      | tar -xz -C ~/.claude/skills/rhumb
    or the project's, to commit it for everyone who works there:
    bash
    mkdir -p .claude/skills/rhumb
    curl -fsS https://rhumbdata.com/.well-known/agent-skills/rhumb.tar.gz \
      | tar -xz -C .claude/skills/rhumb

Start a new session. /mcp shows the server, and the skill loads by itself when a question is one it covers.

What to ask

You askClaude calls
Which model should the summaries in this app use, on the providers I have? Keep it cheap.resolve
What does that model cost on OpenRouter, and which id does it expect there?get_model
I'm building an agent for Linear and GitHub. What should it connect to?stack
It runs code and searches the web. What does it run on, and what does that cost? We already use E2B.stack

Claude finds your providers in the project (the names of its environment variables and its SDKs, never a key's value), states the need, and shows you the model's id on that provider, its price and the reason before writing it into code.

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. Any client that connects to a remote server with a header can use it; in a project's .mcp.json:

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

Tools

ToolWhat it answersCounts
resolveWhich 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
planReads a description of the work (a prompt, tags, attachment types) into a need, then resolves it. The same as POST /v1/plan.5 calls
stackFor the systems an agent works with: each one's own MCP server or command-line tool, a model, warnings, a config to start from, and an address the user can open to be emailed when the stack changes. The same as POST /v1/stack.1 call
platformWhere an app's agent runs: whether a major platform is warranted or any host will do, what a host must meet, and the hosts ruled out with their own pages' words. The same as POST /v1/platform.1 call
list_modelsThe catalog's models with offerings, prices and capabilities, 20 to a page unless asked otherwise. The same as GET /v1/models.1 call
get_modelOne model: every provider's offering, its price history and scores. The same as GET /v1/models/{id}.1 call
list_purposesThe purpose presets resolve accepts. The same as GET /v1/purposes.Free
list_goalsThe goals an answer depends on, each with its question, options and parameters. The same as GET /v1/goals.Free
get_vocabularyEvery 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.

Prompts

For an agent that has the server and not the skill, the server also offers a prompt. Prompts are free and need no key.

  • plan_app: The planning checklist, the goals and the rules for asking, for an agent that has the server and not the skill.

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 free tools, connecting, and listing the tools and prompts 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.

While you plan an app

Your agent plans the app with you: it writes the brief, asks you what it needs and orders the work. Rhumb does not take any of that over. The agent calls it at the decisions it has dated facts for: which model each feature uses (resolve), what an agent connects to and runs on (stack).

Each answer depends on the app's goals: what a feature may cost, how hard its work is, where a model's maker may be based, the kind of data it handles and the accounts you already hold. The skill has the agent find them in your plan, then your repository, then the conversation, and ask you only what none of them answers, one question at a time and no more than five in a session. A planning session for an app with four model features and two agents is about eight calls; on the Free plan the agent makes them one after another and waits when told to.

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; and, for an agent that works with named systems, when to call stack and what to show you from its answer. It also says what Rhumb does not answer, and how to connect the server when it is missing.

It is a folder: SKILL.md, which an agent reads first, and two references it reads when it plans: the goals and their questions, written from the same list as the Goals page, and the order of calls in a planning session. It is published as one archive, installed as above. Claude Code reads a project's skills from .claude/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.

Other servers and skills

Rhumb's own tools answer which model to call and, with stack, what to connect for each system. For the systems your agent works with, the directory lists the MCP servers, command-line tools and vendor skills by system, with who publishes each and what is known about it. See how it is made.

To have the choice made by fixed rules instead of reading the lists, the stack tool (POST /v1/stack) takes the systems and where the agent runs and answers each system's own server or command-line tool, a model, warnings and a .mcp.json to start from. See Stacks.

What changes after an answer is in the log, and an agent that can fetch a page can read it as Atom: /feeds/today.atom for everything, or /feeds/systems/<system>.atom for one system (linear, github). A stack answer's watch_url is for the user, not the agent: a person opens it and presses Watch to be emailed when the stack changes.

What reaches Rhumb

Provider names, a task or purpose, and constraints; for plan, also tags and a prompt when the agent sends one; for stack, the names of the systems, where the agent runs, its harness and what it does. Never your provider keys or a system's key, 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.