autorouter

# autorouter

[![CI](https://github.com/Webb-Ventures/autorouter/actions/workflows/ci.yml/badge.svg)](https://github.com/Webb-Ventures/autorouter/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/autorouter-mcp.svg)](https://www.npmjs.com/package/autorouter-mcp)
[![licence: MIT](https://img.shields.io/badge/licence-MIT-blue.svg)](LICENSE)

One tool instead of every tool.

Every MCP server you register injects its full tool list — names, descriptions,
JSON schemas — into the system prompt on every single turn. Five servers and a
handful of skills is routinely 20–30k tokens of permanent overhead, paid whether
or not the task touches any of them. It also makes tool selection _worse_: more
candidates means more mis-picks.

autorouter is an MCP server that exposes a handful of stable tools and hides
everything else behind a search. The model asks for what it needs in natural
language, gets back a few ranked candidates with schemas attached, and calls one
through the router. A tool it actually uses is then promoted into the real tool
list, so the context is spent on what the session needs rather than on what it
might.

```
find_capabilities({ query: "inspect recent deployment errors" })
  → mcp:deployments/get_logs       (tool)
  → mcp:monitoring/search_events   (tool)
  → skill:incident-triage          (skill)

describe_capability({ id: "mcp:deployments/get_logs" })
call_capability({ id: "mcp:deployments/get_logs", arguments: { lines: 50 } })
```

## Install

```sh
npm install -g autorouter-mcp        # or: npx autorouter-mcp <command>
autorouter init --target claude      # claude | codex | cursor | vscode
autorouter adopt --target claude     # ← the step that actually saves context
```

That is a one-time migration of what you already have. New servers do not need
it — see [Adding an MCP server](#adding-an-mcp-server).

**`adopt` is not optional.** Registering the router alongside your existing
servers is a net _increase_: their schemas are still loaded and the router adds
four more tools. `adopt` moves the downstream entries out of the harness config
and into the router's own, so the harness loads one server and the router still
reaches all of them.

MCP servers are not the whole bill. Skills and plugins load through entirely
separate mechanisms — every `SKILL.md` contributes its name and description to
the system prompt, and an enabled plugin contributes its own skills, commands
_and_ servers just by being installed. On Claude Code, `adopt` handles those too,
using the only two levers the harness exposes:

| what    | how                                            | effect                                                  |
| ------- | ---------------------------------------------- | ------------------------------------------------------- |
| skills  | `skillOverrides[name] = "user-invocable-only"` | out of the model's context; `/name` still works for you |
| plugins | `enabledPlugins[id] = false`                   | plugin's skills, commands and servers all stop loading  |

The router still finds all of them — it reads `~/.claude/skills` and
`installed_plugins.json` directly, which record _installation_, not what the
harness has enabled. That is what makes disabling a plugin a move rather than a
deletion.

Two things are refused rather than done quietly. A plugin whose MCP servers the
router cannot reach (usually OAuth, where the harness holds the token and the
router does not) stays enabled — disabling it would take away a server that
currently works. So does a plugin whose servers the router never learned about,
which happens if you drop `"plugins"` from `import`. Both are reported as `skip`
lines with the reason.

Use `--servers-only` to keep the old behaviour, `--skill-mode off` to remove the
slash command as well, and `--keep-skill` / `--keep-plugin` to exempt individual
ones. Codex, Cursor and VS Code have no skill or plugin concept, so there is
nothing extra to do there.

Run `autorouter doctor` to see the difference:

```
## Context cost
  exposing everything: ~87,524 tokens
  router surface:      ~972 tokens
  best case:           ~86,552 tokens saved (99%)

  per harness (a session only ever runs in one):
    codex   still loaded ~35,500 → saves ~51,052 (58%)
    claude, cursor, vscode: fully adopted → saves ~86,552 (99%)

## Not yet adopted
  codex
    servers: project-tools, docs-search, issue-tracker
    → autorouter adopt --target codex
```

"Still loaded" is what adoption removes, and it is reported per harness rather
than summed: a session runs in exactly one, so a server still registered in Codex
costs a Claude Code session nothing. Every removal is backed up verbatim to
`~/.autorouter/adopted/` before anything is written;
`autorouter restore --target claude` puts it back byte for byte.

## How it finds things

Retrieve, then rerank.

1. **BM25** over every capability, always on, no dependencies. The tokenizer
   splits camelCase and snake_case (`get_user` → `get`, `user`, `getuser`)
   and boosts fields: name ×3, keywords ×2, description ×1, schema ×0.5.
2. **Embeddings**, optional. Voyage or OpenAI; scores are min-max normalized and
   fused `0.5 × bm25 + 0.5 × cosine`. An absent or unreachable provider is not an
   error — it degrades to pure lexical.
3. **A selector model** reranks the shortlist. It should be the cheapest model in
   whichever harness you are using, so `init` asks which one when it cannot infer
   it, and stores the answer in that harness's own server entry.

### The selector backend

Three ways to reach a model, tried in this order under `"mode": "auto"`:

| backend    | how                                         | when it fires                                                   |
| ---------- | ------------------------------------------- | --------------------------------------------------------------- |
| `sampling` | `sampling/createMessage` back to the host   | the host declares the capability — few do; Claude Code does not |
| `api`      | direct HTTPS to Anthropic / OpenAI / Ollama | `selector.apiKeyEnv` names a variable that is actually set      |
| `cli`      | `claude -p` or `codex exec`, headless       | a harness CLI is on `PATH`                                      |

The CLI backend is the one that usually fires, and it exists because the other two
usually cannot. Sampling is the protocol's own answer and almost nothing
implements it. The API backend then asks for an `ANTHROPIC_API_KEY` that a Claude
Code subscriber has no reason to own — they logged in, they did not buy a key — so
the router would degrade to raw index order while telling them to go purchase
access to a model they are already paying for. Meanwhile `claude` is sitting on
`PATH`, already authenticated. Shelling out to it reuses that login with nothing
to configure and no second bill.

What it costs is process startup, which makes a CLI selector slower than a direct
HTTPS request. That is why a configured API key still outranks it. Selections are
memoized per query and candidate set for the life of the process, so the price is
paid once per distinct search, not once per turn.

The harness is stripped back to a reranker. A default headless agent may boot
hooks, language servers, plugin sync and project-instruction discovery that a
short ranking task does not need. The subprocess therefore runs with
`--bare --tools "" --setting-sources ""` and `MAX_THINKING_TOKENS=0` (Codex:
`--ephemeral -s read-only`). The empty tool list is a correctness property before
it is a saving: a selector that could edit files would be a different program.

```jsonc
"selector": {
  "mode": "auto",          // auto | sampling | cli | api | off
  "provider": "cli",
  "cliCommand": "claude",  // only needed if the binary is not under its usual name
  "model": "haiku",
  "candidates": 30,
  "maxResults": 8,
  "timeoutMs": 20000       // raised automatically to the backend's own floor
}
```

It is also started with an empty MCP config (`--strict-mcp-config`,
`mcp_servers={}`) — inheriting the router's own wiring would load the exact
catalog the router exists to keep out of context, and on a bad day recurse into
the router itself.

`model` is passed through only when you set it. Codex rejects model names an
account's plan does not carry, so the account default is what it gets otherwise.

`mode: "off"` skips reranking entirely and returns raw index order, which is
fast, free, and noticeably worse.

Downstream servers are **not** spawned at startup. The catalog is built once and
persisted to `~/.cache/autorouter/catalog.json`; a server is cold-started only
when one of its capabilities is first called.

## What it indexes

| kind                         | source                                                          |
| ---------------------------- | --------------------------------------------------------------- |
| `tool`, `prompt`, `resource` | every configured MCP server (following `nextCursor` pagination) |
| `skill`                      | `**/SKILL.md` under your skill paths and plugin `skills/` dirs  |
| `command`, `agent`           | plugin `commands/*.md` and `agents/*.md`                        |

Plugin commands and agents are also republished as [slash commands](#slash-commands);
skills are searchable but not republished by default, because the prompt list
that would carry them is permanent context — see [Slash commands](#slash-commands).

Harness configs are imported rather than duplicated: `~/.claude.json` (global and
per-project) and `.mcp.json`, `~/.codex/config.toml`, `~/.cursor/mcp.json`,
`~/.vscode/mcp.json`, and installed Claude Code plugins.

## Adding an MCP server

Register it with the router directly — it never enters anyone's context:

```sh
autorouter add linear --url https://mcp.linear.app/mcp
autorouter add foo -- npx -y foo-mcp            # stdio, like `claude mcp add`
autorouter add --json '{"mcpServers":{"linear":{"url":"…"}}}'   # paste the vendor snippet
autorouter remove linear
```