Sign in
MCP

JSON-RPC 2.0 endpoint for the gateway's MCP server

JSON-RPC 2.0 endpoint exposing the gateway itself as an MCP server. It aggregates every server configured in MCP_SERVERS behind one URL, so MCP clients (opencode, infer, IDE assistants) configure a single entry and get the whole fleet, with the gateway's auth, metrics and guardrails applied to every tool call.

The endpoint lives at the root, not under /v1 - /v1/* is the OpenAI-compatible surface, MCP is its own protocol and clients expect a plain /mcp.

Gated by MCP_EXPOSE=true (and MCP_ENABLED=true); otherwise the gateway answers 403. Gateway auth is global, so when AUTH_ENABLE=true this endpoint requires a bearer token like every other route except /health.

Supported methods:

MethodParamsResult
initializeprotocolVersion, capabilities, clientInfo (Implementation)protocolVersion, capabilities (ServerCapabilities, tools.listChanged), serverInfo (Implementation)
notifications/initializednonenone - it is a JSON-RPC notification, sent without id, answered with 202 and an empty body
tools/listoptional cursorListToolsResult - the aggregated, namespaced tools of every healthy MCP server
tools/callCallToolRequestParams (name, arguments)CallToolResult

Param and result shapes are the vendored MCP spec types in mcp/mcp-schema.yaml (Implementation, ServerCapabilities, ListToolsResult, CallToolRequestParams, CallToolResult); this spec only describes the JSON-RPC envelopes the gateway puts them in.

tools/list tolerates partial availability: when one of the configured MCP servers is unreachable its tools are omitted and the healthy servers' tools are still returned, rather than failing the whole call. A tools/call routed to an unavailable server fails with JSON-RPC error code -32603.

Errors use the standard JSON-RPC codes - -32700 parse error, -32600 invalid request, -32601 method not found (unknown method), -32602 invalid params (unknown tool name, bad arguments), -32603 internal error (upstream MCP server failure). They are returned with HTTP 200 and a JSON-RPC error envelope; transport-level failures (auth, feature flag) use HTTP status codes instead.

post/mcp

Request body

jsonrpc'2.0' required

JSON-RPC protocol version, always "2.0"

method'initialize' | 'notifications/initialized' | 'tools/list' | 'tools/call' required

The MCP method to invoke

paramsobject

Method parameters, as defined by the MCP specification

Example request

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "mcp_deepwiki_ask_question",
    "arguments": {
      "repoName": "inference-gateway/inference-gateway",
      "question": "How is MCP wired up?"
    }
  }
}

Response

JSON-RPC response envelope, carrying either a result or an error.

jsonrpc'2.0' required

JSON-RPC protocol version, always "2.0"

resultobject

The method result, present on success

Example response

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "unknown tool: mcp_deepwiki_missing_tool"
  }
}

Changes