MCP Gateway Overview

AISIX AI Gateway fronts registered upstream Model Context Protocol (MCP) servers through one gateway endpoint. An MCP server is a registry entry for one upstream server that speaks MCP over Streamable HTTP.

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, policy, 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 the caller, checks tool access, and applies rate limits, budgets, and guardrails. It then routes the call to the registered upstream MCP server using the credential you configured and records MCP usage telemetry.

The example below registers a server, grants tool access, and connects an MCP client through a self-hosted gateway.

How the MCP Gateway Works

Each upstream MCP server is registered as a gateway resource under a display_name. 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. The registered server name must not contain __, because AISIX reserves that separator for MCP tool routing; single underscores are still valid in regular field names.

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

Register and Connect to an MCP Server

The example below registers one upstream MCP server, grants a caller API key access to that server's tools, and connects an MCP client through the gateway.

Prerequisites

The following example uses a self-hosted AISIX gateway. Before running it, prepare the following:

• An 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.

For managed deployments, use the control plane instead of the self-hosted Admin API commands. Register MCP servers from the MCP servers page, expose them to the target environments, and configure tool access, rate limits, budgets, and guardrails from the same control plane. The concepts are the same; only the management surface differs. This workflow is available with AISIX Cloud and AISIX Cloud On-Premises.

Register an Upstream MCP Server

This example registers an upstream MCP server that uses bearer-token authentication. Create the server resource for the upstream endpoint:

# Replace with your values
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
  }'

❶ display_name becomes the namespace prefix for this server's tools, such as github__create_issue. It must be unique and cannot contain __.

❷ url is the upstream MCP endpoint AISIX reaches over Streamable HTTP.

❸ auth_type: "bearer" tells AISIX to authenticate upstream with a bearer token. For other credential modes, see Upstream authentication.

❹ secret stores the upstream credential gateway-side. AISIX uses it for upstream requests and never returns it to callers.

❺ timeout_ms bounds each upstream operation, including connecting, listing tools, and calling a tool.

You should see a response similar to the following:

{
  "id": "6f64f080-17d7-44d9-b995-6a353e71f6bc",
  "value": {
    "display_name": "github",
    "url": "https://mcp.example.com/mcp",
    "transport": "streamable_http",
    "auth_type": "bearer",
    "timeout_ms": 5000,
    "enabled": true
  },
  "revision": 1
}

Save the returned id if you plan to update, inspect, or delete this server later.

For upstream credential options, see Upstream authentication.

For the complete request and response schema, see Create MCP Server in the Admin API Reference.

Grant Tool Access

A caller connects to /mcp with an AISIX caller API key, not the admin key. Access is granted explicitly: a key with no allowed_tools can list or call no MCP tools.

Create a caller API key with the tools you want it to reach. Hash the plaintext caller key before creating the resource:

# Replace with your values
export AISIX_ADMIN_KEY="YOUR_ADMIN_KEY"
export AISIX_API_KEY="sk-demo-caller"

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

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__*"]
  }'

❶ Use an empty model allowlist when the key is only for MCP traffic.

❷ ["github__*"] grants every tool exposed by the github server. Use an exact prefixed tool name to grant one tool, or ["*"] to grant every MCP tool. For matching details, see Control tool access.

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. The client sends 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 sk-demo-caller"
      }
    }
  }
}

After the client connects, list tools from the client. The tool list contains only the tools the caller API key allows. In this example, tool calls use the github__ prefix, such as github__create_issue.

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 limits, concurrency limits, and budgets to tools/call requests.
• Guardrails: inspect MCP tool arguments and results.
• Observability: review the usage events and metrics emitted by MCP tool calls.

Troubleshoot Tool Access

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

• The MCP server resource is enabled.
• 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, using 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

You have now learned how to register an MCP server, grant caller access, and connect an MCP client through AISIX. Use these guides to refine how MCP traffic is handled:

• Upstream authentication: configure how AISIX authenticates to each upstream server.
• Control tool access: scope callers to specific tools, whole servers, or every tool.
• Rate limits and budgets: apply caller API key request limits, concurrency limits, and budgets to tool calls.
• Guardrails: inspect MCP tool arguments and results.
• Observability: review the usage events and metrics emitted by MCP tool calls.