版本：1.2.0

设置 MCP 网关

AISIX MCP 网关把已注册的 MCP 服务器置于统一的 /mcp 端点后，并控制每个调用方可以使用的工具。这样，应用无需直接连接各个上游服务器，即可通过 AISIX 访问获准使用的工具。

本指南将注册一个上游 MCP 服务器，把其中一个工具授予一把调用方 API Key，并验证该调用方只能使用这个工具。AISIX Cloud 与开源 AISIX 网关通过不同的管理路径配置相同的运行时行为。

前置条件

开始前，请准备以下环境：

对于 AISIX Cloud，完成 AISIX Cloud 快速入门，并保持其 Shell 和 aisix-dp 网关运行。
对于开源 AISIX 网关，完成开源 AISIX 网关快速入门，并停留在其 Shell 和工作目录中，同时保持 aisix-quickstart 网关运行。
Docker、cURL 和 jq。

启动 MCP 测试服务器

此示例在 Docker 中运行 MCP 官方的 Everything 测试服务器。该服务器与你现有的网关会加入一个临时 Docker 网络，因此网关无需重启即可访问服务器。Everything 服务器只能用于本地测试：它没有身份认证，并包含一个可返回其进程环境的诊断工具。此处使用的容器不会接收任何机密信息。完成本指南后，请停止并移除该容器。

根据你的配置路径设置网关容器名称。

对于 AISIX Cloud：

export AISIX_GATEWAY_CONTAINER="aisix-dp"

对于开源 AISIX 网关：

export AISIX_GATEWAY_CONTAINER="aisix-quickstart"

创建临时网络，并把正在运行的网关连接到该网络：

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

在同一网络上启动 Everything 服务器：

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

等待服务器就绪：

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"

最后一条命令会打印一行日志，确认端口 3001 已就绪。从网关容器中可通过 http://aisix-mcp-everything:3001/mcp 访问 MCP 端点。

注册服务器并授权工具

通过与你的部署对应的管理路径注册服务器。两种路径都把服务器命名为 everything，并且只把它的 echo 工具授予现有的快速入门调用方。

AISIX Cloud

注册测试服务器，并允许快速入门环境使用它：

MCP_SERVER_RESPONSE=$(curl -fsS -X POST "$AISIX_CP/mcp_servers" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
{
  "name": "everything",
  "type": "mcp",
  "url": "http://aisix-mcp-everything:3001/mcp",
  "auth_type": "none",
  "allowed_environments": ["${ENV_ID}"]
}
EOF
)

export MCP_SERVER_ID=$(echo "$MCP_SERVER_RESPONSE" | jq -er '.mcp_server.id')
echo "$MCP_SERVER_RESPONSE" | jq

❶ name 会成为工具的命名空间。

❷ allowed_environments 控制哪些环境接收这一组织级资源。

快速入门创建的写入作用域管理员 Token 会立即批准该服务器。随后，控制面会自动把服务器投射到已连接的网关。

把 everything__echo 工具授予快速入门创建的调用方 API Key：

curl -fsS -X PATCH \
  "$AISIX_CP/environments/$ENV_ID/api_keys/$API_KEY_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mcp_access":{"allow":["everything__echo"]}}' | jq

export AISIX_MCP_KEY="$AISIX_API_KEY"

该部分更新会保留 API Key 现有的模型访问权限。AISIX_MCP_KEY 使用快速入门返回的调用方明文 Key。

开源 AISIX 网关

在现有 resources.yaml 中，为快速入门调用方添加 mcp_access，并添加 mcp_servers 集合。保留现有的模型服务提供方 Key 和模型条目不变：

resources.yaml（调用方与 MCP 服务器）
api_keys:
  - display_name: quickstart-caller
    key_env: CALLER_API_KEY
    allowed_models:
      - gpt-4o-mini
    mcp_access:
      allow:
        - everything__echo

mcp_servers:
  - name: everything
    type: mcp
    url: http://aisix-mcp-everything:3001/mcp
    auth_type: none

❶ mcp_access.allow 仅向快速入门调用方授予带命名空间的 echo 工具。

❷ 服务器 name 会成为工具命名空间，因此上游 echo 工具会以 everything__echo 公开。

在正在运行的网关容器内验证完整文件，然后在不重启容器的情况下重新加载：

docker exec aisix-quickstart \
  aisix validate --resources /etc/aisix/resources.yaml

docker kill --signal HUP aisix-quickstart

export AISIX_MCP_KEY="$CALLER_API_KEY"

如果更新后的文件无效，网关会继续使用最后一次有效的配置。请通过 docker logs aisix-quickstart 查看被拒绝的加载。

