# MCP Gateway Overview

The AISIX gateway fronts registered Model Context Protocol (MCP) tool sources through an aggregated `/mcp` endpoint. A source can be an upstream MCP server that uses Streamable HTTP or a REST API described by an OpenAPI document. See [Expose a REST API as MCP Tools](https://docs.api7.ai/ai-gateway/mcp-gateway/openapi-servers.md) for the REST API path.

MCP clients and agents connect to `/mcp` with an AISIX caller API key, discover the tools that key can use, and call those tools without receiving the upstream MCP server credential.

This gives tool traffic the same authentication, access-control, and telemetry boundary as model and A2A traffic. One caller API key can govern the models a caller may use, the MCP tools it may call, and the A2A agents it may reach.

AISIX authenticates every MCP request and filters tool discovery by the caller's effective tool grant. For `tools/call`, AISIX also applies rate limits and guardrails, checks applicable budgets in AISIX Enterprise and AISIX Cloud, routes the call with the configured upstream credential, and records usage telemetry.

## How the MCP Gateway Works[​](#how-the-mcp-gateway-works "Direct link to How the MCP Gateway Works")

Each MCP server has a `name`. In AISIX Enterprise and AISIX Cloud, the server is registered at the organization level and exposed to selected environments. In an open-source AISIX gateway, it is normally declared in `resources.yaml`. AISIX aggregates tools from enabled servers and exposes each tool under a prefixed name.

AISIX uses two underscores to separate the registered server name from the upstream tool name. For example, `github__create_issue` routes to the registered MCP server named `github` and calls its upstream tool named `create_issue`. In both the control-plane and resources-file paths, a server name cannot contain the reserved `__` separator, cannot contain `*`, and cannot end with an underscore. A server name is never a pattern, so a `*` in the server segment of a tool grant always means a glob rather than one particular server. A single underscore can appear inside a name, such as `internal_tools`. AISIX Enterprise and AISIX Cloud additionally limit names to 56 letters, digits, underscores, dots, or hyphens, with a letter or digit at each end.

## Get Started[​](#get-started "Direct link to Get Started")

Follow [Set Up MCP Gateway](https://docs.api7.ai/ai-gateway/mcp-gateway/setup.md) to register an upstream server through the AISIX Cloud Admin API or `resources.yaml` and grant one tool to a caller API key. The guide isolates the gateway path with allowed and denied HTTP checks. Then connect [Cursor](https://docs.api7.ai/ai-gateway/mcp-gateway/cursor.md) or [VS Code](https://docs.api7.ai/ai-gateway/mcp-gateway/vscode.md) to verify discovery, any required approval, and execution in a real MCP client. Both management paths configure the same gateway runtime and MCP endpoints.

## Client Connection[​](#client-connection "Direct link to Client Connection")

MCP clients connect to the AISIX proxy listener over Streamable HTTP. Use `/mcp` for the aggregated tool surface:

| Setting        | Value                                    |
| -------------- | ---------------------------------------- |
| Server URL     | `<gateway-origin>/mcp`                   |
| Transport      | Streamable HTTP                          |
| Request header | `Authorization: Bearer <caller-api-key>` |

The caller API key controls which tools the client can discover and call. The client connects only to AISIX; it does not receive upstream server URLs or credentials.

## Protocol Version Support[​](#protocol-version-support "Direct link to Protocol Version Support")

The AISIX gateway serves both current MCP protocol generations on `/mcp` and `/mcp/{server}` and negotiates with each client automatically, so no AISIX-specific client configuration is needed:

| MCP protocol revision | Client support | Notes                                                                                                     |
| --------------------- | -------------- | --------------------------------------------------------------------------------------------------------- |
| `2026-07-28`          | Supported      | Stateless revision: handshake-free startup through `server/discover`, with per-request protocol metadata. |
| `2025-11-25`          | Supported      | `initialize` handshake.                                                                                   |
| `2025-06-18`          | Supported      | `initialize` handshake.                                                                                   |
| `2025-03-26`          | Supported      | `initialize` handshake.                                                                                   |
| `2024-11-05`          | Not supported  | HTTP+SSE transport generation; the MCP endpoints serve Streamable HTTP only.                              |

Two version signals are involved, and the gateway handles each on its own terms. During the `initialize` handshake, the gateway echoes a requested `protocolVersion` of `2025-03-26`, `2025-06-18`, or `2025-11-25`. It answers `2025-11-25` for any other version, including `2026-07-28`, which has no `initialize` handshake. Separately, the `MCP-Protocol-Version` HTTP header is optional on requests outside the handshake: an absent header is accepted (and treated as `2025-03-26`, per the specification's compatibility rule), while a header naming an unsupported revision is rejected with HTTP `400` and a JSON-RPC error envelope that lists the supported revisions. A client on the `2026-07-28` lifecycle can start with `server/discover` instead of a handshake. Serving is stateless on every generation: the gateway issues no `Mcp-Session-Id`, so MCP requests need no session affinity across gateway replicas.

### Upstream Protocol Selection[​](#upstream-protocol-selection "Direct link to Upstream Protocol Selection")

The client-facing protocol and the upstream session are independent: the gateway terminates the client's protocol at the MCP endpoint and opens its own session to each registered server of `type: mcp`. (An `openapi` source has no upstream MCP session, so this setting does not apply to it.) The revision of that upstream session is a per-server setting, `protocol_version`:

| `protocol_version` | Upstream session behavior                                                                                                                                                                                  |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Not set (default)  | The gateway opens the session with the `initialize` handshake, which negotiates a supported 2025 Streamable HTTP revision. This also works with `2026-07-28` servers that continue to answer `initialize`. |
| `"2026-07-28"`     | The gateway opens the session with handshake-free `server/discover`. Required for servers that no longer answer `initialize`.                                                                              |

In `resources.yaml`, omit `protocol_version` to keep the default lifecycle. In AISIX Enterprise and AISIX Cloud, an existing pin is removed by setting `protocol_version` to `null` — omitting the field in an update leaves the pin in place. For the configuration steps on both management paths, see [Pin the MCP Protocol Revision](https://docs.api7.ai/ai-gateway/mcp-gateway/setup.md#pin-the-mcp-protocol-revision).

The selection is explicit: the gateway uses only the configured lifecycle and never probes or silently downgrades across protocol generations. When the configured lifecycle is incompatible with the server, `tools/list` logs the failure and omits that server's tools from the aggregated list, and a `tools/call` to it returns an upstream failure. The downstream and upstream selections stay independent of each other.

The gateway does not forward the caller's `MCP-Protocol-Version` or `Mcp-Session-Id` headers to the upstream server, and forwards the caller's `Authorization` only when the server's `forward_client_headers` names it exactly. It opens an independent upstream session using the server's registered authentication and protocol settings; a stateful upstream can mint its own session identifier for that session, and tool names, arguments, and results cross the boundary as the call requires.

Conformance

The gateway's continuous integration runs the applicable tools-surface scenarios from the official MCP conformance suite against the served gateway and bridge chain, as a merge-blocking check.

## Govern MCP Tool Calls[​](#govern-mcp-tool-calls "Direct link to Govern MCP Tool Calls")

MCP tool calls use the same caller API key identity and telemetry pipeline as model requests. They share the key's request and concurrency limits with model traffic. Applicable guardrails and, in AISIX Enterprise and AISIX Cloud, budgets that cover the caller also apply. MCP-specific controls include per-server rate limits and tool authorization: each key can carry its own grant, and the control plane can add environment and team layers.

Use these guides to refine the MCP path:

* [Control Tool Access](https://docs.api7.ai/ai-gateway/mcp-gateway/tool-access-control.md): scope each caller API key to the tools it may list and call.
* [Rate Limits and Budgets](https://docs.api7.ai/ai-gateway/mcp-gateway/traffic-controls.md): apply caller API key request and concurrency limits, and use budgets for `tools/call` requests.
* [Guardrails](https://docs.api7.ai/ai-gateway/mcp-gateway/guardrails.md): inspect MCP tool arguments and results.
* [Observability](https://docs.api7.ai/ai-gateway/mcp-gateway/observability.md): investigate MCP requests in access logs and monitor tool calls through usage events and metrics.

AISIX Enterprise and AISIX Cloud also provide shared [MCP access policies](https://docs.api7.ai/ai-gateway/mcp-gateway/access-policies.md) and a [server review and approval workflow](https://docs.api7.ai/ai-gateway/mcp-gateway/server-review.md).

## Per-Server Endpoints[​](#per-server-endpoints "Direct link to Per-Server Endpoints")

Use `/mcp/{server}` when a client expects a separate URL for each registered MCP server. The endpoint presents only the named server. `initialize` reports its registered name, and `tools/list` normally returns permitted tools under their original upstream names. `tools/call` accepts both an original name such as `create_issue` and its aggregated form such as `github__create_issue`.

Authentication, tool access, rate limits, guardrails, usage telemetry, and budgets work the same way as on `/mcp`. Access grants and per-server rate limits keep their `{server}__{tool}` identity across both endpoints, so using both URL forms does not create a second allowance. An unknown or disabled server returns 404 after caller authentication.

For tool-name collision behavior and endpoint errors, see [Proxy API Reference](https://docs.api7.ai/ai-gateway/reference/proxy-api.md#mcp-gateway). If an existing client uses another URL shape, such as `/mcp-servers/{server}/mcp`, map it to `/mcp/{server}` with [URL rewriting](https://docs.api7.ai/ai-gateway/deployment/url-rewriting.md#example-serve-per-server-mcp-urls).

## Troubleshoot Tool Access[​](#troubleshoot-tool-access "Direct link to Troubleshoot Tool Access")

If a client cannot see or call a tool, check these items:

* The MCP server resource is `enabled`.
* In AISIX Enterprise and AISIX Cloud, the server is `approved` and its `allowed_environments` includes the caller key's environment.
* The upstream MCP server is reachable from the AISIX gateway, and the configured upstream authentication is valid. See [Upstream Authentication](https://docs.api7.ai/ai-gateway/mcp-gateway/upstream-authentication.md).
* The caller API key's effective tool grant covers the prefixed tool name. That grant is the intersection of every layer that applies: the key's own `mcp_access` block and, in AISIX Enterprise and AISIX Cloud, the environment and team [MCP access policies](https://docs.api7.ai/ai-gateway/mcp-gateway/access-policies.md).
* The MCP client sends the caller API key to AISIX, not the upstream MCP credential.
* Check the request's [MCP access log](https://docs.api7.ai/ai-gateway/mcp-gateway/observability.md#access-logs) for protocol, upstream-discovery, or access-policy problems.

For MCP error response behavior, see [Headers and Error Codes](https://docs.api7.ai/ai-gateway/reference/headers-and-error-codes.md#mcp-errors). For endpoint-level behavior, see [Proxy API Reference](https://docs.api7.ai/ai-gateway/reference/proxy-api.md#mcp-gateway).
