版本：3.10.x

通过 API7-MCP 在 AI 客户端中管理 API7 企业版

本文介绍如何在本地运行 API7-MCP，将 API7 企业版连接到兼容 MCP 的 AI 客户端。完成配置后，AI 客户端可以通过自然语言提示词读取 API7 资源、查看监控数据、管理基于角色的访问控制（RBAC），并向网关发送测试流量。

API7-MCP 是一个模型上下文协议（Model Context Protocol，MCP）服务器，它将 API7 企业版 Admin API 和网关数据面能力作为工具提供给 AI 客户端。

这类工作流适用于以下场景：

不在控制台和 API 调用之间频繁切换，也能查看路由、服务、上游或消费者配置。
在 AI 客户端中查询请求量、健康检查等监控数据。
将 RBAC 查询或测试流量生成等运维任务交给兼容 MCP 的助手执行。

本文与将 REST API 暴露为 MCP 工具互为补充。后者说明如何通过 openapi-to-mcp 插件把业务 API 暴露给 AI Agent（AI 智能体），而本文说明如何让 AI 客户端通过 API7-MCP 使用 API7 企业版本身。

前置条件

开始之前，请确认你已经准备好：

一个可用的 API7 企业版实例，并且可以访问控制台，至少有一个网关实例。
已从控制台获取令牌。API7-MCP 会使用该令牌作为 X-API-KEY 请求头发起 Admin API 调用，因此 AI 客户端会继承令牌所有者的权限。请使用仅具备所需最低权限角色的令牌。
兼容 MCP 的 AI 客户端，例如 Cursor、Claude Desktop、GitHub Copilot 或 Cline。
在运行 AI 客户端的机器上安装 Node.js。MCP 服务器会作为 AI 客户端拉起的 Node.js 子进程运行。

可用操作

API7-MCP 暴露一组固定操作，你不需要在 AI 客户端配置中手动定义这些工具：

类别	操作
资源查询	`get_resource`，用于查询服务、路由、上游、消费者、凭证、证书、网关组等资源
网关流量	`send_request_to_gateway`，用于向网关发送一个或多个并发请求
监控	`get_prometheus_metrics`、`get_service_healthcheck`
风险检查	`check_risk`
角色	`get_role`、`create_role`、`delete_role`、`update_assigned_roles_for_user`、`get_role_by_user_id`
用户	`get_userId_by_username`
权限策略	`get_permission_policy`、`create_permission_policy`、`update_permission_policy`、`delete_permission_policy`、`attach_permission_policy_to_role`、`detach_permission_policy_from_role`、`get_permission_policy_by_role`

实际可用工具以运行中的 MCP 服务器通过 tools/list 返回的结果为准。api7-mcp README 可以作为参考，但运行时返回结果才是最终依据。

安装并配置 API7-MCP

API7-MCP 作为 AI 客户端的本地子进程运行。你只需要在客户端的 MCP 服务器配置文件中添加一次。不同客户端的配置文件位置和字段名称可能不同，请以对应客户端的 MCP 文档为准。

配置中需要使用以下三个环境变量：

变量	取值
`DASHBOARD_URL`	API7 企业版控制台地址，例如 `https://dashboard.example.com:7443`。
`GATEWAY_URL`	用于发送测试流量的 API7 网关实例地址，例如 `http://gateway.example.com:9080`。
`TOKEN`	前置条件中准备的控制台访问令牌。

你可以从 npm 安装 API7-MCP，也可以从源码构建。两种方式运行的是同一个 MCP 服务器。大多数情况下，直接使用 npm 更简单。

通过 npm 安装

{
  "mcpServers": {
    "api7-mcp": {
      "command": "npx",
      "args": ["-y", "api7-mcp"],
      "env": {
        "DASHBOARD_URL": "https://dashboard.example.com:7443",
        "GATEWAY_URL": "http://gateway.example.com:9080",
        "TOKEN": "your-api7-enterprise-token"
      }
    }
  }
}

通过源码安装

克隆仓库并构建项目：

git clone https://github.com/api7/api7-mcp.git
cd api7-mcp
pnpm install
pnpm build

构建完成后会生成 dist/index.js。在 AI 客户端中配置 node 启动该文件：

{
  "mcpServers": {
    "api7-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/api7-mcp/dist/index.js"],
      "env": {
        "DASHBOARD_URL": "https://dashboard.example.com:7443",
        "GATEWAY_URL": "http://gateway.example.com:9080",
        "TOKEN": "your-api7-enterprise-token"
      }
    }
  }
}

请使用 dist/index.js 的绝对路径。相对路径会从 AI 客户端的工作目录解析，而不同客户端的工作目录可能不同。

保存配置后，重启 AI 客户端或重新加载 MCP 服务器列表。客户端应显示 api7-mcp 已连接，并将可用操作展示为工具。

验证

以下检查用于确认 API7-MCP 既能读取控制台数据，也能通过网关发送流量。请在 AI 客户端的对话中执行。

发送测试流量

在 AI 客户端中输入：

向 API7 网关发送 5 个请求。

客户端会调用 send_request_to_gateway，并通常要求你确认是否允许执行该工具。确认后，客户端会返回请求发送结果。

查看监控数据

继续让 AI 客户端查询最近的请求量：

查看 API7 企业版过去 10 分钟的 API 请求数。

客户端会调用 get_prometheus_metrics，返回请求数和状态码分布。你可以在 API7 企业版控制台的 Monitoring 页面交叉验证结果：

API7 企业版 Monitoring 页面显示最近请求数

两边数据通常应基本一致。几个百分点以内的差异属于正常现象，常见原因包括查询时间窗口不完全一致、Prometheus 抓取间隔（通常为 15 秒）以及指标传播延迟。

安全使用建议

API7-MCP 会通过配置的令牌让 AI 客户端获得真实的 API7 企业版写入权限。建议遵循以下原则：

控制令牌权限。 为 API7-MCP 创建专用控制台令牌，并为其分配一个仅包含当前工作流所需权限的角色。避免使用管理员令牌。
保留工具调用确认。 对 create_permission_policy、delete_role、update_assigned_roles_for_user 等写操作，建议保留 AI 客户端的逐次确认机制。
优先在非生产环境验证。 在探索提示词和自动化流程时，先将 DASHBOARD_URL 与 GATEWAY_URL 指向测试或预发环境。
审计调用行为。 如果你的部署启用了控制台审计日志，通过 API7-MCP 发起的调用会和其他 Admin API 客户端一样记录在令牌持有者名下。

故障排查

如果 API7-MCP 运行不符合预期，可以按以下方向排查：

如果 AI 客户端无法连接 api7-mcp，检查客户端 MCP 日志，并确认命令、文件路径和 Node.js 安装是否正确。
如果操作返回认证或授权错误，确认 TOKEN 有效，并且对应角色拥有所需权限。
如果 get_prometheus_metrics 没有返回数据，确认 AI 客户端所在机器可以访问控制台，并且 Prometheus 抓取已经配置完成。最近请求可能需要等待一个抓取周期后才会出现。

下一步

将 REST API 暴露为 MCP 工具：反向场景，使用 openapi-to-mcp 插件把业务 REST API 暴露给 AI Agent。
api7-mcp GitHub 仓库：查看源码、操作说明和对话示例。

前置条件​

可用操作​

安装并配置 API7-MCP​

通过 npm 安装​

通过源码安装​

验证​

发送测试流量​

查看监控数据​

安全使用建议​

故障排查​

下一步​