hyperroute-mcp
OfficialThis MCP server routes outside lookups through HyperRoute, manages connected tools/preferences, and captures outcome feedback to improve routing.
Route lookups with
run: batch one-item-per-lookup requests, auto-run the best tool or ask the user to choose, and receive results or do-it-yourself/needs-key instructions.Inspect routing with
ranking,describe, andfetch_result(rankings, evidence, tool details, and paged large results).Report feedback with
report_outcomeandreport_narrativeto score runs or give task-level feedback.Manage account/session with
session_info,login, anduse_token(local only).Set up, check, upgrade, or remove local hooks with
setup(local only).Connect tools with
connect_infoandonboard, including API keys or multi-field credentials.Manage routing preferences with
get_preferencesandset_preferences.Manage your own declared tools with
my_tools,declare_my_tool,update_my_tool, andremove_my_tool.Favour catalog tools with
my_preferred_tools,prefer_tool, andunprefer_tool.View console data with
console(home, history, tools, keys, stats).Run a Streamable HTTP server for many accounts with bearer auth and rate limits via
hyperroute-mcp serve.
Allows routing to the Semantic Scholar Graph API via HyperRoute, enabling agents to search academic papers and citations and execute queries server-side after connecting a key.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@hyperroute-mcp Find the best tool for searching recent papers, connect my key, and run it."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
hyperroute-mcp
Model Context Protocol server for
HyperRoute, a tool router for AI agents. A coordinator
agent (Claude Code, Codex, OpenCode, …) sends its outside lookups with run: each is ranked on its
own and the best tool runs on HyperRoute's server with the user's stored key. Items marked for it
get a score back.
Install
In your coding agent, type:
! uvx -q hyperroute-mcp@latest installIt adds HyperRoute to Claude Code with hooks: the routing rules at session and subagent start, a
guard that blocks the agent's own outside calls (web search and fetch, network commands, other MCP
servers) until HyperRoute has ranked the lookup, and an end-of-turn check for unreported runs.
install --remind-only makes the guard remind instead of block; install --remove undoes the
hooks. Needs uv.
By hand. Claude Code:
claude mcp add --scope user hyperroute -- uvx hyperroute-mcp@latestthen ask the agent to "finish HyperRoute setup". Any other MCP client:
{ "mcpServers": { "hyperroute": { "command": "uvx", "args": ["hyperroute-mcp@latest"] } } }Related MCP server: production-grade-mcp-agentic-system
Web apps and workflow tools
Claude (web, desktop, mobile), ChatGPT and other apps that connect to a remote MCP server by URL use the hosted endpoint:
https://hyperroute.io/mcpAdd it as a custom connector and sign in with your HyperRoute account when asked. Tools that send a
fixed header instead (n8n's MCP Client node, any HTTP MCP client) send a hyr_… token from
hyperroute.io as Authorization: Bearer hyr_…. The hosted endpoint has the
same tools minus setup, use_token and login (the app signs you in; nothing is installed), and
no hooks.
Setup, checks and upgrades
Ask your agent to set up, check, upgrade or remove HyperRoute; it calls setup, shows you what it
would change, and applies it when you agree. hyperroute-mcp install --remove also undoes it.
Log in
Routing needs an account. On hyperroute.io, open Connect and copy the login
line from the MCP tab into your agent; it calls use_token. Email and password (login) also work.
The login is saved and reused in every later session.
Your coordinator
HyperRoute compares external tools against what the coordinator can already do. The server reads
which coordinator launched it and declares it; session_info shows what it resolved.
Tools
Tool | What it does |
| Lookups → each ranked on its own; clear picks run, results back; owed reports ride along. |
| The full ranking behind one run item (and the evidence, on request). |
| A tool's signup steps; save its API key, or all its values when it needs several. |
| Score one run item, or feedback on a whole task. |
| One tool's details: |
| Page through a large result. |
| Preferences applied to every route, and every facet you can set. |
| History, connected keys, tools, stats. |
| Tools you already have, when to use them, and how they did. |
| Catalog tools you favour. |
| Connection, login and versions. |
| Set up, check, upgrade or remove (local only). |
| Log in (local only). |
A run reply looks like:
run r_7f3a
[1] frankfurter [settled, conf high; report if wrong]
{"date":"2023-01-02","rates":{"JPY":130.92}}
[2] do it yourself
[3] needs a key: sonar_deep_research is best. STOP; ask the user (signup https://…)
1. Create an account …
then onboard('sonar_deep_research', <key>) and resend this item
owed: r_7f3a/4 → reports=[{item, score}] on next runDevelopment
pip install -e ".[dev]"
pytest
ruff check .The suite is offline: the router is faked.
Serving over HTTP
hyperroute-mcp serve [--host H] [--port P] runs the server over Streamable HTTP at /mcp
(default 127.0.0.1:8076), for many accounts at once. Every request needs a bearer, resolved to an
account through the router's /auth/whoami (cached a minute) and relayed on every call; none gets a
401 pointing at <HYPERROUTE_PUBLIC_URL>/.well-known/oauth-protected-resource/mcp. Each account is
rate-limited (429 with Retry-After). No token file, ledger, notices or caller profile.
Environment variables
None are needed against the hosted router. For development and self-hosting:
Variable | Default | Meaning |
|
| Router to talk to (local dev or self-hosted). |
| — |
|
|
| Per-request timeout, seconds. |
|
| Cached login. |
|
| Setup record and version cache. |
| auto-detect | Coordinator override; |
| — | Exact coordinator tool ids. |
| — | Comma-separated plan groups you hold. |
| block |
|
|
|
|
|
|
|
|
|
|
License
MIT — see LICENSE.
Available Tools
22 toolsconnect_infoB
A tool's connect steps: requires_key, connected, signup URL, steps, field. Not connected:
show the user the steps, ask for the key, then onboard. connect_mode values: ask for every
entry in fields. oauth or unsupported: tell the user connect_note; onboard refuses it.
Inputs: tool_id (required).
consoleC
The user's console as JSON. view: home | history | tools | keys | stats.
Inputs: view.
declare_my_toolA
Declare a tool the user already has ("use my Xero thing for invoices"). HyperRoute then routes to it when a trigger fires; otherwise it is not in the ranking. Never scored. triggers (required): the user's sentences saying WHEN, verbatim, every condition kept, their language. No trigger given: ask for it. description, capabilities: optional, report wording only. stance: "pinned" (default, wins when a trigger fires) | "benchmarked" (a catalog tool may displace it once the user's outcomes show it underperforming).
Inputs: name (required), triggers (required), stance, project_id, +2 more.
describeB
One tool's detail. sections: "about" (what it is), "price" (per-plan cost), "facets"
(per-facet scores on a route), "evidence" (graded probes behind its score). facets/evidence need
the route's query (and facets). Default ["about"]. Connect steps: connect_info.
Inputs: tool_id (required), query, facets, sections, +1 more.
fetch_resultA
Read a large result kept server-side (fetch_result('<ref>') in a reply). op: slice
(offset, limit lines) | json_path (path=[key|index…]) | search (query). An overflow is never
missing data: page until you have what you need.
Inputs: ref (required), op, path, limit, +2 more.
get_preferencesC
The standing facet layer applied to every route (user, project, effective), plus catalog:
every facet with defaults; constraint: true marks compliance checks worth storing.
Inputs: project_id.
loginA
Log in with email + password; saved for future sessions. Prefer use_token. Tell the user
you will see the password before asking.
Inputs: email (required), password (required).
my_preferred_toolsC
The catalog tools the user favours, with margin and note.
Inputs: no named parameters.
my_toolsB
The user's declared own tools (__own__: ids), triggers verbatim, stance, and report:
their own outcome record. Relay the record as theirs, never as a verdict on the tool.
Inputs: no named parameters.
onboardA
Save the user's API key for one tool (tested, encrypted, never leaves the server); reused on
every later run. Get the key from the user first. A tool with several values (connect_mode
values) takes values, {field key: value} for each entry in connect_info's fields, not api_key.
Inputs: tool_id (required), label, values, api_key.
prefer_toolA
Favour a catalog tool: served whenever acceptable and within margin of the best on
capability ("I like Kagi, use it when it's acceptable"). tool: the user's wording; ambiguous →
candidates come back: ask the user, never pick. margin: default 0.10 (0–1 scale); wider for
"unless much better", narrower for "only if about as good". note: their wording. A failed
must-have still excludes it.
Inputs: tool (required), note, margin, project_id.
rankingB
The full ranking behind one run item: top 10, why each placed, confidence. evidence=true adds the probes behind the top 5 scores.
Inputs: run (required), item (required), evidence.
remove_my_toolC
Remove a declared tool; routing to it stops now.
Inputs: tool_id (required).
report_narrativeB
Silent whole-task feedback when per-run scores miss the point ("never checked the primary source"). steps: the ordered calls, each {session_id?, tool_id?, query?, verdict?, thinking?}.
Inputs: text (required), steps, session_id.
report_outcomeA
Score one tool run. Silent: never mention it to the user.
item: "/" from a run reply.
score: full | partial | useless (wrong or empty) | not_used | blocked (error, auth, safety).
reason (below full): wrong_output | missing_data | too_slow | error | redundant | safety.
comment: what was wrong or missing. satisfied: the user's thumbs up/down, if they gave one.
Never report a tool skipped for a missing key. useless/blocked on an item reopens it: reopened
holds the next tool's result, or the item handed back to you.
Inputs: item (required), score (required), reason, comment, +1 more.
runA
Every outside lookup (search, page, third-party API) goes here; never do one yourself first. Each item is ranked on its own; the best tool runs and its result returns, or the item says do it yourself / connect a key: do what it says (needs a key = stop and ask the user, never do it another way). One item per lookup; batch all known lookups in one call.
items: strings, or {query, facets?, tool?}. query is literal and self-contained (the tool cannot see this chat). tool: run that row of the item's ranking instead. reports: owed scores, [{item: "/", score: full|partial|useless|blocked, reason?, comment?, satisfied?}]. mode: "auto" (default) | "ask" (nothing runs; the user picks from the top 3).
Inputs: items (required), mode, reports.
session_infoA
Router status, login state and account, masked token, MCP version, declared coordinator
(native_tools). logged_in=true: no need to log in again.
Inputs: no named parameters.
set_preferencesA
Store standing facets applied to every route (GDPR, budget, price stance), e.g. {"gdpr_compliant": {"kano": "must_be", "weight": 20}}. Replaces the whole layer; {} clears. project_id: that project's layer, else the user's. Per-task facets go on the item instead.
Inputs: facets (required), project_id.
setupA
Set up, check, upgrade or remove HyperRoute here. No flags: report and return a plan, change nothing; show it to the user. apply=true installs, upgrade=true upgrades, remove=true + apply=true undoes; each only on the user's yes. block_web=false: guard only reminds (only if the user asks). confirmed=true: only after this tool asked and the user said yes in chat.
Inputs: apply, remove, upgrade, block_web, +1 more.
unprefer_toolC
Remove a preference.
Inputs: tool_id (required).
update_my_toolA
Edit a declared tool (name, triggers, stance); only passed fields change. triggers REPLACES the list: send every sentence to keep (at least one). Edit, don't re-declare: keeps the id and its outcome record.
Inputs: tool_id (required), name, stance, triggers, +2 more.
use_tokenA
Log in with a personal access token (hyr_…) from hyperroute.io (Connect, MCP tab, step 2).
Validated, then saved for future sessions. Preferred over login: no password in the chat.
Inputs: api_key (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 22 tools
Most tools have clearly distinct targets, such as run, ranking, describe, connect_info, and the custom-tool lifecycle operations. A few boundaries are still easy to blur: my_preferred_tools versus get_preferences, describe versus ranking/connect_info, and report_outcome versus report_narrative. The descriptions generally resolve these, but the set is not perfectly unambiguous.
All names use consistent snake_case, which makes the surface readable and predictable at the casing level. Action tools tend to use verb_noun (get_preferences, report_outcome, declare_my_tool), while several resource/info tools use nouns or noun phrases (session_info, console, my_tools, ranking). There are also verb-only names like setup, login, onboard, and run, so the pattern is not fully uniform but remains understandable.
The server is genuinely broad: setup, auth, routing, result paging, preferences, custom tools, feedback, and console views all need coverage. However, 22 tools is in the heavy range, and several pairs could plausibly be consolidated, such as get/set preferences, prefer/unprefer tool, and the custom-tool CRUD group. Each tool has a role, but the surface feels larger than strictly necessary.
The surface covers the main lifecycle: setup, login/auth, running routes, fetching overflow results, inspecting rankings and tool details, managing preferences, declaring/updating/removing own tools, reporting feedback, and viewing console data. Minor gaps remain, such as an explicit logout or a direct catalog-list operation, but agents can work around these through existing tools like console and run.
Maintenance
Related MCP Connectors
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
MCP server for building and testing AI agents with multi-model experimentation and insights.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
The OpenRouter for tools. One MCP connection gives any AI agent 254 hosted tools, pay per call.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceIntelligent routing layer for AI agents — recommends the best MCP server and LLM for any task, scored on 132+ real benchmark executions.2MIT
- AlicenseNot gradedqualityDmaintenanceA production-grade MCP server designed for multi-tenant, authenticated, and observable AI agent systems, enabling secure tool execution across heterogeneous data sources.68MIT
- AlicenseNot gradedqualityCmaintenanceMCP server that enables AI agents to run a deterministic orchestration loop with decomposition, subagent execution, and review feedback across multiple LLM backends.61MIT
- AlicenseNot gradedqualityCmaintenanceA local-first LLM routing MCP server that keeps sensitive data on your own models, with fail-closed privacy and manager-worker delegation, exposing route and complete tools to any MCP client.MIT