---
title: "JSON-RPC 2.0 endpoint for the gateway's MCP server"
method: POST
path: "/mcp"
tags: ["MCP"]
---

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

`POST /mcp`

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:

| Method | Params | Result |
| --- | --- | --- |
| `initialize` | `protocolVersion`, `capabilities`, `clientInfo` (`Implementation`) | `protocolVersion`, `capabilities` (`ServerCapabilities`, `tools.listChanged`), `serverInfo` (`Implementation`) |
| `notifications/initialized` | none | none - it is a JSON-RPC notification, sent without `id`, answered with `202` and an empty body |
| `tools/list` | optional `cursor` | `ListToolsResult` - the aggregated, namespaced tools of every healthy MCP server |
| `tools/call` | `CallToolRequestParams` (`name`, `arguments`) | `CallToolResult` |

Param and result shapes are the vendored MCP spec types in
[`mcp/mcp-schema.yaml`](https://github.com/inference-gateway/schemas/blob/main/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.

## Request body

- MCPJSONRPCRequest — A JSON-RPC 2.0 request or notification sent to `POST /mcp`. Omit `id` to send a notification (`notifications/initialized`). `params` and the corresponding `result` follow the vendored MCP spec types in `mcp/mcp-schema.yaml`: `initialize` takes `protocolVersion`, `capabilities` and `clientInfo`; `tools/list` takes an optional `cursor`; `tools/call` takes `CallToolRequestParams`. Tool names are namespaced `mcp_<server alias>_<tool name>`, e.g. `mcp_deepwiki_ask_question`. The alias comes from the `alias=url` syntax in `MCP_SERVERS` and is derived from the URL host when omitted; it must match `^[a-z0-9_-]+$` so the resulting tool name stays valid across all LLM providers. The same namespacing applies to the tools injected into `/v1/chat/completions`. `mcp_tools_get` and `mcp_tools_execute` are reserved for the gateway's own selector meta-tools and cannot be used by a configured server.
  - `jsonrpc` '2.0', required — JSON-RPC protocol version, always "2.0"
  - `id` union — Request identifier echoed back in the response. Absent for notifications.
    - string
    - integer
  - `method` 'initialize' | 'notifications/initialized' | 'tools/list' | 'tools/call', required — The MCP method to invoke
  - `params` object — Method parameters, as defined by the MCP specification

## Response `200`

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

- MCPJSONRPCResponse — A JSON-RPC 2.0 response envelope. Exactly one of `result` or `error` is present. `result` carries the MCP result type for the requested method (`ListToolsResult` for `tools/list`, `CallToolResult` for `tools/call`) as defined in `mcp/mcp-schema.yaml`.
  - `jsonrpc` '2.0', required — JSON-RPC protocol version, always "2.0"
  - `id` union, required — The `id` of the request this responds to
    - string
    - integer
  - `result` object — The method result, present on success
  - `error` MCPJSONRPCError — A JSON-RPC 2.0 error object
    - `code` integer, required — JSON-RPC error code: `-32700` parse error, `-32600` invalid request, `-32601` method not found, `-32602` invalid params, `-32603` internal error (including upstream MCP server failures).
    - `message` string, required — Short description of the error
    - `data` unknown

## Other responses

- `202` — Notification accepted; no response body
- `401` — Unauthorized
- `403` — The MCP surface is not exposed. Both `MCP_ENABLED=true` and `MCP_EXPOSE=true` are required.
- `500` — Internal server error

## Changes

- **2026-09-24** `b12d4368f3a8` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/inference-gateway/apis/inference-gateway-api/changes/mcp/post.md)

---

[API](https://skmtc.dev/inference-gateway/apis/inference-gateway-api.md) · [All operations](https://skmtc.dev/inference-gateway/apis/inference-gateway-api/llms.txt) · [OpenAPI document](https://skmtc.dev/inference-gateway/apis/inference-gateway-api/revisions/befd6c1f4391?raw)