Skip to main content
Glama
hyperroute-mcp

hyperroute-mcp

Official
by HyperRouteAI

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 install

It 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@latest

then 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/mcp

Add 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

run

Lookups → each ranked on its own; clear picks run, results back; owed reports ride along.

ranking

The full ranking behind one run item (and the evidence, on request).

connect_info / onboard

A tool's signup steps; save its API key, or all its values when it needs several.

report_outcome / report_narrative

Score one run item, or feedback on a whole task.

describe

One tool's details: about · price · facets · evidence.

fetch_result

Page through a large result.

get_preferences / set_preferences

Preferences applied to every route, and every facet you can set.

console

History, connected keys, tools, stats.

my_tools / declare_my_tool / update_my_tool / remove_my_tool

Tools you already have, when to use them, and how they did.

my_preferred_tools / prefer_tool / unprefer_tool

Catalog tools you favour.

session_info

Connection, login and versions.

setup

Set up, check, upgrade or remove (local only).

use_token / login

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 run

Development

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

HYPERROUTE_BASE_URL

https://hyperroute.io

Router to talk to (local dev or self-hosted).

HYPERROUTE_API_KEY

—

hyr_… token to start logged in; used, never cached.

HYPERROUTE_TIMEOUT

30

Per-request timeout, seconds.

HYPERROUTE_TOKEN_FILE

~/.hyperroute/token.json

Cached login.

HYPERROUTE_HOME

~/.hyperroute

Setup record and version cache.

HYPERROUTE_COORDINATOR

auto-detect

Coordinator override; none disables.

HYPERROUTE_NATIVE_TOOLS

—

Exact coordinator tool ids.

HYPERROUTE_HELD

—

Comma-separated plan groups you hold.

HYPERROUTE_GUARD

block

remind makes the Claude Code guard remind instead of block.

HYPERROUTE_PUBLIC_URL

HYPERROUTE_BASE_URL

serve only: the public origin the endpoint is reached at.

HYPERROUTE_MCP_RATE / HYPERROUTE_MCP_BURST

120 / 60

serve only: calls per minute per account, and burst.

HYPERROUTE_LOG_LEVEL

info

serve only: uvicorn log level.

License

MIT — see LICENSE.

Available Tools

22 tools
connect_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

    B3.2/5.0

    Scored across 22 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers