Skip to main content
Version: 1.11.0

Set Up MCP Gateway

AISIX MCP Gateway places registered MCP servers behind one /mcp endpoint and enforces which tools each caller can use. This lets applications reach approved tools through AISIX without connecting to each upstream server directly.

Start the local Everything test server, register it with AISIX, grant its echo tool to one caller key, then verify both allowed and denied calls.

Prerequisites​

Before starting, prepare the following:

  • For AISIX Enterprise, complete the AISIX Enterprise getting-started guide, then keep its shell and aisix-dp gateway running. For AISIX Cloud, obtain an environment, attached gateway, caller API key, and gateway URL from your organization.
  • For Dashboard workflows, sign in with permission to create or submit MCP servers and update caller API keys. For Admin API workflows, obtain a write-scoped token from an identity allowed to manage MCP servers and API keys.
  • For the open-source AISIX gateway, complete the AISIX OSS getting-started guide, then remain in its shell and working directory with the aisix-quickstart gateway running.
  • Docker, cURL, and jq.

Start an MCP Test Server​

The example runs the official MCP Everything test server in Docker. The server and your existing gateway join a temporary Docker network, so the gateway can reach the server without a restart. Use the Everything server only for local testing: it has no authentication and includes a diagnostic tool that can return its process environment. The container used here receives no secrets. Stop and remove it after finishing the guide.

Set the gateway container name for your configuration path.

For AISIX Enterprise or AISIX Cloud:

export AISIX_GATEWAY_CONTAINER="aisix-dp"

For the open-source AISIX gateway:

export AISIX_GATEWAY_CONTAINER="aisix-quickstart"

Create a temporary network and connect the running gateway to it:

docker network create aisix-mcp
docker network connect aisix-mcp "$AISIX_GATEWAY_CONTAINER"

Start the Everything server on the same network:

docker run -d --name aisix-mcp-everything \
--network aisix-mcp \
node:22-alpine \
sh -c 'npx -y @modelcontextprotocol/server-everything@2026.7.4 streamableHttp'

Wait until the server is ready:

for attempt in $(seq 1 120); do
docker logs aisix-mcp-everything 2>&1 | grep -q "listening on port 3001" && break
sleep 1
done

docker logs aisix-mcp-everything 2>&1 | grep "listening on port 3001"

The final command prints a log line confirming that port 3001 is ready. From the gateway container, the MCP endpoint is available at http://aisix-mcp-everything:3001/mcp.

Register the Server and Grant a Tool​

Register the server using the management path for your deployment. Both paths name the server everything and grant only its echo tool to the existing quickstart caller.

  1. Open MCP servers and select New MCP server. If your role allows only submissions, select Submit MCP server.
  2. Keep MCP server selected. Enter everything as the name and http://aisix-mcp-everything:3001/mcp as the URL.
  3. Keep Authentication set to None and Enabled selected. Under Available in environments, select the environment served by the test gateway.
Everything MCP server URL and environment configured in the new-server form
  1. Select Register MCP server, or Submit MCP server for a submission-only role. If you submitted it, wait for an authorized operator to approve it. Confirm that the row shows Approved, Enabled, and the selected environment.
Saved everything MCP server showing Approved, Enabled, and the selected environment
  1. Follow Control Tool Access to grant everything__echo to the caller key.

Export the plaintext caller key before verifying access:

export AISIX_MCP_KEY="YOUR_CALLER_API_KEY"

Verify MCP Tool Access with HTTP​

Before introducing an editor, run a protocol-level check that isolates the gateway configuration, caller grant, and upstream server. The verification commands are the same for the control-plane and resources-file paths. They use the existing AISIX_PROXY value and the caller credential saved in AISIX_MCP_KEY.

An MCP client performs the initialization exchange automatically. Send an initialization request directly to verify the endpoint:

curl -fsS -X POST "$AISIX_PROXY/mcp" \
-H "Authorization: Bearer $AISIX_MCP_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-11-25",
"capabilities": {},
"clientInfo": {"name": "aisix-setup", "version": "1.0"}
}
}' | jq -e '.result.capabilities.tools'

A successful response includes the server's tools capability. Complete the initialization exchange:

curl -fsS -o /dev/null -w "%{http_code}\n" \
-X POST "$AISIX_PROXY/mcp" \
-H "Authorization: Bearer $AISIX_MCP_KEY" \
-H "MCP-Protocol-Version: 2025-11-25" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"method": "notifications/initialized"
}'

The notification returns HTTP 202 with no response body.

The control plane can take a few seconds to project configuration to a gateway. Poll the tool list for up to 90 seconds, then verify that only the allowed tool is visible:

for attempt in $(seq 1 45); do
TOOLS_RESPONSE=$(curl -fsS -X POST "$AISIX_PROXY/mcp" \
-H "Authorization: Bearer $AISIX_MCP_KEY" \
-H "MCP-Protocol-Version: 2025-11-25" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/list",
"params": {}
}') || true

if echo "$TOOLS_RESPONSE" | jq -e \
'.result.tools | map(.name) == ["everything__echo"]' >/dev/null 2>&1; then
break
fi
sleep 2
done

echo "$TOOLS_RESPONSE" | jq -e \
'.result.tools | map(.name) == ["everything__echo"]'

The final command prints true. Call the permitted tool:

curl -fsS -X POST "$AISIX_PROXY/mcp" \
-H "Authorization: Bearer $AISIX_MCP_KEY" \
-H "MCP-Protocol-Version: 2025-11-25" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "everything__echo",
"arguments": {"message": "hello through AISIX"}
}
}' | jq -e \
'.result.content[] | select(.text == "Echo: hello through AISIX")'

The command prints the matching tool-result content block. To verify that the allowlist is enforced, attempt to call another tool from the same upstream server:

curl -fsS -X POST "$AISIX_PROXY/mcp" \
-H "Authorization: Bearer $AISIX_MCP_KEY" \
-H "MCP-Protocol-Version: 2025-11-25" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {
"name": "everything__get-sum",
"arguments": {"a": 1, "b": 2}
}
}' | jq -e \
'.error.message == "tool '\''everything__get-sum'\'' is not available"'

The command prints true. AISIX rejects the call without sending it upstream.

Adapt the Setup for Your MCP Server​

Replace the test server URL with a Streamable HTTP endpoint reachable from the gateway. Keep type: mcp, and configure the upstream credential with auth_type and its related fields. See Upstream Authentication.

For an open-source AISIX gateway, validate the complete resources file and send SIGHUP when the running gateway already has every referenced environment variable. If you add or change an environment variable, recreate the container with the new value. See Reload a Resources File.

The control plane stores upstream credentials and projects the approved configuration to attached gateways. To let members submit servers without publishing them directly, use Review and Approve MCP Servers.

Pin the MCP Protocol Revision​

The gateway opens the upstream session with the MCP initialize handshake, which negotiates the protocol revision with the server. Keep that default for most servers, including servers that implement the stateless 2026-07-28 revision while remaining backward compatible.

Set protocol_version to 2026-07-28 only for a server that requires that revision, which replaces the handshake with an on-demand server/discover call. A pinned server never falls back: if the upstream does not support the pinned revision, the connection fails instead of quietly negotiating an older one. The setting applies to type: mcp servers only, since an openapi server has no upstream MCP session.

  1. Open MCP servers and select Edit on the server.
  2. Set MCP protocol version to 2026-07-28 (stateless).
  3. Select Save.

To return to negotiation, select the default handshake option and save again.

Upstream Message Size Limit​

A single message from an upstream MCP server can be at most 64 MiB. This limit applies to an application/json response body and to each SSE event, including one tools/call result or one tools/list page.

The gateway rejects a larger message instead of buffering it. A tools/call returns the JSON-RPC error upstream MCP server '<name>' failed to call tool; a failed tools/list omits that server's tools from the list. In both cases, the gateway log names the exceeded size limit.

The limit is fixed and applies only to type: mcp servers.

Clean Up​

Keep the server and caller grant if you plan to continue with the other MCP Gateway guides. Otherwise, remove the resources added through your management path.

  1. Open API keys, edit the caller key, and clear its MCP tool grant.
  2. Select Save changes.
  3. Open MCP servers, select Delete on everything, and confirm.

Remove the test server and temporary network:

docker rm -f aisix-mcp-everything
docker network disconnect aisix-mcp "$AISIX_GATEWAY_CONTAINER"
docker network rm aisix-mcp

Next Steps​

You have now registered an MCP server, granted one tool, and verified both allowed and denied tool calls. Use these guides to extend the setup: