Autorouter README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Autorouter listing page.
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.
Install
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:
| 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:
"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.
- 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. - 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. - A selector model reranks the shortlist. It should be the cheapest model in
whichever harness you are using, so
initasks 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.
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; skills are searchable but not republished by default, because the prompt list that would carry them is permanent context — see 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:
The entry is saved before the connection is checked, because the usual reason a
new server does not answer is that it has no OAuth grant yet — and
autorouter login <name> needs the entry to exist before it can authorize it.
You can also just use the harness. claude mcp add foo … still works: a
running router notices the harness config changed, moves the entry into its own
config with the usual backup, and tells you on the next search. So there is no
second command to remember, and no window where you have forgotten it and are
paying for that server's schemas on every turn. Set "autoAdopt": false to keep
adoption manual.
From inside a session, ask for it in words — the router exposes an
add_server tool. Registering a stdio server means this machine will run that
command from then on, so the first call only reports what would be registered;
it takes a second call with confirm: true to write anything. Set
"allowAddServer": false to withdraw the tool.
Configuration
autorouter.json — looked up at $AUTOROUTER_CONFIG, ./.autorouter.json,
./autorouter.json, ~/.config/autorouter/config.json, ~/.autorouter.json.
Env overrides (AUTOROUTER_IMPORT, AUTOROUTER_SELECTOR_MODEL,
AUTOROUTER_SELECTOR_MODE, AUTOROUTER_PROMPT_MODE, AUTOROUTER_ACTIVATION,
AUTOROUTER_AUTO_ADOPT, AUTOROUTER_ALLOW_ADD_SERVER,
AUTOROUTER_EMBEDDINGS_PROVIDER, …) let each harness
pin its own behaviour without a shared global file. AUTOROUTER_HOME redirects
every home-relative path, for tests and containers.
Slash commands
Adopting a plugin into the router would otherwise cost you its slash commands:
Claude Code reads commands/*.md off disk, and nothing over MCP can add to that
list. What it does surface as slash commands are MCP prompts, so the catalog's
plugin commands and subagents are republished as ones:
Skills are not republished by default (promptMode: "commands"). The prompt
list is permanent context — the host fetches it once and carries it for the whole
session — and skills are the bulk of it: one plugin shipping 141 of them costs
~11.5k tokens on every turn, which is more than adopting that plugin saves. The
alias is also mostly redundant, since adopt --skill-mode user-invocable-only
leaves a local skill's native /name working and a plugin's skills are surfaced
by the harness on demand rather than injected. Skills stay fully searchable
either way; set "promptMode": "all" to get /mcp__autorouter__skill_name back,
or "none" to publish only find.
Bodies are substituted the way the native loader substitutes them — $ARGUMENTS
for everything you typed, $1..$9 positionally — so a command file written for
Claude Code behaves identically through the router. argument-hint frontmatter
is passed through as the argument description. Names are prefixed with the owning
plugin, so two plugins shipping a setup command both stay reachable rather than
one silently shadowing the other.
Tools are deliberately not published here. A prompt returns text for the model to
act on and cannot return a tool result, so a slash command for database_write would
look callable and do nothing. Tools reach the model through search instead.
Harness support
Searching returns a tool with its full description and input schema, not a summary — the same information a native tool listing carries, because a truncated description leaves the model guessing argument names, and a guessed argument is the whole difference between roughly reliable and reliable.
Better still, where the client honours notifications/tools/list_changed, a tool
you use is promoted to a real first-class tool. From then on the model
makes an ordinary tool call: the host validates arguments against the real
schema, the permission prompt names the real tool rather than call_capability,
and the router is not in the execution path at all. It becomes a loader that
decides what is in your tool list, not a middleman on every call.
Promotion is deferred to the first successful call (activation: "lazy") because
a promoted tool is permanent context and a search hit is not evidence of need —
most of what a search matches is never called. Set "activation": "eager" to
promote every hit as before, or "off" to route everything through
call_capability and carry no tool definitions at all.
supports listChanged | proxy only |
|---|---|
| Claude Code ≥ 2.1.232, GitHub Copilot, opencode | Codex, Gemini CLI, Claude Desktop, Vercel AI SDK |
Where it is unsupported the schema travels inline in the search result instead,
and activate_capabilities is never advertised, so the model is never told about
a tool it cannot use. Override the detection with AUTOROUTER_DYNAMIC=on|off|auto.
A tool registered mid-turn may not be callable until the next turn on Claude Code,
so call_capability always remains as the same-turn fallback and returns an
identical result.
Token budgets
A router that leaks context is just a slower way of loading everything, so the three surfaces that persist or accumulate are each bounded in tokens, not in item count. Counting items looks like a bound and is not one: tool definitions vary widely in size, so the context cost of "15 tools" depends entirely on what the model happened to search for.
| surface | budget | lifetime |
|---|---|---|
| promoted tool list | 3,000 tok, LRU eviction, on use only | session |
| inline schemas per search | 700 tok, spent top-down | one result |
| prompt list | commands only, clamped to 120 chars | session |
The tool promoted by the call in flight is never evicted — a tool that vanishes between being offered and being called is worse than one never offered.
autorouter doctor reports the real bill per harness rather than summing across
them, since a session only ever runs in one: a server still registered in Cursor
costs a Claude Code session nothing.
Schemas are compacted everywhere they are repeated: $schema, title and
examples are dropped, and prose is trimmed, more aggressively the deeper it
sits. Every structural field survives untouched — names, types, enums, required,
nesting, and additionalProperties: false — because dropping one of those turns a
valid call into a guessed one. This reduces repeated schema size without changing
what is callable.
describe_capability is the exception and returns the schema verbatim: it exists
precisely to recover anything a budgeted result had to leave out.
CLI
For agents that have a shell but no MCP, the same engine is directly usable:
OAuth servers
Some remote MCP servers carry no credentials in their visible configuration. The working token is an OAuth grant obtained by the harness, stored in the harness's credential store, and issued specifically to that harness.
The router does not read it. It runs its own authorization-code flow and holds its own grant, which means it also works under Codex and Cursor, neither of which has a token to borrow:
Registration is RFC 7591 dynamic client registration, so there is no app to
create first. Tokens live in ~/.autorouter/oauth/<server>.json at 0600 and
are refreshed automatically; logout deletes them. The loopback redirect uses a
fixed port (33418, --port or $AUTOROUTER_OAUTH_PORT to change it) because the
redirect URI is baked into the registration a provider stores — a grant obtained
on one port cannot be refreshed from another.
Choosing permissions
A dynamically registered client may default to every scope the provider advertises, including write or administrative permissions. That can leave a search tool holding a token capable of destructive actions. Scopes are the only restriction that survives a prompt injection, so pick them deliberately:
--read-only keeps the scopes whose names do not grant mutation. It is a
heuristic over naming conventions (:write, admin, manage, all) and it
cannot infer the permissions behind opaque scope names. --scopes is the exact
lever when the heuristic cannot tell. Where a provider offers no read-only subset
at all, --read-only fails loudly rather than requesting an empty scope, which
most providers read as "give the default".
Scopes are fixed when the grant is issued, so narrowing an existing one means
--force and a fresh authorization. A re-login inherits the previous narrowing
unless you pass a new one, and autorouter login with no argument prints what
each stored grant actually covers.
Until a server has a grant, adopt refuses to move it or to disable the plugin
that supplies it. Moving a server the router cannot reach would delete a working
capability, so doctor and adopt both print the exact login command instead.
The trade-off, stated plainly
Routing means your host's permission prompt sees call_capability, not
database.execute_statement. That is a real loss of granularity and this tool
does not pretend otherwise. Three mitigations: exclude means a capability is
never surfaced; confirm rejects the first attempt with the resolved target
spelled out and requires the model to re-issue with confirm: true; and every
result is prefixed with the resolved server/tool so the transcript stays
auditable.
Adopting skills and plugins edits ~/.claude/settings.json, a file you also edit
by hand. The whole file is backed up verbatim alongside the server moves and
restore rewrites it byte for byte, but it is a shared file and worth knowing
about. Hidden skills default to user-invocable-only rather than off for the
same reason: /name keeps working, so the capability is relocated, not removed.
Development
The build targets Node so npx works for people who do not have Bun.
See CONTRIBUTING.md for the invariants worth knowing before
changing anything — chiefly that nothing is spawned at startup, that every write
adopt makes has to restore byte for byte, and that the selector subprocess runs
with no tools by design.
Licence
MIT. Security reports go through SECURITY.md, not the public issue tracker.