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, grant one tool to a caller API key, and verify allowed and denied calls. 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.

Govern MCP Tool Calls​

MCP tool calls use the same caller API key boundary as model requests. You do not configure a separate policy stack for MCP traffic.

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. For direct per-key configuration, check allowed_tools; for AISIX Cloud policy-based access, check the applicable MCP access policy and the key's mcp_access settings.
  • 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: