跳到主要内容

mcp-tools-acl

mcp-tools-acl 插件控制每个消费者在启用了 openapi-to-mcp 的路由上可以调用或发现哪些 MCP 工具。插件提供两种限制方式:

  • 拦截 tools/call 时,插件拒绝调用受限工具并返回 HTTP 错误响应。
  • 过滤 tools/list 时,插件从返回给客户端的列表中移除受限工具,使 MCP 客户端无法看到这些工具。此过滤适用于 JSON 和服务器发送事件(SSE)响应。

每条规则指定白名单或黑名单,还可以指定表达式条件。插件按顺序评估规则,应用第一条匹配的规则并跳过其余规则。

此插件在 API7 企业版 3.9.8 和 3.10.0 中引入。

示例​

每个示例都在同一路由上启用 openapi-to-mcp 和 key-auth。如果请求没有通过身份认证的消费者,mcp-tools-acl 会原样放行所有流量。

继续前,请完成准备 API7 网关,确保所需的 OpenAPI-to-MCP 服务可用。

在消费者上配置 mcp-tools-acl,可以按消费者控制访问。如果同时在消费者和路由上配置了插件,则以消费者上的配置为准。只有通过身份认证的消费者未配置 mcp-tools-acl 时,才应用路由配置。

使用 Admin API 标签页时,请设置 Dashboard 地址和网关组,然后输入 Dashboard Token:

export API7_ADMIN_URL="https://localhost:7443"
export API7_GATEWAY_GROUP_ID="default"
printf "Dashboard token: "
read -rs API7_ADMIN_KEY && export API7_ADMIN_KEY && echo

示例中的 -k 允许客户端接受本地 Dashboard 的自签名证书。使用客户端信任的证书时,请移除此参数。

使用 ADC 标签页时,请选择 api7ee 后端,并配置相应的 Dashboard 地址、Token 和网关组。

示例使用官方 Swagger Petstore 镜像 1.0.27。该测试服务同时提供 OpenAPI 文档和 API。镜像清单摘要已固定,便于复现访问控制结果。

启动 Petstore​

按网关的部署方式启动测试服务:

将 GATEWAY_CONTAINER 设置为正在运行的 API7 网关容器名称,然后将网关和 Petstore 接入同一个专用网络。OpenAPI-to-MCP 服务必须按照准备 API7 网关中的说明,与网关共享网络命名空间。

export GATEWAY_CONTAINER=replace-with-gateway-container-name

docker network inspect gateway-petstore-net > /dev/null 2>&1 || \
docker network create gateway-petstore-net

if ! docker inspect "$GATEWAY_CONTAINER" \
--format '{{json .NetworkSettings.Networks}}' \
| grep -q '"gateway-petstore-net"'; then
docker network connect gateway-petstore-net "$GATEWAY_CONTAINER"
fi

为固定版本的 Petstore 创建 Compose 文件,使其接入共享网络:

docker-compose.petstore.yaml
services:
petstore:
image: swaggerapi/petstore3:1.0.27@sha256:749432676c31cd05256f0d9e878302164debb94daa1c1223e193747e1b34e7d1
platform: linux/amd64
networks:
- gateway-petstore-net
ports:
- "18080:8080"

networks:
gateway-petstore-net:
external: true

使用固定的 Compose 项目名称启动或更新 Petstore,以便在相关指南中重复执行命令:

docker compose -p api7-docs-petstore \
-f docker-compose.petstore.yaml up -d

容器启动后,确认可以访问 OpenAPI 文档:

curl -fsS "http://127.0.0.1:18080/api/v3/openapi.json" > /dev/null

使用白名单限制工具访问​

以下示例演示如何配置白名单,使消费者只能调用指定的 MCP 工具。

创建消费者 alice:

curl -k "${API7_ADMIN_URL}/apisix/admin/consumers/alice?gateway_group_id=${API7_GATEWAY_GROUP_ID}" -X PUT \
-H "X-API-KEY: ${API7_ADMIN_KEY}" \
-H "Content-Type: application/json" \
-d '{
"username": "alice"
}'

为 alice 创建 key-auth 凭证:

curl -k "${API7_ADMIN_URL}/apisix/admin/consumers/alice/credentials/cred-alice-key-auth?gateway_group_id=${API7_GATEWAY_GROUP_ID}" -X PUT \
-H "X-API-KEY: ${API7_ADMIN_KEY}" \
-H "Content-Type: application/json" \
-d '{
"name": "cred-alice-key-auth",
"plugins": {
"key-auth": {
"key": "alice-key"
}
}
}'

在消费者 alice 上配置 mcp-tools-acl 插件:

curl -k "${API7_ADMIN_URL}/apisix/admin/consumers/alice?gateway_group_id=${API7_GATEWAY_GROUP_ID}" -X PUT \
-H "X-API-KEY: ${API7_ADMIN_KEY}" \
-H "Content-Type: application/json" \
-d '{
"username": "alice",
"plugins": {
"mcp-tools-acl": {
"rules": [
{
"allow_tools": ["getPetById", "getUserByName"]
}
]
}
}
}'

❶ 仅允许消费者 alice 调用 getPetById 和 getUserByName。其他工具均无法调用,也不会出现在工具列表中。

创建一个以 Petstore API 为上游的服务:

curl -k "${API7_ADMIN_URL}/apisix/admin/services/mcp-tools-acl-service?gateway_group_id=${API7_GATEWAY_GROUP_ID}" -X PUT \
-H "X-API-KEY: ${API7_ADMIN_KEY}" \
-H "Content-Type: application/json" \
-d '{
"name": "mcp-tools-acl-service",
"upstream": {
"type": "roundrobin",
"scheme": "http",
"pass_host": "node",
"nodes": [
{
"host": "petstore",
"port": 8080,
"weight": 1
}
]
}
}'

在该服务中创建一条启用了 openapi-to-mcp 和 key-auth 的路由:

curl -k "${API7_ADMIN_URL}/apisix/admin/routes/mcp-tools-acl-route?gateway_group_id=${API7_GATEWAY_GROUP_ID}" -X PUT \
-H "X-API-KEY: ${API7_ADMIN_KEY}" \
-H "Content-Type: application/json" \
-d '{
"name": "mcp-tools-acl-route",
"service_id": "mcp-tools-acl-service",
"paths": ["/mcp"],
"methods": ["POST"],
"plugins": {
"openapi-to-mcp": {
"transport": "streamable_http",
"openapi_url": "http://petstore:8080/api/v3/openapi.json",
"base_url": "http://petstore:8080/api/v3",
"headers": {
"Authorization": "special-key"
}
},
"key-auth": {}
}
}'

以消费者 alice 的身份发送 tools/list 请求:

curl -s "http://127.0.0.1:9080/mcp" \
-H "apikey: alice-key" \
-H "Accept: application/json, text/event-stream" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list"
}'

响应中应只包含 getPetById 和 getUserByName,其他工具均已被过滤。

调用允许的工具:

curl -i "http://127.0.0.1:9080/mcp" \
-H "apikey: alice-key" \
-H "Accept: application/json, text/event-stream" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "getPetById",
"arguments": {
"pathParameters": {
"petId": 1
}
}
}
}'

你应收到 HTTP/1.1 200 OK 响应,其中包含 Petstore 的宠物数据。

调用未列入白名单的工具:

curl -i "http://127.0.0.1:9080/mcp" \
-H "apikey: alice-key" \
-H "Accept: application/json, text/event-stream" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "deletePet",
"arguments": {
"pathParameters": {
"petId": 1
}
}
}
}'

你应收到 HTTP/1.1 403 Forbidden 响应,表明工具调用已被拒绝。

使用黑名单限制工具访问​

以下示例演示如何禁用指定工具,同时保留对其他工具的访问权限。

