MCP API Reference

AnyRouter runs a Model Context Protocol server that exposes your models, keys, presets, credits and status as JSON-RPC tools.

Client setup is in MCP Server. There is no chat tool: call Chat Completions, Messages or Responses directly.

Request

• Endpoint: POST https://anyrouter.dev/api/v1/mcp
• Protocol: JSON-RPC 2.0 over HTTPS (Streamable HTTP transport)
• Content type: application/json
• Authentication: OAuth 2.1 bearer token, or a static API key (see below)

Tools

list_hubs … hub_import_skill manage the Skills & Knowledge Hub. The artifact tools are described in the Artifacts API.

Admin tools

Administrator accounts see extra tools (hidden from tools/list for everyone else), usable with an LLM key or a management key.

admin_list_endpoints returns the live endpoint catalog. Dangerous endpoints (destructive or costly) require confirm: true.

Scopes and consent bundles

The user picks one bundle on the consent screen and can downgrade what a client requests. A tool outside the granted bundle returns permission denied.

read:hub / write:hub gate the Skills & Knowledge Hub tools; read:credits gates get_credits, read:analytics gates get_usage, read:byok gates list_byok_keys. list_models, recommend_model, get_system_status and the knowledge-base tools need no scope. An LLM key (sk-ar-v1-*) can call those and the artifact tools, and nothing else; a key whose endpoint allow-list leaves out Artifacts does not see the artifact tools.

Manual authentication

Clients that cannot run OAuth send a static bearer token: an LLM API key (sk-ar-v1-*) or a Management API key (ak_*) with the scopes you need.

curl https://anyrouter.dev/api/v1/mcp \
  -H "Authorization: Bearer ak_your_management_key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}'

Response

A tool call returns a JSON-RPC success envelope. Output is in result.content: a single text block whose text is a JSON payload:

{
  "jsonrpc": "2.0",
  "result": {
    "content": [{ "type": "text", "text": "{ \"total\": 3, \"data\": [ ... ] }" }]
  },
  "id": 1
}

Tool failures

A failed tool call (invalid argument, unknown id, upstream error) still returns a success envelope. The failure is in-band: isError: true with the message in result.content[0].text, and no top-level error:

{
  "jsonrpc": "2.0",
  "result": {
    "content": [{ "type": "text", "text": "Key key_123 not found in this workspace." }],
    "isError": true
  },
  "id": 1
}

Check result.isError, not response.error. A top-level error is only for protocol/transport failures, for example an unauthenticated request (HTTP 401):

{
  "jsonrpc": "2.0",
  "error": { "code": -32001, "message": "Unauthorized" },
  "id": null
}

Errors

Rate limits

• Per credential: up to 120 tool calls per minute for each API key or token.
• Per IP: up to 300 requests per minute (applied before authentication, so it also covers failed sign-ins).

Crossing a limit returns HTTP 429 with a Retry-After header and a JSON-RPC error body:

{
  "jsonrpc": "2.0",
  "error": { "code": -32000, "message": "Rate limit exceeded — retry after 60s." },
  "id": null
}

These are management-tier limits, separate from the inference rate limits.

Artifact tools only

Add ?tools=artifacts to the gateway URL to get only the five artifact tools: no other tools, resources or connected servers.

claude mcp add --transport http anyrouter-artifacts \
  "https://anyrouter.dev/api/v1/mcp?tools=artifacts" \
  --header "Authorization: Bearer $ANYROUTER_API_KEY"

Scopes still apply: a management key needs read:artifacts / write:artifacts. An unknown tools value returns 400.

Auto-connect config

The anyr CLI reads one workspace setting to decide whether to connect this gateway in the agents it launches (anyr claude, anyr codex, anyr opencode, anyr grok).

curl https://anyrouter.dev/api/v1/mcp/config \
  -H "Authorization: Bearer $ANYROUTER_API_KEY"

{
  "workspace_id": "ws_123",
  "enabled": true,
  "setting": null,
  "default": true,
  "url": "https://anyrouter.dev/api/v1/mcp",
  "auth": { "header": "Authorization", "scheme": "Bearer", "credential": "caller_key" },
  "can_edit": true,
  "artifacts": { "enabled": true, "url": "https://anyrouter.dev/api/v1/mcp?tools=artifacts" }
}

GET accepts an inference key (sk-ar-v1-…) or a signed-in session. A management key (ak_…) is not accepted here. A key whose endpoint allow-list leaves out MCP gets 403.

To change it, PATCH from a dashboard session as the workspace owner with { "enabled": true }, { "enabled": false }, or { "enabled": null } for the default. The response has the same shape as GET.

To opt out on one machine instead, pass --no-mcp on a launch or run anyr mcp auto off.

Revoking access

Open /dashboard/mcp, find the client under Connected clients and click Revoke. The token is deleted at once and later calls return 401 Unauthorized. The client config stays; its next call re-runs OAuth.