Reduces context window overhead by providing a single search tool to discover and call MCP tools, skills, and plugins on demand.
Also known as Webb-Ventures/autorouter, autorouter-mcp
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.3.1
- Last commit
- Oct 22, 2026
- License
- MIT
What is autorouter MCP?
autorouter reduces context window overhead by providing a single search tool to discover and call MCP tools, skills, and plugins on demand.
Summary generated from the project's README
About autorouter MCP server
Developers using MCP clients like Claude Code, Cursor, or VS Code can reduce context window overhead by using autorouter to manage their toolsets. Instead of injecting every available tool, skill, and plugin schema into the system prompt on every turn, this server hides them behind a search interface. It uses a single search tool to discover capabilities on demand, which prevents the massive token costs associated with large tool lists.
To use it, you must run the adopt command for your specific target to move existing server entries into the router's management. The system works by retrieving candidates via BM25 and optional embeddings from providers like OpenAI or Voyage, then reranking them using a selector model. It can use a CLI backend to reuse your existing authenticated sessions, avoiding the need for extra API keys. Once a tool is used, it is promoted to the active tool list to ensure the session remains efficient.
What you can do with it
- 1Reduce context window token costsA developer can minimize the permanent token overhead caused by registering multiple MCP servers and skills.
- 2Discover tools using natural languageAn AI client can search for specific capabilities like inspecting deployment errors without having every tool schema pre-loaded.
- 3Manage plugin and skill visibilityDevelopers can disable plugins or hide skill descriptions to save space while still allowing the router to find them.
Written from the project's README. Every use case is checked against a quote from it.
How to install autorouter MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall autorouter MCP in Claude Code
$ claude mcp add autorouter -- npx -y autorouter-mcpInstall autorouter MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"autorouter": {
"command": "npx",
"args": [
"-y",
"autorouter-mcp"
]
}
}
}Install autorouter MCP in VS Code
.vscode/mcp.json
{
"servers": {
"autorouter": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"autorouter-mcp"
]
}
}
}Install autorouter MCP in VS Code CLI
$ code --add-mcp '{"name":"autorouter","type":"stdio","command":"npx","args":["-y","autorouter-mcp"]}'Install autorouter MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"autorouter": {
"command": "npx",
"args": [
"-y",
"autorouter-mcp"
]
}
}
}Install autorouter MCP in Codex
$ codex mcp add autorouter -- npx -y autorouter-mcpInstall autorouter MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.autorouter] command = "npx" args = ["-y", "autorouter-mcp"]
Install autorouter MCP in Gemini CLI
$ gemini mcp add -s user autorouter npx -- -y autorouter-mcpInstall autorouter MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"autorouter": {
"command": "npx",
"args": [
"-y",
"autorouter-mcp"
]
}
}
}Configuration
AUTOROUTER_CONFIGPath to autorouter.json. Defaults to the standard lookup chain (./.autorouter.json, ~/.config/autorouter/config.json, …).
AUTOROUTER_IMPORTComma-separated harness configs to import: claude, codex, cursor, vscode, plugins.
AUTOROUTER_SELECTOR_MODEReranker backend: auto | sampling | cli | api | off.
AUTOROUTER_SELECTOR_MODELModel the selector reranks with, e.g. haiku.
| Name | Description | |
|---|---|---|
| AUTOROUTER_CONFIG | Path to autorouter.json. Defaults to the standard lookup chain (./.autorouter.json, ~/.config/autorouter/config.json, …). | |
| AUTOROUTER_IMPORT | Comma-separated harness configs to import: claude, codex, cursor, vscode, plugins. | |
| AUTOROUTER_SELECTOR_MODE | Reranker backend: auto | sampling | cli | api | off. | |
| AUTOROUTER_SELECTOR_MODEL | Model the selector reranks with, e.g. haiku. |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablewebb-ventures/autorouter is public and reachablegithub.com/webb-ventures/autorouter ↗Pass
- Package names this repository as its sourceautorouter-mcp names webb-ventures/autorouter as sourcenpmjs.com/package/autorouter-mcp ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for autorouter-mcpnpmjs.com/package/autorouter-mcp/v/0.3.1#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-22github.com/webb-ventures/autorouter ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from autorouter-mcpPass
- No critical advisory in the package or its dependencies100 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubautorouter
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:
| what | how | effect |
|---|---|---|
| skills | skillOverrides[name] = "name-only" |
description out of context; Claude can still invoke it, /name still works |
| 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: ~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:
SessionStarthooks whose output lands in context, with the median size measured from your transcripts. A hook with an empty matcher runs again after every compaction,/clearand resume. - Stale tool references: lines in
~/.claude/CLAUDE.md,CLAUDE.mdorAGENTS.mdthat name a tool asmcp__<server>__<tool>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 withcmux-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.
- 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.
"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; 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 the repo's .mcp.json (see Repo skills and servers), ~/.codex/config.toml, ~/.cursor/mcp.json,
~/.vscode/mcp.json, and installed Claude Code plugins. While the
cmux terminal is running, its Computer Use server
(cmux-cua) is picked up too, since cmux injects it per session rather than
writing it to any config. Servers a harness has switched off (disabled: true,
or Codex's enabled = false) are skipped, and a command that would just open a
desktop app — rather than start an MCP server — is never launched.
Repo skills and servers
Open Claude Code in a repo, or anywhere inside one, and the router picks up that
repo's .mcp.json servers and .claude/skills — scoped to it, so they never
show up in another project — and Claude Code stops pre-loading them.
- Which repo. The host's
roots/list(Claude Code answers with its launch directory and any--add-dirs, and announces changes), thenCLAUDE_PROJECT_DIR, then the router's own working directory. - Which skills.
.claude/skillsin the working directory and each parent up to the git root, the way Claude Code reads them, plus every nested<subdir>/.claude/skillsbelow the root. Claude Code only loads those once it touches a file in that subdirectory; the router can search a monorepo's per-app skills from the top. - How they leave context. Only through the repo's own, private
.claude/settings.local.json:disabledMcpjsonServersfor the routed servers,skillOverrides: "name-only"for the skills (so Claude can still invoke them by name, and/namestill works). Entries earlier versions wrote as"user-invocable-only"— which blocks the Skill tool — are moved to"name-only"on the next pick-up. If the router creates that file it adds it to.git/info/exclude. Nothing committed is ever edited, and values you set yourself — even"on"— are left alone. - Which servers.
.mcp.jsonis checked in, so the router only launches a server from it that Claude Code would run: the folder must be trusted, and the server must be HTTP or approved — in Claude Code (enabledMcpjsonServers), or withautorouter approve <name>, which pins the exact command. Trust and approvals hold for every git worktree of the same repository. Anything unapproved stays with Claude Code, which asks about it as usual.
autorouter adopt --project [dir] # the same thing by hand (--dry-run to preview)
autorouter restore --project [dir] # take back exactly what that added
autorouter approve playwright # let the router launch a .mcp.json stdio server
Set "autoAdoptProject": false to keep this manual.
Upgrading from an earlier version? Before this, adopt emptied a repo's
committed .mcp.json and moved its servers into the router's global config.
autorouter repair lists what it moved, from the adopt backups; --apply puts
the entries back (byte-for-byte when the backup allows), scopes private
per-project servers to their project, and adopts each repo the new way.
doctor flags it when there is something to repair.
Adding an MCP server
Register it with the router directly — it never enters anyone's context:
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
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, set "allowAddServer": true and ask for it in
words — the router then exposes an add_server tool. It is off by default
because a tool definition is context on every request and autorouter add
covers the same ground. 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.
Configuration
autorouter.json — looked up at $AUTOROUTER_CONFIG, ./.autorouter.json,
./autorouter.json, ~/.config/autorouter/config.json, ~/.autorouter.json.
{
"import": ["claude", "codex", "cursor", "vscode", "plugins", "cmux"],
"servers": { "custom": { "command": "…", "args": [] } },
"skillPaths": ["~/.claude/skills", ".claude/skills"],
"exclude": ["media.generate_video"], // never surfaced at all
"alwaysExpose": ["code-search.search"], // stays first-class, never adopted
"confirm": ["database.execute_statement"], // first call is rejected, must re-issue
"autoAdopt": true, // move servers added to a harness behind the router
"autoAdoptProject": true, // route the current repo's .mcp.json servers and skills
"allowAddServer": false, // expose the add_server tool to the model
"promptMode": "commands", // slash commands: "all" | "commands" | "none"
"activation": "lazy", // promote to a real tool: "eager" | "lazy" | "off"
"spillOverTokens": 3000, // larger results are saved, not inlined
"spillOverrides": { "mcp:linear/*": 8000 }, // per-id thresholds; 0 = never
"resultsMode": "auto", // "auto" | "file" | "page" | "off"
"resultsDir": "", // default <cache>/results; never inside the working tree
"selector": { "mode": "auto" },
"embeddings": {
"provider": "voyage",
"model": "voyage-3-lite",
"apiKeyEnv": "VOYAGE_API_KEY",
},
}
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, AUTOROUTER_RESULTS_MODE,
AUTOROUTER_SPILL_OVER_TOKENS, …) 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:
/mcp__autorouter__find <what you want to do>
/mcp__autorouter__plugin_name_command_name
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 hides a local skill as
name-only, which leaves its native /name and Skill-tool invocation 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 (which also unpins, with off: true) 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.
Search and run in one step
find_capabilities({ query, arguments, auto: true }) runs the top hit in the
same request, saving a round trip, but only when the hit is unambiguous:
- it is a tool, and
- it leads the runner-up by at least 0.25 of the normalised index score, or, when the selector model ranked the hits, its confidence is at least 0.7 and 0.25 ahead of the next, and
- the arguments fit its schema (required properties, basic types, enums, no unknown keys where the schema forbids them), and
- it is not behind a
confirmgate. Auto never bypasses confirmation.
Otherwise it returns the normal search result with one line saying why it did not run.
autorouter MCP questions
How do I add autorouter MCP to Claude Code?
Run claude mcp add autorouter -- npx -y autorouter-mcp in your terminal. Add --scope user to make it available in every project.
How do I add autorouter MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How does autorouter save context tokens?
Instead of injecting every server's full tool schema into the system prompt, it hides them behind a search tool and only promotes tools into the active context when they are actually used.
Is the 'adopt' command necessary?
Yes, the adopt command is required to move existing server configurations into the router so that the harness loads only the router instead of every individual server.
What happens if I use a plugin with OAuth?
If the router cannot reach a plugin's MCP servers (common with OAuth where the harness holds the token), the plugin stays enabled to ensure the server continues to work.