在上一示例的基础上,创建带有黑名单的消费者 bob:

curl -k "${API7_ADMIN_URL}/apisix/admin/consumers/bob?gateway_group_id=${API7_GATEWAY_GROUP_ID}" -X PUT \
-H "X-API-KEY: ${API7_ADMIN_KEY}" \
-H "Content-Type: application/json" \
-d '{
"username": "bob",
"plugins": {
"mcp-tools-acl": {
"rules": [
{
"deny_tools": ["deletePet"]
}
]
}
}
}'

❶ 禁止消费者 bob 调用 deletePet,其他工具仍可访问。

为 bob 创建 key-auth 凭证:

curl -k "${API7_ADMIN_URL}/apisix/admin/consumers/bob/credentials/cred-bob-key-auth?gateway_group_id=${API7_GATEWAY_GROUP_ID}" -X PUT \
-H "X-API-KEY: ${API7_ADMIN_KEY}" \
-H "Content-Type: application/json" \
-d '{
"name": "cred-bob-key-auth",
"plugins": {
"key-auth": {
"key": "bob-key"
}
}
}'

以消费者 bob 的身份发送 tools/list 请求:

curl -s "http://127.0.0.1:9080/mcp" \
-H "apikey: bob-key" \
-H "Accept: application/json, text/event-stream" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list"
}'

工具列表应包含除 deletePet 外的所有工具。

调用被禁止的工具:

curl -i "http://127.0.0.1:9080/mcp" \
-H "apikey: bob-key" \
-H "Accept: application/json, text/event-stream" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "deletePet",
"arguments": {
"pathParameters": {
"petId": 1
}
}
}
}'

你应收到 HTTP/1.1 403 Forbidden 响应。

基于路由条件应用不同规则​

以下示例演示如何使用表达式条件(expr),根据所访问的路由等请求上下文应用不同的 ACL 规则。

创建带有条件规则的消费者 grace:

curl -k "${API7_ADMIN_URL}/apisix/admin/consumers/grace?gateway_group_id=${API7_GATEWAY_GROUP_ID}" -X PUT \
-H "X-API-KEY: ${API7_ADMIN_KEY}" \
-H "Content-Type: application/json" \
-d '{
"username": "grace",
"plugins": {
"mcp-tools-acl": {
"rules": [
{
"expr": [["route_id", "==", "route-pets"]],
"allow_tools": ["getPetById"]
},
{
"allow_tools": ["getUserByName"]
}
]
}
}
}'

❶ 规则 1:请求命中路由 route-pets 时,仅允许调用 getPetById。

❷ 规则 2 是未设置 expr 的兜底规则,在其他路由上仅允许调用 getUserByName。只有规则 1 不匹配时,才会应用此规则。

为 grace 创建 key-auth 凭证:

curl -k "${API7_ADMIN_URL}/apisix/admin/consumers/grace/credentials/cred-grace-key-auth?gateway_group_id=${API7_GATEWAY_GROUP_ID}" -X PUT \
-H "X-API-KEY: ${API7_ADMIN_KEY}" \
-H "Content-Type: application/json" \
-d '{
"name": "cred-grace-key-auth",
"plugins": {
"key-auth": {
"key": "grace-key"
}
}
}'

创建一个以 Petstore API 为上游的服务,或复用第一个示例中的服务:

curl -k "${API7_ADMIN_URL}/apisix/admin/services/mcp-tools-acl-service?gateway_group_id=${API7_GATEWAY_GROUP_ID}" -X PUT \
-H "X-API-KEY: ${API7_ADMIN_KEY}" \
-H "Content-Type: application/json" \
-d '{
"name": "mcp-tools-acl-service",
"upstream": {
"type": "roundrobin",
"scheme": "http",
"pass_host": "node",
"nodes": [
{
"host": "petstore",
"port": 8080,
"weight": 1
}
]
}
}'

