MCP Gateway Overview

AISIX AI Gateway exposes registered upstream MCP (Model Context Protocol) servers through a single MCP endpoint. Agents connect to AISIX, discover the tools their caller API key can access, and call those tools without ever receiving the upstream MCP server credential.

This gives agent tool traffic the same authentication, access control, policy, and telemetry boundary as model traffic. One caller API key governs both the models a caller may use and the MCP tools it may call. AISIX authenticates the caller, checks tool access, and applies traffic controls and guardrails. It then routes the call to the registered upstream MCP server using the credential you configured, and records MCP tool-call telemetry.

This page introduces the MCP gateway and walks through a minimal end-to-end setup. For depth on each area, see:

• Upstream authentication — how AISIX authenticates to each upstream MCP server (none, bearer, api_key, oauth2).
• Control tool access per key — how allowed_tools on a caller API key decides which tools that key can list and call.

How the MCP Gateway Works

Each upstream MCP server is registered as a gateway resource. AISIX exposes that server's tools under a prefix derived from the server's registered 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. The registered server name must not contain __, because AISIX reserves that separator for MCP tool routing. This double-underscore separator is specific to aggregated MCP tool names — single underscores are still used in regular field names such as display_name and allowed_tools.

The flow below shows three registered upstream MCP servers and the prefixed tool names an MCP client sees through AISIX:

MCP clients connect to the AISIX proxy listener at /mcp. Upstream MCP servers must use the Streamable HTTP transport.

Prerequisites

Before starting, prepare the following:

• A self-hosted AISIX gateway with the admin and proxy listeners available.
• The admin key from the gateway config.yaml.
• An upstream MCP server reachable from the gateway over Streamable HTTP.
• A caller API key value that the MCP client will send to AISIX.

Managed deployments

On AISIX Cloud, you register MCP servers and grant tool access from the dashboard instead of the Admin API, scoped to an organization and exposed per environment. The concepts on this page are identical; only the management surface differs. See AISIX Cloud.

Register an Upstream MCP Server

Create an MCP server resource for the upstream endpoint. This example uses a bearer-token upstream; for the other authentication modes, see Upstream authentication.

export AISIX_ADMIN_KEY="YOUR_ADMIN_KEY"
export MCP_UPSTREAM_TOKEN="YOUR_UPSTREAM_MCP_TOKEN"

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/mcp_servers" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "github",
    "url": "https://mcp.example.com/mcp",
    "auth_type": "bearer",
    "secret": "'"${MCP_UPSTREAM_TOKEN}"'",
    "timeout_ms": 5000
  }'

Key fields:

Field	Notes
display_name	The tool-name prefix for this server. Must be non-empty and must not contain the reserved __ separator.
url	The upstream MCP endpoint.
transport	Defaults to streamable_http, the only supported transport.
auth_type	How AISIX authenticates upstream: none, bearer, api_key, or oauth2. See Upstream authentication.
secret	The upstream credential for the chosen auth_type. Write-only — AISIX stores it and never returns it.
timeout_ms	Per-request timeout for upstream calls.
enabled	Whether the server is dispatched. Defaults to true; set false to keep the registration but stop exposing its tools.

AISIX stores the upstream credential with the MCP server resource. The caller API key sent by the MCP client authenticates the caller to AISIX — it is never forwarded to the upstream MCP server.

Grant Tool Access

An MCP client sees and can call only the tools its caller API key allows. Create a caller API key with the tools you want to expose. Hash the plaintext caller key before creating the resource:

export AISIX_ADMIN_KEY="YOUR_ADMIN_KEY"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"

AISIX_API_KEY_HASH=$(printf '%s' "${AISIX_API_KEY}" | shasum -a 256 | awk '{print $1}')

Create the API key resource with the allowed tools. Use an empty model allowlist when the key is only for MCP traffic:

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/apikeys" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "key_hash": "'"${AISIX_API_KEY_HASH}"'",
    "allowed_models": [],
    "allowed_tools": ["github__*"]
  }'

["github__*"] grants every tool on the github server. To grant one tool, list its exact prefixed name; to grant everything, use ["*"]. For the full matching rules, see Control tool access per key.

Save the returned id if you want to update this caller API key later.

Connect an MCP Client

Configure the MCP client or agent to connect to the AISIX proxy endpoint at /mcp over Streamable HTTP, sending the caller API key in the Authorization header.

If your MCP client accepts JSON settings, map these values into the client-specific schema. The exact field names vary by client:

{
  "mcpServers": {
    "aisix": {
      "url": "http://127.0.0.1:3000/mcp",
      "transport": "Streamable HTTP",
      "headers": {
        "Authorization": "Bearer YOUR_CALLER_API_KEY"
      }
    }
  }
}

After the client connects, list tools from the client.

Expected result: the tool list contains only the tools the caller API key allows (here, every github__* tool). Tool calls use the prefixed name, such as github__create_issue.

Apply Traffic Controls

MCP tool calls pass through the same caller API key boundary as model requests, so the same controls apply:

• Rate limits and budgets. AISIX applies rate limits to tools/call requests. The MCP handshake and tool discovery (tools/list) still connect and list tools even when the caller has reached a tool-call rate limit. In managed deployments, AISIX Cloud budget checks also apply.
• Guardrails. Attach guardrails to inspect MCP tool-call arguments (input) and tool results (output). A blocked call is rejected with an MCP error and is never sent upstream. See Guardrails.
• Telemetry. MCP usage events record the inbound protocol, the MCP server name, and the MCP tool name. Token and cost fields are zero for MCP tool calls because the gateway does not meter model tokens on this path.

For example, to limit one caller to one MCP tool call per minute, update the caller API key with a rate limit. Updates replace the resource, so include the existing key hash and tool access:

curl -sS -X PUT "http://127.0.0.1:3001/admin/v1/apikeys/YOUR_API_KEY_ID" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "key_hash": "'"${AISIX_API_KEY_HASH}"'",
    "allowed_models": [],
    "allowed_tools": ["github__*"],
    "rate_limit": {
      "rpm": 1
    }
  }'

Expected result: the client can still connect and list permitted tools, but a second tools/call within the same minute is rejected with HTTP 429 before AISIX calls the upstream MCP server.

Troubleshoot Tool Access

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

• The MCP server resource is enabled and its registered name does not contain __.
• 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 allowed_tools covers the prefixed tool name (an exact name, a <server>__* grant, or *).
• 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

• Upstream authentication — configure none, bearer, api_key, or oauth2 for each upstream server.
• Control tool access per key — scope callers to specific tools, whole servers, or everything.
• Caller API Keys — manage caller credentials.
• Guardrails — inspect MCP tool arguments and results.