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"] } } }

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

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:

License

MIT — see LICENSE.