设置 MCP 网关

本指南将注册一个上游 MCP 服务器，并把其中一个工具授予一把调用方 API Key。随后，你将验证该调用方通过 /mcp 只能使用已授权的工具。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 '{"allowed_tools":["everything__echo"]}' | jq

export AISIX_MCP_KEY="$AISIX_API_KEY"

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

开源 AISIX 网关

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

resources.yaml
api_keys:
  - display_name: quickstart-caller
    key_env: CALLER_API_KEY
    allowed_models:
      - gpt-4o-mini
    allowed_tools:
      - everything__echo

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

❶ allowed_tools 仅向快速入门调用方授予带命名空间的 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 查看被拒绝的加载。

验证 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 "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 "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 "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 "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 网关指南，请保留服务器和调用方授权；否则，请通过对应的管理路径移除所添加的资源。

对于 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 '{"allowed_tools":[]}' | jq

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

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

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

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

后续步骤

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

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

前置条件​

启动 MCP 测试服务器​

注册服务器并授权工具​

AISIX Cloud​

开源 AISIX 网关​

验证 MCP 工具访问​

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

清理​

后续步骤​