使用 HTTP 验证 MCP 工具访问

接入编辑器之前，先执行协议级检查，单独验证网关配置、调用方授权和上游服务器。两种管理路径使用相同的命令，使用现有的 AISIX_PROXY 值和保存在 AISIX_MCP_KEY 中的调用方凭证。

MCP 客户端会自动完成初始化交换。直接发送初始化请求以验证端点：

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'

成功的响应包含服务器的 tools 能力。完成初始化交换：

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

该通知会返回 HTTP 202，且没有响应正文。

AISIX Cloud 控制面可能需要几秒钟才能把配置投射到网关。轮询工具列表最多 90 秒，然后验证只有被允许的工具可见：

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"]'

最后一条命令会打印 true。调用允许的工具：

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")'

该命令会打印匹配的工具结果内容块。为了验证工具授权列表已执行，尝试调用同一上游服务器中的另一个工具：

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

该命令会打印 true。AISIX 会拒绝此调用，而不会把它发送到上游。

为你的 MCP 服务器调整配置

把测试服务器 URL 替换为网关可访问的 Streamable HTTP 端点。保留 type: mcp，并通过 auth_type 及其相关字段配置上游凭证。请参阅上游身份认证。

对于开源 AISIX 网关，请验证完整的资源文件；当正在运行的网关已具有所有被引用的环境变量时，发送 SIGHUP。如果添加或更改了环境变量，请使用新值重新创建容器。请参阅重新加载资源文件。

AISIX Cloud 把上游凭证存储在控制面中，并把已批准的配置投射到已连接的网关。若要允许成员提交服务器而不直接发布，请使用审查并批准 MCP 服务器。

固定 MCP 协议修订版

网关默认使用 MCP initialize 握手打开上游会话，并在握手中与服务器协商协议修订版。对绝大多数服务器都应保持该默认值，包括那些实现了无状态 2026-07-28 修订版但仍保持向后兼容的服务器。

只有当服务器要求 2026-07-28 修订版时，才把 protocol_version 设置为 2026-07-28——该修订版以按需的 server/discover 调用取代握手。被固定的服务器不会回退：如果上游不支持所固定的修订版，连接会直接失败，而不会悄悄协商到更旧的修订版。该设置仅适用于 type: mcp 的服务器，因为 openapi 服务器没有上游 MCP 会话。

对于 AISIX Cloud，为已注册的服务器固定修订版：

curl -fsS -X PATCH "$AISIX_CP/mcp_servers/$MCP_SERVER_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"protocol_version":"2026-07-28"}' | jq

发送 "protocol_version": null 可移除该设置，让服务器回到握手方式。

对于开源 AISIX 网关，在服务器条目中添加该字段并重新加载：

resources.yaml（MCP 协议版本）
mcp_servers:
  - name: everything
    type: mcp
    url: http://aisix-mcp-everything:3001/mcp
    auth_type: none
    protocol_version: "2026-07-28"

清理

如果计划继续学习其他 MCP 网关指南，请保留服务器和调用方授权；否则，请通过对应的管理路径移除所添加的资源。

对于 AISIX Cloud，清空调用方的工具授权并删除服务器：

curl -fsS -X PATCH \
  "$AISIX_CP/environments/$ENV_ID/api_keys/$API_KEY_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mcp_access":{"allow":[]}}' | jq

curl -fsS -X DELETE "$AISIX_CP/mcp_servers/$MCP_SERVER_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN"

对于开源 AISIX 网关，从 resources.yaml 中移除新增的 mcp_access 和 mcp_servers，验证文件并再次发送 SIGHUP。

移除测试服务器和临时网络：

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

后续步骤

你现在已注册 MCP 服务器、授权一个工具，并验证了允许和拒绝的工具调用。使用以下指南继续扩展配置：

将 Cursor 连接到 MCP 网关：配置 Cursor 并验证一次完整工具调用。
将 VS Code 连接到 MCP 网关：配置 VS Code 并验证一次完整工具调用。
把 REST API 公开为 MCP 工具：从 OpenAPI 文档生成工具。
配置上游身份认证：使用 Bearer Token、API Key 或 OAuth 客户端凭证。
控制工具访问：授权确切工具名称、某个服务器的所有工具或全部已注册工具。
应用限流和预算：使用调用方和服务器限额治理 MCP 工具调用。
配置安全护栏：检查工具参数和结果。

前置条件​

启动 MCP 测试服务器​

注册服务器并授权工具​

AISIX Cloud​

开源 AISIX 网关​

使用 HTTP 验证 MCP 工具访问​

为你的 MCP 服务器调整配置​

固定 MCP 协议修订版​

清理​

后续步骤​