autorouter

autorouter

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

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.

`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:

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: ~752 tokens best case: ~86,772 tokens saved (99%)

per harness (a session only ever runs in one): codex still loaded ~35,500 → saves ~51,272 (59%) claude, cursor, vscode: fully adopted → saves ~86,772 (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.

Doctor also reports what costs context but no adopt can move. It only reports and suggests; it never edits these:

• Hooks: SessionStart hooks whose output lands in context, with the median size measured from your transcripts. A hook with an empty matcher runs again after every compaction, /clear and resume.
• Stale tool references: lines in ~/.claude/CLAUDE.md, CLAUDE.md or AGENTS.md that name a tool as mcp__ __ when that server now sits behind the router. The model looks for a tool that isn't there. The router's own primer block is skipped.
• Injected servers: servers a launcher passes on the command line (claude --mcp-config ..., as cmux does with cmux-cua). These are in no config file, so adopt can't move them. Doctor flags them when the router imports a copy as well.

What a session actually pays: autorouter audit

Schemas are only part of the bill. Claude Code already defers MCP schemas to names, and every API call re-reads everything still in the window, so the real cost is context size × number of calls. autorouter audit reads Claude Code's transcripts (~/.claude/projects/*/*.jsonl) and uses the usage figures recorded for each call:

## Context bill

avg context per call 181k input processed 4.79B (96% cache reads) compactions 269 (median 317k before → 90k after)

What fills it (tokens × calls each stays in context)

30.1% 1.44B startup overhead (system prompt, tools, skills, CLAUDE.md) 23.2% 1.11B carried over through compaction (kept turns, re-attached files) 15.4% 735.5M Claude's thinking (kept in context) 13.9% 666.0M Bash output ...

Compaction window (replay, API-equivalent cost)

autoCompactWindow: 350000 (~/.claude/settings.json) window change compactions avg context 140k -26.9% 834 102k 170k -25.9% 559 116k ← recommended 350k 0.0% 173 196k ← current

Attribution charges each block of content once for every later call that re-reads it, until the next compaction. The window table replays your own sessions under each autoCompactWindow, calibrated against the compactions in your transcripts. Costs are weighted by API price ratios (cache read ×0.1, cache write ×1.25, output ×5) as a proxy for subscription usage. Read the percentages as relative, not exact. Among windows within 1.5 points of the cheapest, it recommends the largest, because every compaction loses some detail. --days N (default 14, or all) and --project DIR narrow the range; --json prints the full report.

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":

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.

"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

Plugin commands and agents are also republished as slash commands; skills are searchable but not republished