hyperroute-mcp

Model Context Protocol server for HyperRoute, a tool router for AI agents. A coordinator agent (Claude Code, Codex, OpenCode, …) calls recommend for an outside task, runs the pick with execute (the tool runs on HyperRoute's server with the user's stored key), and reports the result with report_outcome.

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

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 ranking looks like:

session: s-6d6c5a95f9f84d9a
verdict: interpose

  tool              name                        price  use        why
→ opencitations     OpenCitations Index         free   ready      highest-ranked: capability 0.81 …
  semantic_scholar  Semantic Scholar Graph API  free   needs_key  lower capability (0.75 vs 0.81).

confidence: med (on the pick)
act: execute('opencitations', <query>)

use: ready (run it) · needs_key (connect a key first) · native (the agent does it itself, following the instruction: line) · own (your own tool) · soon (not runnable yet).

Development

pip install -e ".[dev]"
pytest
ruff check .

The suite is offline: the router is faked.

Environment variables

None are needed against the hosted router. For development and self-hosting:

License

MIT — see LICENSE.