下方的路由 route-pets 使用 /mcp 路径。如果在前面的示例中创建了 mcp-tools-acl-route,请先删除该示例路由,因为 Dashboard 会拒绝在同一服务中匹配相同路径的路由:

curl -k "${API7_ADMIN_URL}/apisix/admin/routes/mcp-tools-acl-route?gateway_group_id=${API7_GATEWAY_GROUP_ID}" -X DELETE \
-H "X-API-KEY: ${API7_ADMIN_KEY}"

在该服务中创建两条启用了 openapi-to-mcp 和 key-auth 的路由:

curl -k "${API7_ADMIN_URL}/apisix/admin/routes/route-pets?gateway_group_id=${API7_GATEWAY_GROUP_ID}" -X PUT \
-H "X-API-KEY: ${API7_ADMIN_KEY}" \
-H "Content-Type: application/json" \
-d '{
"name": "route-pets",
"service_id": "mcp-tools-acl-service",
"paths": ["/mcp"],
"methods": ["POST"],
"plugins": {
"openapi-to-mcp": {
"transport": "streamable_http",
"openapi_url": "http://petstore:8080/api/v3/openapi.json",
"base_url": "http://petstore:8080/api/v3",
"headers": { "Authorization": "special-key" }
},
"key-auth": {}
}
}'
curl -k "${API7_ADMIN_URL}/apisix/admin/routes/route-inventory?gateway_group_id=${API7_GATEWAY_GROUP_ID}" -X PUT \
-H "X-API-KEY: ${API7_ADMIN_KEY}" \
-H "Content-Type: application/json" \
-d '{
"name": "route-inventory",
"service_id": "mcp-tools-acl-service",
"paths": ["/mcp2"],
"methods": ["POST"],
"plugins": {
"openapi-to-mcp": {
"transport": "streamable_http",
"openapi_url": "http://petstore:8080/api/v3/openapi.json",
"base_url": "http://petstore:8080/api/v3",
"headers": { "Authorization": "special-key" }
},
"key-auth": {}
}
}'

当 grace 请求 route-pets 时,规则 1 匹配,仅允许调用 getPetById:

curl -i "http://127.0.0.1:9080/mcp" \
-H "apikey: grace-key" \
-H "Accept: application/json, text/event-stream" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "getPetById",
"arguments": {
"pathParameters": {
"petId": 1
}
}
}
}'

你应收到 HTTP/1.1 200 OK 响应,其中包含 Petstore 的宠物数据。

当 grace 请求 route-inventory 时,由于 route_id 不同,规则 1 不匹配。此时应用兜底规则 2,仅允许调用 getUserByName:

curl -i "http://127.0.0.1:9080/mcp2" \
-H "apikey: grace-key" \
-H "Accept: application/json, text/event-stream" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "getUserByName",
"arguments": {
"pathParameters": {
"username": "user1"
}
}
}
}'

你应收到 HTTP/1.1 200 OK 响应,其中包含 Petstore 的用户数据。

规则从上到下评估。第一条匹配的规则生效,后续规则均被跳过。请将带有 expr 的具体规则放在不带 expr 的兜底规则之前。

如果所有规则的 expr 均为 false,导致没有任何规则匹配,插件便不会限制访问,所有工具均可调用。

故障排除​

插件未生效

确认同一路由上已启用 openapi-to-mcp,并已配置身份认证插件。如果请求没有通过身份认证的消费者,mcp-tools-acl 会原样放行所有流量。

tools/call 返回 HTTP 400

请求体是有效的 JSON,但缺少 params,或者 params.name 不是字符串。插件返回 HTTP 400 和 {"message": "Invalid MCP tools/call request"}。这表示 MCP 客户端发出的请求格式不正确。工具被规则拒绝时,才使用 rejected_code。

allow_tools: [] 会禁止所有工具

空白名单符合 Schema 校验,会禁止所有工具。每个 tools/call 请求都会被拒绝,tools/list 会返回空列表。要允许消费者访问工具,请确保 allow_tools 数组非空。