Skip to main content
Version: 0.3.0

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 project. 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-… project 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 project 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 project 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.

Project scope​

Project-scoped tools take an optional projectId (id or name) and resolve it against the projects the owner can reach: the user's assigned projects, plus any project they are a member of, or every project when the user is scoped to none. When exactly one project is reachable, projectId may be omitted. A project 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_previewproject:readPreviews which model(s) a project would route a request to (ordered candidates + trace), no upstream call.
get_usage_summaryreport:readSummarizes a project's usage over a trailing window (default 24h): call count, cost, tokens.
get_budget_statusreport:readReports current budget/limit usage per model for a project.
get_metrics_snapshotreport:readAggregate request/token/cost/latency metrics for one project. Other projects' data is never returned.
list_projectsproject:readLists the projects the token owner can reach (id, name, model count).

Write tools​

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

Errors​

WhereConditionResult
HTTPNo Authorization header401 Missing or invalid Authorization header. Expected: Bearer <mcp-token>
HTTPUnknown token, or a project 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