MCP API Reference

AnyRouter runs a Model Context Protocol server that exposes your workspace — models, keys, presets, credits, and status — as JSON-RPC tools. This page is the protocol reference: tools, arguments, scopes, errors, and the manual auth path for clients that can't run OAuth.

For step-by-step client setup (Claude Desktop, Claude Code, Cursor, OpenCode, …), see MCP Server. The MCP server does not expose a chat tool — clients call the Chat Completions, Messages, or Responses endpoints 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

The list_hubs … hub_import_skill tools manage the Skills & Knowledge Hub from inside your agent.

Admin tools

Accounts registered as AnyRouter administrators see additional tools (hidden from tools/list for everyone else). They work with either an LLM key (sk-ar-v1-*) or a management key (ak_*).

admin_request is the general gateway; admin_list_endpoints returns the full live catalog. Endpoints flagged dangerous (destructive or costly) require confirm: true.

Scopes and consent bundles

When a client requests authorization, the user picks one bundle on the AnyRouter consent screen. Users can downgrade from what a client requests; a tool needing a scope outside the granted bundle returns permission denied.

read:hub / write:hub gate the Skills & Knowledge Hub tools. read:credits gates get_credits; list_models, get_system_status, and the knowledge-base tools need no scope. Tools that always work (like list_models) require no bundle at all.

Manual authentication

Clients that cannot run OAuth authenticate with a static bearer token: an LLM API key (sk-ar-v1-*, grants list_models only) 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 normal JSON-RPC success envelope. The tool's output lives in result.content — an array of content blocks. AnyRouter tools return 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

When a tool fails (an invalid argument, an unknown id, an upstream error), the call still returns a successful JSON-RPC envelope. Per the MCP spec, the failure is reported in-band on the result with isError: true and the message in result.content[0].text — there is no top-level error object:

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

Detect a failed tool call by checking result.isError — not response.error. A top-level error object is reserved for protocol/transport failures, not tool failures. For example, an unauthenticated request returns HTTP 401 with:

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

Errors

Rate limits

The MCP endpoint is rate limited to protect your workspace and keep the service responsive:

• Per credential — up to 120 tool calls per minute for each API key or token.
• Per IP — up to 300 requests per minute from a single IP address (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 limits are on the management tier and are separate from the inference rate limits that apply to Chat Completions, Messages, and Responses.

Revoking access

To revoke an MCP client's access, open /dashboard/mcp, find the client under Connected clients, and click Revoke. The token is deleted immediately; subsequent tool calls return 401 Unauthorized. Revoking does not uninstall the client config — the next tool invocation simply re-runs OAuth.

Related

• MCP Server — step-by-step client setup
• Management API Keys — the ak_… keys and scopes used here
• Credits API — what get_credits returns