MCP 接入

ApiGo 提供两套 MCP 能力：

入口	地址	鉴权	面向对象
应用 MCP	`/mcp/{appCode}`	`X-AppKey` 或 `Authorization: Bearer <token>`	外部 AI 客户端调用已发布接口
管理端 MCP	`/api/box/mcp/{agentCode}`	`X-Agent-Key`	AI 智能体管理平台资源与接口

两者都使用 JSON-RPC 2.0，协议版本为 MCP 2025-06-18，但工具来源、鉴权和权限模型不同。

应用 MCP

前置条件

一个接口要出现在应用 MCP 的工具列表中，必须同时满足：

接口的发布协议包含 MCP；
接口发布到 prod 环境并处于上线状态；
接口认证方式为 app_key；
调用凭证已获得该接口的访问权（接口级授权，或凭证为项目级作用域）；
凭证已启用 MCP，且未被禁用。

创建或编辑接口时，只有认证方式为 app_key 才能勾选 MCP 发布协议；切换为其他认证方式会自动取消 MCP。MCP 复用 REST 的 app_key 鉴权，不需要 X-Sign。

客户端配置

在 账户中心 → 应用凭证 → MCP 配置 中复制配置：

{
  "mcpServers": {
    "ApiGo-MCP": {
      "type": "http",
      "url": "https://www.apigo.cn/mcp/{appCode}",
      "headers": {
        "X-AppKey": "{AppKey}"
      }
    }
  }
}

若使用 OAuth2 客户端凭证，把 headers 中的 X-AppKey 换成 Authorization："Authorization": "Bearer <access_token>"。

私有化部署时把域名替换为实际网关地址。服务端只接受 POST：

GET 请求返回 HTTP 405，不支持独立 SSE 通道；
OPTIONS 预检请求放行；
客户端可通过 Accept: application/json 或 Accept: text/event-stream 指定响应形式；
请求体上限 1 MiB，响应体上限 4 MiB。

鉴权规则

网关优先从 Authorization: Bearer <access_token>（OAuth2 客户端凭证）解析应用，未携带时回落 X-AppKey，随后依次校验：

应用存在且已启用；
应用 mcpEnabled = 1；
路径中的 {appCode} 与应用的 AppCode 一致；
来源 IP 在应用的 IP 白名单内（配置了白名单时）。

使用 Bearer 时，token 由 /oauth2/token 以 client_credentials 换取，应用身份取自 token 内的 AppKey，因此无需再传 X-AppKey；Authorization 属于敏感头，网关消费后不会转发给目标接口。换取方式见 OAuth2 客户端凭证认证。

企业 IdP JWT 暂未开放

MCP 入口当前只识别平台 OAuth2 token 与 X-AppKey。企业 IdP 签发的 JWT 暂不能用于 /mcp/{appCode}，二期将按 token 的 iss 分发并支持 RFC 9728 / RFC 8707。需要同时提供 MCP 的接口请保持 app_key 或 oauth2 认证。

任一校验失败返回 JSON-RPC 错误，HTTP 状态仍为 200，error.data.code 为业务错误码（如 40020 表示未启用 MCP）。

协议交互

initialize

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "clientInfo": { "name": "my-client", "version": "1.0.0" }
  }
}

响应包含协议版本、服务信息和工具能力：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "serverInfo": {
      "name": "{appCode}",
      "title": "{应用名称}",
      "version": "v1"
    },
    "capabilities": {
      "tools": { "listChanged": false }
    }
  }
}

notifications/initialized 返回 HTTP 202，无响应体。

tools/list

返回当前凭证可访问的全部工具，不分页：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

每个工具包含名称、描述和 JSON Schema 输入定义。参数 Schema 由接口的请求参数生成，必填参数进入 required，默认值写入 default。

工具名规则：

优先使用接口上配置的 MCP 工具名（当前界面未开放该字段）；
未配置时由接口路径生成：非字母数字替换为下划线、合并连续下划线、去掉首尾下划线；
以数字开头时加 api_ 前缀；
长度超过 64 截断；
同一凭证下重名时回退为 api_{apiId}。

tools/call

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "user_list",
    "arguments": {
      "pageNum": 1,
      "pageSize": 20
    }
  }
}

调用过程：

按工具名反查目标接口；
校验参数：未声明的参数报 Unknown argument，缺少必填参数报 Missing required argument；
按参数位置把 arguments 转换为目标请求的 header、query、path 和 body；
网关把请求改写为目标接口的真实请求，继续经过日志、WAF、流控、熔断、缓存、订阅配额等过滤器；
目标接口响应被包装为 JSON-RPC 结果，响应体放在 result.content[0].text 中。

调用 tools/call 时：

接口自身的认证被跳过，身份由 MCP 入口的 X-AppKey 确定；
客户端传入的 Authorization、Cookie、X-AppKey、签名头等敏感头不会转发给目标接口；
日志记录为 MCP 来源，可在 API 日志中筛选；
接口级凭证仍受订阅有效期和日调用量约束，超限返回 40023；
项目级凭证直接放行接口级鉴权，但仍受流控、熔断、IP 规则和 WAF 约束。

错误码

JSON-RPC code	含义	常见原因
`-32700`	Parse error	请求体不是合法 JSON
`-32600`	Invalid Request	缺少 `jsonrpc`/`method`，路径不是 `/mcp/{appCode}`，或请求体过大
`-32601`	Method not found	不支持的方法
`-32602`	Invalid params	未知工具、参数缺失、参数未声明、头部参数含 CR/LF
`-32603`	Internal error	服务内部异常
`-32001`	Auth error	应用不存在、被禁用、未启用 MCP、AppCode 不匹配、IP 不在白名单

业务错误码通过 error.data.code 返回，例如 40020（未启用 MCP）、40021（订阅冻结或失效）、40023（日配额超限）。

常见问题

现象	排查方向
初始化成功但工具列表为空	接口未发布 MCP、未上线 prod、认证方式不是 app_key，或凭证未获授权
提示未启用 MCP	在应用凭证编辑中勾选「启用 MCP」
提示 AppCode 不匹配	客户端 URL 中的 appCode 与 AppKey 所属应用不一致
工具调用返回参数错误	对照 `tools/list` 返回的 inputSchema 检查参数名和必填项
工具调用返回 40021	检查订阅是否冻结、过期或已退订
返回 405	客户端使用了 GET 或 SSE 独立通道，改为 POST

管理端 MCP

管理端 MCP 面向 AI 智能体，用于查询和管理 ApiGo 资源。

接入方式

在 账户中心 → MCP 创建智能体，选择智能体类型并绑定工具；
保存后获得以 ak_ 开头的 Agent Key，明文只展示一次；
客户端请求：

POST /api/box/mcp/{agentCode}
X-Agent-Key: {AgentKey}
Content-Type: application/json

鉴权规则：

智能体必须存在且已启用；
Agent Key 经 SHA-256 后与库中哈希比对；
智能体创建者必须仍为有效用户，并拥有智能体所属项目的访问权限；
工具列表受智能体绑定的工具和创建者的管理端权限共同过滤；
项目上下文取自智能体所属项目，所有操作受项目隔离约束。

initialize、tools/list、tools/call 的行为与应用 MCP 一致；GET 请求返回 405（SSE not supported）。鉴权失败时返回 -32603 及具体原因（缺少 API Key、智能体不存在、已禁用、Key 无效、创建者不可用等）。

工具目录

管理端 MCP 当前提供 32 个工具，其中 18 个只读工具、14 个写工具。

只读工具：

类别	工具
数据源	`datasource_list`、`datasource_detail`、`datasource_test`
接口	`api_list`、`api_page`、`api_detail`、`api_versions`、`api_sql_parse`、`api_path_check`、`api_mock_case_draft`
日志	`api_log_query`、`api_log_traffic_trend`
分组	`group_list`
元数据	`metadata_schemas`、`metadata_tables`、`metadata_columns`
凭证	`credential_list`、`credential_detail`

写工具：

类别	工具
数据源	`datasource_add`、`datasource_update`、`datasource_delete`
接口	`api_sql_save`、`api_proxy_save`、`api_publish`、`api_offline`、`api_online`、`api_delete`、`api_destroy`
凭证	`credential_create`、`credential_bind`
分组	`group_create`
调试	`api_debug_invoke`

写工具会在智能助理中触发二次确认；api_debug_invoke 因可能产生业务副作用也按写操作处理。

使用建议

为不同用途创建不同智能体，按最小权限绑定工具；
生产环境的写操作建议只授予必要的智能体；
Agent Key 泄露后立即禁用或重建智能体；
智能体所属项目决定可操作范围，跨项目需求应创建独立智能体。

应用 MCP​

前置条件​

客户端配置​

鉴权规则​

协议交互​

initialize​

tools/list​

tools/call​

错误码​

常见问题​

管理端 MCP​

接入方式​

工具目录​

使用建议​

相关文档​