Skip to main content
API7.ai Logo

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 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 AISIX Cloud budgets, routes the call with the configured upstream credential, and records usage telemetry.

How the MCP Gateway Works​

Each MCP server has a name. In 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. Across both management paths, a server name cannot contain the reserved __ separator or end with an underscore. A single underscore can appear inside a name, such as internal_tools. AISIX Cloud additionally limits names to 56 letters, digits, underscores, dots, or hyphens, with a letter or digit at each end.

Get Started​

Follow Set Up MCP Gateway to register an upstream server through AISIX Cloud 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 or VS Code 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​

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

SettingValue
Server URL<gateway-origin>/mcp
TransportStreamable HTTP
Request headerAuthorization: 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​

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 revisionClient supportNotes
2026-07-28SupportedStateless revision: handshake-free startup through server/discover, with per-request protocol metadata.
2025-11-25Supportedinitialize handshake.
2025-06-18Supportedinitialize handshake.
2025-03-26Supportedinitialize handshake.
2024-11-05Not supportedHTTP+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 supported protocolVersion from the request and answers 2025-11-25 for an unsupported one. 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​

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_versionUpstream 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 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.

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​

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 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 AISIX Cloud can add environment and team layers.

Use these guides to refine the MCP path:

  • Control Tool Access: scope each caller API key to the tools it may list and call.
  • Rate Limits and Budgets: apply caller API key request and concurrency limits, and use AISIX Cloud budgets for tools/call requests.
  • Guardrails: inspect MCP tool arguments and results.
  • Observability: review the usage events and metrics emitted by MCP tool calls.

AISIX Cloud also provides shared MCP access policies and a server review and approval workflow.

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 AISIX Cloud 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. If an existing client uses another URL shape, such as /mcp-servers/{server}/mcp, map it to /mcp/{server} with URL rewriting.

Troubleshoot Tool Access​

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

  • The MCP server resource is enabled.
  • In 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.
  • 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 Cloud, the environment and team MCP access policies.
  • The MCP client sends the caller API key to AISIX, not the upstream MCP credential.

For MCP error response behavior, see Headers and Error Codes. For endpoint-level behavior, see Proxy API Reference.

Next Steps​

Use these guides to configure how MCP traffic is handled: