MCP Gateway

AISIX can expose registered upstream MCP servers through a single MCP endpoint. Agents connect to AISIX, discover the tools their caller API key can access, and call those tools without receiving the upstream MCP server credential.

This gives agent tool traffic the same authentication, policy, and telemetry boundary as model traffic. AISIX authenticates the caller, checks tool access, routes the call to the registered upstream MCP server, and records MCP tool-call telemetry.

How MCP Gateway Works

Each upstream MCP server is registered as an Admin API resource. AISIX exposes that server's tools with a prefix based on the server display name.

AISIX uses two underscores to separate the registered server name from the upstream tool name. For example, github__create_issue means AISIX routes the call to the registered MCP server named github and calls its upstream tool named create_issue. The registered server name cannot 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 can see through AISIX:

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

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.

Register an Upstream MCP Server

Create an MCP server resource for the upstream endpoint:

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
  }'

AISIX stores the upstream credential with the MCP server resource. The caller API key sent by the MCP client is used to authenticate to AISIX, not to the upstream MCP server.

Grant Tool Access

Create a caller API key that can use the MCP tools you want to expose. Hash the plaintext caller key before creating the Admin API 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 tool names. 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__create_issue"]
  }'

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

Choose the narrowest tool access that matches the caller:

Tool access setting	Behavior
Specific tool names	Allows only the listed tools, such as github__create_issue.
["*"]	Allows every tool from every registered MCP server.
Omitted, null, or []	Allows no MCP tools.

The examples above show the fields needed for a basic MCP setup. For full resource schemas, see the Admin API Reference.

Connect an MCP Client

Configure the MCP client or agent to connect to the AISIX proxy endpoint at /mcp with Streamable HTTP. Send the caller API key to AISIX 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. The response includes only tools allowed by the caller API key. Tool calls use the prefixed tool name, such as github__create_issue.

Apply Traffic Controls

MCP tool calls use the same caller API key boundary as model requests. In managed deployments, AISIX Cloud budget checks can also apply.

AISIX applies those controls to tools/call requests. MCP handshake and tool discovery methods can still connect and list available tools, even when the caller has reached a tool-call rate limit.

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

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__create_issue"],
    "rate_limit": {
      "rpm": 1
    }
  }'

After this update, the MCP client can still connect and list permitted tools. A second tools/call request within the same minute is rejected with HTTP 429 before AISIX calls the upstream MCP server.

Use guardrails when AISIX should inspect MCP tool arguments or tool results. For guardrail setup, see Built-in Keyword Guardrails.

MCP usage events include the inbound protocol, MCP server name, and MCP tool name. Token and cost fields are zero for MCP tool calls because the gateway does not meter model tokens on this path.

Troubleshoot Tool Access

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

• The MCP server resource is enabled and its registered server name does not contain __, which AISIX reserves for MCP tool prefixes.
• The upstream MCP server is reachable from the AISIX gateway.
• The caller API key includes the exact prefixed tool name in allowed_tools.
• 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

Continue with Caller API Keys to manage caller credentials, or Guardrails to inspect MCP tool arguments and results.