Skip to main content
Version: next

MCP Server

Routerly's mcp module exposes the gateway's own management API as tools to Model Context Protocol clients: Claude Code, Claude Desktop, Codex, OpenCode, OpenClaw, Cursor, Cline, Zed, and any other MCP-compatible client. It lets an agent inspect and, for a small write set, adjust Routerly directly from the conversation, without a human going through the CLI or dashboard.

This is a distinct surface from the LLM Proxy (/v1/*, /anthropic/*): /mcp never forwards a request to an upstream LLM provider. It only reads and writes Routerly's own configuration and usage data.

To wire a specific client to it, see Guides: Connect an MCP Client.


MCP is personal​

An MCP token belongs to a user, not to a router. Connecting a client to Routerly is the same act as logging into the dashboard: the client acts as you, and it can do exactly what your role lets you do, no more.

OwnerThe user who created it. Each user manages their own tokens.
Prefixsk-rt-mcp-…, distinct from the sk-rt-… router tokens used by the LLM Proxy.
StorageSHA-256 hash only, on the owner's user record. The raw value is shown once at creation and is never retrievable afterwards.
GrantsEvery permission of the owner's role, resolved at call time. Change the role, and every token of that user changes with it.
ExpiryOptional. An expired token is rejected with 401, it is not deleted.
RevocationImmediate: revoking a token stops every client using it on the next call.

Create and revoke tokens from the dashboard's Profile: MCP tab or with routerly mcp token.

Upgrading from an earlier version

Before 0.4.0, /mcp was authenticated by a router token carrying the mcp and mcp:write scopes, and the tool browser was a gateway-wide page gated by the mcp:read permission. Those scopes and the mcp:read / mcp:manage permissions no longer exist: they are dropped from roles and tokens automatically on first start after the upgrade. A client still authenticating with a router token gets 401 and must be re-pointed at a personal MCP token.


Transports​

Two transports ship, both authenticated by the same personal MCP token:

TransportEndpointUse case
Streamable HTTPPOST /mcpRemote MCP clients, JSON-RPC 2.0 over HTTP, Authorization: Bearer sk-rt-mcp-…
stdiorouterly mcp serveLocal desktop clients that spawn a subprocess and speak MCP over its stdin/stdout

The stdio transport is a local wrapper: routerly mcp serve resolves an MCP token, then spawns the Routerly service binary with ROUTERLY_MCP_STDIO=1 and ROUTERLY_MCP_TOKEN=<token> set, which starts only the stdio server on that token owner's identity. See CLI: routerly mcp and Reference: Environment Variables.

Both transports run the exact same tool registry and the exact same permission checks, so a tool call behaves identically whichever transport it arrives on. One difference of note: HTTP resolves the token on every request, while stdio resolves it once at startup, so a role change reaches a running stdio session only after a restart.


Permissions​

There is no MCP-specific permission. Each tool declares the ordinary dashboard permission it needs, and the caller's role decides:

  • tools/list returns only the tools the caller holds the permission for. A tool the caller cannot use is not advertised at all.
  • tools/call re-checks the permission and returns an isError result, Permission denied: <permission> is required to call <tool>., if it is missing. Filtering and enforcement are independent, so an under-permissioned client can never reach a handler.

An admin sees all 9 tools; a viewer sees only the read tools its role covers. See Dashboard: Users & Roles for the permission catalogue.

Router scope​

Router-scoped tools take an optional routerId (id or name) and resolve it against the routers the owner can reach: the user's assigned routers, plus any router they are a member of, or every router when the user is scoped to none. When exactly one router is reachable, routerId may be omitted. A router outside that set is reported as not found, so it is indistinguishable from one that does not exist.


The built-in tools​

Routerly ships 9 built-in tools, 7 read and 2 write. A tool only appears in the registry when its backing module is bootstrapped: for example get_metrics_snapshot is absent if the observability module is not running on that instance.

Read tools​

ToolPermissionDoes
list_modelsmodel:readLists the models configured on the gateway (id, provider, context window). No secrets.
get_modelmodel:readGets one configured model by id. No secrets.
route_previewrouter:readPreviews which model(s) a router would route a request to (ordered candidates + trace), no upstream call.
get_usage_summaryreport:readSummarizes a router's usage over a trailing window (default 24h): call count, cost, tokens.
get_budget_statusreport:readReports current budget/limit usage per model for a router.
get_metrics_snapshotreport:readAggregate request/token/cost/latency metrics for one router. Other routers' data is never returned.
list_routersrouter:readLists the routers the token owner can reach (id, name, model count).

Write tools​

ToolPermissionDoes
create_router_tokentoken:writeMints a new API token on a router. Returns only id/tokenSnippet/createdAt/scopes; the raw token is never returned to the MCP client.
toggle_modelrouter:writeFlips the enabled flag on one of a router's model refs. The flag is persisted but not yet honored by the routing engine.

Every write tool call is recorded in the audit log as mcp:<tool> (user of the token, routerId, modelId, the tool's result ids; never the raw token). A call refused for a missing permission is recorded as forbidden.


Errors​

WhereConditionResult
HTTPNo Authorization header401 Missing or invalid Authorization header. Expected: Bearer <mcp-token>
HTTPUnknown token, or a router token used by mistake401 Invalid MCP token.
HTTPToken past its expiry401 MCP token expired.
stdioROUTERLY_MCP_TOKEN missing or rejectedThe process fails to start, with the same message on stderr
Tool callCaller lacks the tool's permission200 with isError: true in the JSON-RPC result