MCP Server

A remote Model Context Protocol server so agents can manage FreeRouter inference keys, usage, and account — authenticated with a management API key.

What it is

FreeRouter exposes an MCP server at https://api.freerouter.com/mcp. Point Cursor, Claude, VS Code, or any Streamable HTTP MCP client at that URL and pass a management API key (fr_mgmt_…) as a Bearer token. The tools are the same operations as the management REST API: list / create / update / revoke inference keys, plus usage and account.

This is not an inference endpoint. MCP cannot run /v1/chat/completions. Use an inference key (fr_live_…) against https://api.freerouter.com/v1 for that — see the API Reference.

Admin-only — keep the key server-side A management key can mint inference keys that spend against your provider keys. Treat it like any server secret. Prefer a read-only management key if the client only needs reporting.

Endpoint & auth

https://api.freerouter.com/mcp

Authorization: Bearer $FREEROUTER_MANAGEMENT_KEY

Transport is Streamable HTTP: POST JSON-RPC 2.0, application/json responses. GET returns 405. Missing, invalid, revoked, or inference-shaped secrets return 401.

The two key types stay split:

fr_mgmt_… authenticates /mcp (and the management REST API on the app host). Presenting one to /v1 returns 401.
fr_live_… authenticates inference on /v1. Presenting one to /mcp returns 401.

Client config

Create a management key under Settings → Management API Keys, then drop it into the client. Store the secret in the client's env or secrets store — never commit it.

Cursor

{
  "mcpServers": {
    "freerouter": {
      "url": "https://api.freerouter.com/mcp",
      "headers": {
        "Authorization": "Bearer ${FREEROUTER_MANAGEMENT_KEY}"
      }
    }
  }
}

Claude / Claude Code

{
  "mcpServers": {
    "freerouter": {
      "type": "http",
      "url": "https://api.freerouter.com/mcp",
      "headers": {
        "Authorization": "Bearer ${FREEROUTER_MANAGEMENT_KEY}"
      }
    }
  }
}

curl (initialize)

curl https://api.freerouter.com/mcp \
  -H "Authorization: Bearer $FREEROUTER_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": { "name": "curl", "version": "0" }
    }
  }'

Tools

v1 mirrors the management REST API. Tool results are JSON text. Write tools are marked below.

Tool	What it does	Write?
`list_api_keys`	List inference keys (metadata, never secrets). Optional `offset`.	No
`get_api_key`	Fetch one key by `id`.	No
`create_api_key`	Mint an inference key. Secret returned once as `key`. Optional `name`/`label`, `api_shape`.	Yes
`update_api_key`	Rename (`name`/`label`) and/or `revoked: true\|false`.	Yes
`revoke_api_key`	Revoke by `id` (row retained; restore with `update_api_key`).	Yes
`get_usage_summary`	Totals for `range` `24h\|7d\|30d`. Optional `api_key_id`.	No
`get_usage_series`	Zero-filled time buckets. Same filters.	No
`get_usage_breakdown`	Top 12 by `by=model\|gateway`. Same filters.	No
`get_account`	Workspace profile + key/provider inventory. No secrets, no member emails.	No

New keys need routing A key created via MCP has an empty routing rule until you attach provider keys in the dashboard (API Keys → Routing rule). Calls on an unrouted key return 402.

No cost data by design Usage tools cover requests, errors, latency, models, and gateways only. The proxy never stores tokens or per-request cost.

Read-only keys

A management key flagged read-only can call every read tool. Write tools (create_api_key, update_api_key, revoke_api_key) return a tool error: This management API key is read-only. Writes are not allowed. The HTTP status stays 200 — that is MCP isError, not a JSON-RPC transport failure. Flag the key in Settings; a key cannot escalate itself.

MCP vs the management REST API

Same workspace operations, two protocols:

REST — https://app.freerouter.com/api/v1/keys (and /usage/*, /account). Best for backends and scripts. Documented on Management API Keys.
MCP — https://api.freerouter.com/mcp. Best for agents and IDEs.

Both take Authorization: Bearer $FREEROUTER_MANAGEMENT_KEY. Routing, provider keys, and inference stay off this surface in v1.

Next Management API Keys