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
按网关的部署方式启动测试服务:
- Docker
- Kubernetes
将 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 文件,使其接入共享网络:
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
此镜像适用于 linux/amd64。请在与网关相同的命名空间中创建 Petstore。清单和命令使用 Ingress Controller 示例的 aic 命名空间。如果网关部署在其他命名空间,请将所有 aic 替换为实际命名空间。API7 网关通常使用 api7。
apiVersion: apps/v1
kind: Deployment
metadata:
namespace: aic
name: petstore
spec:
replicas: 1
selector:
matchLabels:
app: petstore
template:
metadata:
labels:
app: petstore
spec:
nodeSelector:
kubernetes.io/arch: amd64
containers:
- name: petstore
image: swaggerapi/petstore3:1.0.27@sha256:749432676c31cd05256f0d9e878302164debb94daa1c1223e193747e1b34e7d1
ports:
- containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
namespace: aic
name: petstore
spec:
selector:
app: petstore
ports:
- port: 8080
targetPort: 8080
应用清单:
kubectl apply -f petstore.yaml
等待 Petstore 就绪:
kubectl rollout status -n aic deployment/petstore
使用白名单限制工具访问
以下示例演示如何配置白名单,使消费者只能调用指定的 MCP 工具。
- Admin API
- ADC
- Ingress Controller
创建消费者 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 响应,表明工具调用已被拒绝。
创建一个配置了 key-auth 凭证和 mcp-tools-acl 的消费者,并创建一条启用了 openapi-to-mcp 和 key-auth 的路由:
consumers:
- username: alice
labels:
docs-example: mcp-tools-acl
credentials:
- name: cred-alice-key-auth
type: key-auth
config:
key: alice-key
plugins:
mcp-tools-acl:
rules:
- allow_tools:
- getPetById
- getUserByName
services:
- name: mcp-tools-acl-service
labels:
docs-example: mcp-tools-acl
upstream:
type: roundrobin
scheme: http
pass_host: node
nodes:
- host: petstore
port: 8080
weight: 1
routes:
- name: mcp-tools-acl-route
uris:
- /mcp
methods:
- POST
plugins:
key-auth:
header: apikey
openapi-to-mcp:
transport: streamable_http
base_url: http://petstore:8080/api/v3
headers:
Authorization: special-key
openapi_url: http://petstore:8080/api/v3/openapi.json
❶ 仅允许消费者 alice 调用 getPetById 和 getUserByName。其他工具均无法调用,也不会出现在工具列表中。
ADC 会让选定类型的资源与声明的目标状态保持一致。预览本示例涉及的变更,并确认差异中没有意外更新或删除:
adc diff -f adc.yaml \
--include-resource-type service \
--include-resource-type consumer \
--label-selector docs-example=mcp-tools-acl
同步已核对的服务与消费者配置,包括消费者下的凭证:
adc sync -f adc.yaml \
--include-resource-type service \
--include-resource-type consumer \
--label-selector docs-example=mcp-tools-acl
- Gateway API
- APISIX CRD
按以下方式创建消费者和路由,并配置 openapi-to-mcp、key-auth 和 mcp-tools-acl:
apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
namespace: aic
name: alice
spec:
gatewayRef:
name: apisix
credentials:
- type: key-auth
name: cred-alice-key-auth
config:
key: alice-key
plugins:
- name: mcp-tools-acl
config:
rules:
- allow_tools:
- getPetById
- getUserByName
---
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
namespace: aic
name: mcp-tools-acl-plugin-config
spec:
plugins:
- name: key-auth
config:
header: apikey
- name: openapi-to-mcp
config:
transport: streamable_http
base_url: http://petstore:8080/api/v3
headers:
Authorization: special-key
openapi_url: http://petstore:8080/api/v3/openapi.json
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
namespace: aic
name: mcp-tools-acl-route
spec:
parentRefs:
- name: apisix
rules:
- matches:
- path:
type: Exact
value: /mcp
method: POST
filters:
- type: ExtensionRef
extensionRef:
group: apisix.apache.org
kind: PluginConfig
name: mcp-tools-acl-plugin-config
backendRefs:
- name: petstore-external-domain
port: 8080
---
apiVersion: v1
kind: Service
metadata:
namespace: aic
name: petstore-external-domain
spec:
type: ExternalName
externalName: petstore.aic.svc.cluster.local
ports:
- port: 8080
---
apiVersion: apisix.apache.org/v1alpha1
kind: BackendTrafficPolicy
metadata:
namespace: aic
name: petstore-external-domain
spec:
targetRefs:
- group: ""
kind: Service
name: petstore-external-domain
passHost: node
scheme: http
❶ 仅允许消费者 alice 调用 getPetById 和 getUserByName。
按以下方式创建消费者和路由,并配置 openapi-to-mcp、key-auth 和 mcp-tools-acl:
apiVersion: apisix.apache.org/v2
kind: ApisixConsumer
metadata:
namespace: aic
name: alice
spec:
ingressClassName: apisix
authParameter:
keyAuth:
value:
key: alice-key
---
apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
namespace: aic
name: petstore-external-domain
spec:
ingressClassName: apisix
scheme: http
passHost: node
externalNodes:
- type: Domain
name: petstore.aic.svc.cluster.local
port: 8080
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
namespace: aic
name: mcp-tools-acl-route
spec:
ingressClassName: apisix
http:
- name: mcp-tools-acl-route
match:
paths:
- /mcp
methods:
- POST
upstreams:
- name: petstore-external-domain
plugins:
- name: key-auth
enable: true
config:
header: apikey
- name: openapi-to-mcp
enable: true
config:
transport: streamable_http
base_url: http://petstore:8080/api/v3
headers:
Authorization: special-key
openapi_url: http://petstore:8080/api/v3/openapi.json
- name: mcp-tools-acl
enable: true
config:
rules:
- allow_tools:
- getPetById
- getUserByName
❶ 在此路由上仅允许调用 getPetById 和 getUserByName。
将配置应用到集群:
kubectl apply -f mcp-tools-acl-ic.yaml
使用黑名单限 制工具访问
以下示例演示如何禁用指定工具,同时保留对其他工具的访问权限。
- Admin API
- ADC
- Ingress Controller
在上一示例的基础上,创建带有黑名单的消费者 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 响应。
更新 adc.yaml 中的消费者配置,以更改 ACL 规则:
consumers:
- username: bob
labels:
docs-example: mcp-tools-acl
credentials:
- name: cred-bob-key-auth
type: key-auth
config:
key: bob-key
plugins:
mcp-tools-acl:
rules:
- deny_tools:
- deletePet
services:
- name: mcp-tools-acl-service
labels:
docs-example: mcp-tools-acl
upstream:
type: roundrobin
scheme: http
pass_host: node
nodes:
- host: petstore
port: 8080
weight: 1
routes:
- name: mcp-tools-acl-route
uris:
- /mcp
methods:
- POST
plugins:
key-auth:
header: apikey
openapi-to-mcp:
transport: streamable_http
base_url: http://petstore:8080/api/v3
headers:
Authorization: special-key
openapi_url: http://petstore:8080/api/v3/openapi.json
❶ 禁止消费者 bob 调用 deletePet,其他工具仍可访问。
ADC 会让选定类型的资源与声明的目标状态保持一致。预览本示例涉及的变更,并确认差异中没有意外更新或删除:
adc diff -f adc.yaml \
--include-resource-type service \
--include-resource-type consumer \
--label-selector docs-example=mcp-tools-acl
同步已核对的服务与消费者配置,包括消费者下的凭证:
adc sync -f adc.yaml \
--include-resource-type service \
--include-resource-type consumer \
--label-selector docs-example=mcp-tools-acl
- Gateway API
- APISIX CRD
更新消费者或路由配置中的 ACL 规则:
# Other Configs
# ---
apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
namespace: aic
name: bob
spec:
gatewayRef:
name: apisix
credentials:
- type: key-auth
name: cred-bob-key-auth
config:
key: bob-key
plugins:
- name: mcp-tools-acl
config:
rules:
- deny_tools:
- deletePet
❶ 禁止消费者 bob 调用 deletePet。
更新消费者或路由配置中的 ACL 规则:
# Other Configs
# ---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
namespace: aic
name: mcp-tools-acl-route
spec:
ingressClassName: apisix
http:
- name: mcp-tools-acl-route
match:
paths:
- /mcp
methods:
- POST
upstreams:
- name: petstore-external-domain
plugins:
- name: key-auth
enable: true
config:
header: apikey
- name: openapi-to-mcp
enable: true
config:
transport: streamable_http
base_url: http://petstore:8080/api/v3
headers:
Authorization: special-key
openapi_url: http://petstore:8080/api/v3/openapi.json
- name: mcp-tools-acl
enable: true
config:
rules:
- deny_tools:
- deletePet
❶ 禁止调用 deletePet,同时允许访问此路由上的其他工具。
将配置应用到集群:
kubectl apply -f mcp-tools-acl-ic.yaml
基于路由条件应用不同规则
以下示例演示如何使用表达式条件(expr),根据所访问的路由等请求上下文应用不同的 ACL 规则。
- Admin API
- ADC
- Ingress Controller
创建带有条件规则的消费者 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,导致没有任何规则匹配,插件便不会限制访问,所有工具均可调用。
创建一个带有条件规则的消费者,以及两条路由:
consumers:
- username: grace
labels:
docs-example: mcp-tools-acl
credentials:
- name: cred-grace-key-auth
type: key-auth
config:
key: grace-key
plugins:
mcp-tools-acl:
rules:
- expr:
-
- route_name
- ==
- pets-route
allow_tools:
- getPetById
- allow_tools:
- getUserByName
services:
- name: pets-mcp-service
labels:
docs-example: mcp-tools-acl
upstream:
type: roundrobin
scheme: http
pass_host: node
nodes:
- host: petstore
port: 8080
weight: 1
routes:
- name: pets-route
uris:
- /mcp
methods:
- POST
plugins:
key-auth:
header: apikey
openapi-to-mcp:
transport: streamable_http
base_url: http://petstore:8080/api/v3
headers:
Authorization: special-key
openapi_url: http://petstore:8080/api/v3/openapi.json
- name: inventory-mcp-service
labels:
docs-example: mcp-tools-acl
upstream:
type: roundrobin
scheme: http
pass_host: node
nodes:
- host: petstore
port: 8080
weight: 1
routes:
- name: inventory-route
uris:
- /mcp2
methods:
- POST
plugins:
key-auth:
header: apikey
openapi-to-mcp:
transport: streamable_http
base_url: http://petstore:8080/api/v3
headers:
Authorization: special-key
openapi_url: http://petstore:8080/api/v3/openapi.json
❶ 请求命中 pets-route 时,仅允许调用 getPetById。
❷ 对其他所有路由应用兜底规则,仅允许调用 getUserByName。
ADC 会让选定类型的资源与声明的目标状态保持一致。预览本示例涉及的变更,并确认差异中没有意外更新或删除:
adc diff -f adc.yaml \
--include-resource-type service \
--include-resource-type consumer \
--label-selector docs-example=mcp-tools-acl
同步已核对的服务与消费者配置,包括消费者下的凭证:
adc sync -f adc.yaml \
--include-resource-type service \
--include-resource-type consumer \
--label-selector docs-example=mcp-tools-acl
- Gateway API
- APISIX CRD
为不同的 MCP 路由配置条件规则:
apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
namespace: aic
name: grace
spec:
gatewayRef:
name: apisix
credentials:
- type: key-auth
name: cred-grace-key-auth
config:
key: grace-key
plugins:
- name: mcp-tools-acl
config:
rules:
- expr:
-
- route_name
- ==
- pets-route
allow_tools:
- getPetById
- allow_tools:
- getUserByName
---
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
namespace: aic
name: mcp-tools-acl-plugin-config
spec:
plugins:
- name: key-auth
config:
header: apikey
- name: openapi-to-mcp
config:
transport: streamable_http
base_url: http://petstore:8080/api/v3
headers:
Authorization: special-key
openapi_url: http://petstore:8080/api/v3/openapi.json
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
namespace: aic
name: pets-route
spec:
parentRefs:
- name: apisix
rules:
- matches:
- path:
type: Exact
value: /mcp
method: POST
filters:
- type: ExtensionRef
extensionRef:
group: apisix.apache.org
kind: PluginConfig
name: mcp-tools-acl-plugin-config
backendRefs:
- name: petstore-external-domain
port: 8080
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
namespace: aic
name: inventory-route
spec:
parentRefs:
- name: apisix
rules:
- matches:
- path:
type: Exact
value: /mcp2
method: POST
filters:
- type: ExtensionRef
extensionRef:
group: apisix.apache.org
kind: PluginConfig
name: mcp-tools-acl-plugin-config
backendRefs:
- name: petstore-external-domain
port: 8080
---
apiVersion: v1
kind: Service
metadata:
namespace: aic
name: petstore-external-domain
spec:
type: ExternalName
externalName: petstore.aic.svc.cluster.local
ports:
- port: 8080
---
apiVersion: apisix.apache.org/v1alpha1
kind: BackendTrafficPolicy
metadata:
namespace: aic
name: petstore-external-domain
spec:
targetRefs:
- group: ""
kind: Service
name: petstore-external-domain
passHost: node
scheme: http
❶ 仅当请求命中 pets-route 时,应用允许调用 getPetById 的规则。
❷ 对其他所有匹配的路由应用允许调用 getUserByName 的规则。
为不同的 MCP 路由配置条件规则:
apiVersion: apisix.apache.org/v2
kind: ApisixConsumer
metadata:
namespace: aic
name: grace
spec:
ingressClassName: apisix
authParameter:
keyAuth:
value:
key: grace-key
---
apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
namespace: aic
name: petstore-external-domain
spec:
ingressClassName: apisix
scheme: http
passHost: node
externalNodes:
- type: Domain
name: petstore.aic.svc.cluster.local
port: 8080
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
namespace: aic
name: mcp-tools-acl-routes
spec:
ingressClassName: apisix
http:
- name: pets-route
match:
paths:
- /mcp
methods:
- POST
upstreams:
- name: petstore-external-domain
plugins:
- name: key-auth
enable: true
config:
header: apikey
- name: openapi-to-mcp
enable: true
config:
transport: streamable_http
base_url: http://petstore:8080/api/v3
headers:
Authorization: special-key
openapi_url: http://petstore:8080/api/v3/openapi.json
- name: mcp-tools-acl
enable: true
config:
rules:
- expr:
-
- uri
- ==
- /mcp
allow_tools:
- getPetById
- allow_tools:
- getUserByName
- name: inventory-route
match:
paths:
- /mcp2
methods:
- POST
upstreams:
- name: petstore-external-domain
plugins:
- name: key-auth
enable: true
config:
header: apikey
- name: openapi-to-mcp
enable: true
config:
transport: streamable_http
base_url: http://petstore:8080/api/v3
headers:
Authorization: special-key
openapi_url: http://petstore:8080/api/v3/openapi.json
- name: mcp-tools-acl
enable: true
config:
rules:
- expr:
-
- uri
- ==
- /mcp
allow_tools:
- getPetById
- allow_tools:
- getUserByName
❶ 仅当请求 URI 为 /mcp 时,应用允许调用 getPetById 的规则。
❷ 通过兜底规则,使 /mcp2 路由仅允许调用 getUserByName。
将配置应用到集群:
kubectl apply -f mcp-tools-acl-ic.yaml
故障排除
插件未生效
确认同一路由上已启用 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 数组非空。