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

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

API7-MCP 是一个模型上下文协议（Model Context Protocol，MCP）服务器，它把 API7 企业版管理操作和网关测试请求暴露为 AI 客户端可调用的工具。

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

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

本文与[将 REST API 暴露为 AI Agent 的 MCP 工具](https://docs.apiseven.com/api7-gateway/ai-gateway/use-cases/expose-apis-as-mcp-tools.md)互为补充。后者说明如何将 API 暴露为 MCP 工具，而本文说明如何让兼容 MCP 的 AI 客户端使用 API7 企业版本身。

## 前置条件[​](#前置条件 "前置条件的直接链接")

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

* 一个可用的 API7 企业版实例，并且可以访问控制台，至少有一个网关实例。
* [从控制台获取 Token](https://docs.apiseven.com/api7-gateway/reference/obtain-dashboard-token.md)。API7-MCP 使用该 Token 调用控制台 API，这些调用会以 Token 持有者的权限运行。请使用专用 Token，并为其分配满足需求的最小权限角色。API7-MCP 也会将该 Token 作为 `X-API-KEY` 请求头附加到网关测试请求，详情请参阅下方注意事项。
* 兼容 MCP 的 AI 客户端，例如 Cursor、Claude Desktop、GitHub Copilot 或 Cline。
* 在运行 AI 客户端的机器上安装 Node.js。MCP 服务器会作为 AI 客户端拉起的 Node.js 子进程运行。

## 可用 MCP 工具[​](#可用-mcp-工具 "可用 MCP 工具的直接链接")

API7-MCP 将 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 服务器响应 MCP `tools/list` 请求时发布的结果为准。[api7-mcp README](https://github.com/api7/api7-mcp#supported-operations) 提供了概览。

## 安装并配置 API7-MCP[​](#安装并配置-api7-mcp "安装并配置 API7-MCP的直接链接")

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

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

| 变量            | 取值                                                                           |
| --------------- | ------------------------------------------------------------------------------ |
| `DASHBOARD_URL` | API7 企业版控制台地址，例如 `https://dashboard.example.com:7443`。             |
| `GATEWAY_URL`   | 用于发送测试流量的 API7 网关实例地址，例如 `http://gateway.example.com:9080`。 |
| `TOKEN`         | 用于控制台 API 调用和网关测试请求的控制台 Token。                              |

警告

API7-MCP 当前使用共享 HTTP 客户端向 `DASHBOARD_URL` 和 `GATEWAY_URL` 发起 HTTPS 请求，并且会禁用 TLS 证书验证。默认情况下，该客户端还会将 `TOKEN` 作为 `X-API-KEY` 附加到网关测试请求中，因此网关可能会将该请求头转发给所选路由的上游。仅使用可信的端点和网络，仔细核对两个配置地址，并且不要测试不应接收控制台 Token 的上游路由。

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

### 通过 npm 安装[​](#通过-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 企业版控制台的 **监控** 页面交叉验证结果：

![API7 企业版 Monitoring 页面显示最近请求数](https://static.api7.ai/uploads/2025/05/06/0YyAypyY_verified-api-requests.webp)

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

## 安全使用建议[​](#安全使用建议 "安全使用建议的直接链接")

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

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

## 故障排查[​](#故障排查 "故障排查的直接链接")

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

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

## 后续步骤[​](#后续步骤 "后续步骤的直接链接")

* [将 REST API 暴露为 AI Agent 的 MCP 工具](https://docs.apiseven.com/api7-gateway/ai-gateway/use-cases/expose-apis-as-mcp-tools.md)：反向场景，使用 `openapi-to-mcp` 插件把业务 REST API 暴露给 AI Agent。
* [api7-mcp GitHub 仓库](https://github.com/api7/api7-mcp)：查看源码、工具参考和对话示例。
