Skip to main content
Version: 0.3.0

Connect an MCP client

Routerly exposes its own management API to MCP clients, so an agent can list models, preview routing, read usage, and check budgets from inside a conversation. See Concepts: MCP Server for what the surface is and which tools it ships.

This guide is the wiring: one section per client, with the exact command or config file each one expects.


1. Create your MCP token​

An MCP token is personal: it acts as you and grants exactly your role's permissions. Create one from the CLI:

routerly mcp token create laptop
✓ MCP token "laptop" created.

Token (save it now, it is shown only once):
sk-rt-mcp-8f3c1d...

Or from the dashboard: Profile → MCP → New Token, which opens /dashboard/profile/mcp/new. That page shows the value once and, right below it, the configuration for the client you pick, with the token already in it (see Dashboard: Profile: MCP tab).

Copy the value immediately: Routerly stores only its hash and never shows it again. Revoke it at any time with routerly mcp token remove <token-id>, and every client using it stops working on the next call.


2. Pick a transport​

TransportEndpointWhen
HTTPPOST http://localhost:3000/mcpAnything that supports remote MCP servers. Preferred: no local CLI needed, and the token is checked on every request.
stdiorouterly mcp serveClients that only spawn a local subprocess, and setups where the gateway is not reachable over HTTP from the client.

Replace http://localhost:3000 with your own origin (publicUrl) if Routerly does not run on the same machine as the client.

Verify the surface answers before wiring anything:

routerly mcp tools
routerly mcp test list_models

Claude Code​

HTTP, the one-liner:

claude mcp add --transport http routerly http://localhost:3000/mcp \
--header "Authorization: Bearer sk-rt-mcp-YOUR_TOKEN"

stdio, if you prefer the local wrapper:

claude mcp add --transport stdio routerly -- routerly mcp serve

Everything after -- is the command Claude Code runs, untouched.

Add --scope user to make the server available in every project instead of just the current one, or --scope project to write it into the repository's .mcp.json for the whole team. Check the result with:

claude mcp list

Claude Desktop​

Claude Desktop reads a JSON config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Open it from the app (Settings → Developer → Edit Config) and add the routerly entry:

{
"mcpServers": {
"routerly": {
"command": "routerly",
"args": ["mcp", "serve"],
"env": {
"ROUTERLY_MCP_TOKEN": "sk-rt-mcp-YOUR_TOKEN"
}
}
}
}

routerly mcp serve picks the token up from ROUTERLY_MCP_TOKEN, so the desktop app needs no CLI login of its own.

Use an absolute path for command (which routerly) if the app cannot find the binary: desktop apps do not inherit your shell's PATH. Quit and reopen Claude Desktop to load the change; the tools then appear under Connectors.


Codex​

Codex CLI, HTTP:

# ~/.codex/config.toml
[mcp_servers.routerly]
url = "http://localhost:3000/mcp"
bearer_token_env_var = "ROUTERLY_MCP_TOKEN"

Codex reads the token from the named environment variable, so export it in your shell profile:

export ROUTERLY_MCP_TOKEN="sk-rt-mcp-YOUR_TOKEN"

stdio, added from the command line:

codex mcp add routerly --env ROUTERLY_MCP_TOKEN=sk-rt-mcp-YOUR_TOKEN -- routerly mcp serve

which writes the equivalent [mcp_servers.routerly] section with command and args.


OpenCode​

OpenCode reads opencode.json (project root, or ~/.config/opencode/opencode.json for every project). Remote:

{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"routerly": {
"type": "remote",
"url": "http://localhost:3000/mcp",
"enabled": true,
"headers": {
"Authorization": "Bearer sk-rt-mcp-YOUR_TOKEN"
}
}
}
}

Local:

{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"routerly": {
"type": "local",
"command": ["routerly", "mcp", "serve"],
"enabled": true,
"environment": {
"ROUTERLY_MCP_TOKEN": "sk-rt-mcp-YOUR_TOKEN"
}
}
}
}

OpenClaw​

HTTP:

openclaw mcp add routerly \
--url http://localhost:3000/mcp \
--transport streamable-http \
--header "Authorization: Bearer sk-rt-mcp-YOUR_TOKEN"

--transport streamable-http is required: OpenClaw defaults to sse, which Routerly does not serve.

stdio:

openclaw mcp add routerly \
--command routerly \
--arg mcp \
--arg serve \
--env ROUTERLY_MCP_TOKEN=sk-rt-mcp-YOUR_TOKEN

Check the connection:

openclaw mcp probe routerly --json

Cursor​

Cursor reads ~/.cursor/mcp.json for every project, or .cursor/mcp.json inside a repository to scope the server to that project alone:

{
"mcpServers": {
"routerly": {
"url": "http://localhost:3000/mcp",
"headers": {
"Authorization": "Bearer sk-rt-mcp-YOUR_TOKEN"
}
}
}
}

An entry with a url is remote by definition, so there is no transport field to set. The server then appears under Settings → Tools & Integrations → MCP, where it can be toggled per project.


Cline​

Cline keeps its servers in ~/.cline/mcp.json, editable from the panel (MCP Servers → Configure MCP Servers):

{
"mcpServers": {
"routerly": {
"type": "streamableHttp",
"url": "http://localhost:3000/mcp",
"headers": {
"Authorization": "Bearer sk-rt-mcp-YOUR_TOKEN"
},
"disabled": false,
"autoApprove": []
}
}
}

"type": "streamableHttp" is required: without it Cline falls back to the legacy sse transport, which Routerly does not serve.


Zed​

Zed calls MCP servers context servers, configured in the same settings.json as everything else (Zed → Settings → Open Settings):

{
"context_servers": {
"routerly": {
"url": "http://localhost:3000/mcp",
"headers": {
"Authorization": "Bearer sk-rt-mcp-YOUR_TOKEN"
}
}
}
}

The headers entry is not optional: without it Zed starts an OAuth flow against the server, and Routerly's MCP surface only authenticates bearer tokens.


Any other client​

The surface is standard MCP, so any client that speaks Streamable HTTP works with two values:

  • URL: http://localhost:3000/mcp
  • Header: Authorization: Bearer sk-rt-mcp-YOUR_TOKEN

A raw JSON-RPC call, to sanity-check a setup by hand:

curl -s http://localhost:3000/mcp \
-H "Authorization: Bearer sk-rt-mcp-YOUR_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Troubleshooting​

SymptomCause
401 Invalid MCP token.The token was revoked, mistyped, or is a project token (sk-rt-…) rather than an MCP token (sk-rt-mcp-…).
401 MCP token expired.The token passed its expiry date. Create a new one.
Fewer tools than expectedtools/list only advertises the tools your role permits. Check your role in Users & Roles.
Permission denied: … is required to call …Same cause, seen at call time instead of at listing time.
projectId is required: this token can reach several projectsPass projectId in the tool arguments; it is optional only when you can reach exactly one project.
The client cannot start routerly mcp serveThe binary is not on the app's PATH. Use an absolute path in command.