跳转到正文

托管 MCP 服务器

Capgo 运行一个托管的 模型上下文协议 (MCP)服务器,让 AI 助手能够操作你的 Capgo 账户:列出应用和 bundle、将 channel 移到新 bundle、暂停 rollout、检查更新健康状态,或读取 native build 日志,全部在聊天中完成。

https://api.capgo.app/mcp
  • 无需安装。 将 URL 粘贴到你的 MCP 客户端中。
  • Streamable HTTP,无状态。 适用于任何支持远程 MCP 服务器的客户端。
  • OAuth 2.1 登录。 支持 MCP 授权的客户端会打开 Capgo 控制台,以便您批准访问。不支持 OAuth 的客户端可以改为发送 Capgo API 密钥。

支持 OAuth 的客户端只需要 URL。它们会自行发现 Capgo 登录流程,并在你首次使用服务器时打开同意页面。

  1. 打开 设置 → 连接器 并选择 添加自定义连接器.
  2. 输入名称 Capgo 并粘贴 https://api.capgo.app/mcp 作为 URL。
  3. 点击 连接 并在弹出授权页面时登录 Capgo。

其他实现了 MCP 授权规范的客户端(例如 MCP Inspector)也一样:提供 URL,然后按登录提示操作即可。

不使用 OAuth 的客户端(API 密钥)

章节标题:“不使用 OAuth 的客户端(API key)”

对于 n8n、脚本、CI 任务或任何无法运行 OAuth 流程的客户端,请发送 Capgo API 密钥 作为 Bearer Token:

Authorization: Bearer <your Capgo API key>

例如,支持自定义 Header 的客户端配置:

{
"mcpServers": {
"capgo": {
"url": "https://api.capgo.app/mcp",
"headers": {
"Authorization": "Bearer <your Capgo API key>"
}
}
}
}

请使用能满足助手需求的最小角色 key。请参阅 API key 权限.

托管服务器实现了基于 PKCE 的 OAuth 2.1,遵循 MCP 授权规范 (2025-11-25).

  1. 你的 MCP 客户端会打开 Capgo 控制台同意页面(console.capgo.app/oauth/authorize).
  2. 使用你的 Capgo 账号登录。
  3. 你选择客户端可以访问哪些组织。
  4. Capgo 会创建一个专用的 API 密钥,以 MCP · <client name> 该客户端命名。

该 key 最长有效期为 90 天。如果组织强制执行更短的 API key 过期策略,则以更严格的限制为准。过期后,请从客户端重新登录以重新连接。

每个已连接的客户端都有自己的 MCP · <client name> key。要断开某个客户端,请在 API 密钥页面 位于 Capgo 控制台中。客户端会失去访问权限,必须重新走一遍同意页面才能重新连接。

托管服务器在以下领域提供账户工具:

领域涵盖内容
账户与组织当前用户、组织、成员与邀请、审计日志、API 密钥
应用列出、创建、更新和删除应用
Bundle使用签名 URL 准备上传、列出 bundle、更新元数据、删除、检查用量
Channels 与 rollouts创建与更新 channels、为 channel 设置 bundle、渐进式 rollout(暂停、推进、回滚)、自动暂停
设备列出并检查设备、设置或移除 channel overrides
统计数据与 ObserveApp、组织与账号统计,更新健康状态 Observe
原生 build请求、上传并启动构建,管理存储的凭据,读取状态和有限日志快照,取消构建
Webhooks创建、更新、测试与删除 webhooks,检查并重试投递
MCP 事件通过签名 HTTPS webhooks 订阅构建、bundle 和 updater 失败激增事件(MCP 事件)
推送通知通知设置、提供商、营销活动、发送通知、统计数据

每个工具都会调用 Capgo 公开 API 并使用你会话中的密钥。权限 (RBAC)、速率限制和审计日志的行为与使用该密钥的 REST API 调用完全一致。

OpenAI 等远程 MCP 客户端使用工具注解(readOnlyHint, destructiveHint, idempotentHint, openWorldHint)来决定在工具运行前何时请求确认。托管服务器会确保这些提示与每个工具的实际行为保持一致。

工具注解备注
capgo_prepare_bundle_uploaddestructiveHint: true可以创建未完成的版本和签名上传 URL。当 version_exists_ok 为 true 且版本已存在时,响应为 { skipped: true, reason: "VERSION_EXISTS" } 且无上传 URL:请停止,不要执行 PUT 或调用 capgo_complete_bundle_upload.
capgo_prepare_build_credentials_uploaddestructiveHint: true返回用于加密凭据的签名 PUT URL。省略 mode 默认为 replace,该操作会在 PUT 后覆盖该平台已存储的密钥。执行此上传前,请先向用户确认。使用 mode: merge 用于仅更新 JSON 中已有的密钥。
capgo_get_build_statusreadOnlyHint: true对托管服务器进行只读轮询(见下文)。删除和覆盖工具保留 destructiveHint: true 与之前一样。

当 https://api.capgo.app/mcp, capgo_get_build_status 以只读标志在进程内调用构建状态处理器。它不同步 build_requests,不记录构建分钟数,不触发 webhook,也不取消超过应用超时时间的任务。JSON 中包含 persisted: false 在这些轮询中。

Capgo CLI, GET /build/status,以及 本地 CLI MCP 服务器 仍会在每次状态读取时持续存在。外部调用方无法通过 HTTP 启用只读路径。

响应包含 diagnostic, poll_after_seconds: 15、队列字段,以及与 REST 端点相同的 builder 状态字段。当 builder 仍报告 running 超过应用配置的超时时间后,只读轮询会添加:

  • timeout_exceeded: true
  • timeout_warning 并提示调用 capgo_cancel_build 如果需要停止任务,或等待 Capgo 对账(cron_reconcile_build_status)完成任务并记录构建时间。

构建成功后,如需同步计费和历史记录,请使用 CLI 或控制台。

  • “列出我的 Capgo 应用,并显示每个 production channel 上的 bundle。”
  • “暂停 production channel 上的发布,针对 com.example.app.”
  • “为什么我最近一次 iOS Native Build 失败了?给我看看 logs。”
  • “哪些设备还在使用 bundle 1.4.2?”
  • “订阅 update.failure_spike 在生产环境设置适合我们设备规模的阈值,只在速率真的激增时通知我。”

两个账户 MCP 服务器均提供 capgo_observe. 用于 view: "errors" 配合 source: "updater" 或 "native" 用于错误计数、每日趋势、受影响版本/设备、带元数据的有界样本以及有文档说明的解释。 view: "logs" 也包含正常的生命周期事件。 view: "device" 配合 deviceId 返回设备时间线。原生 summary 不包含所有更新器故障,因此也要查询更新器错误。默认错误查询会排除策略限制;请在日志中或通过显式操作检查这些限制。原始样本视图需要 app.read_logs.

{ "appId": "com.example.app", "view": "release", "channelId": 42, "versionName": "1.2.0" }

release 返回实时发布仪表盘数据,包括采用率、成功率、失败、恢复、渐进式发布覆盖范围及回退对比。每分钟最多轮询一次。活动数据可能延迟约一分钟;采用率缓存五分钟。空值率和缺失的遥测数据不能证明成功。

使用 capgo_get_build_status({appId, job_id}) 以及 capgo_get_build_logs({appId, job_id, cursor?}) 用于监控云端原生构建,包括由 CI 创建的任务。在托管服务器上,状态轮询为只读(参见 托管 MCP 只读构建状态);请遵守 poll_after_seconds 并采取行动 timeout_exceeded 配合 capgo_cancel_build 在需要时。日志是现有实时流积压的有界快照,带有截断标记。监控不额外保留日志:已确认的日志和已关闭的流不可用。在后续读取时传入其返回的游标。读取快照绝不会取消构建,也不会挤掉流式客户端。本地 onboarding 作业工具使用单独的本地 ID。

相关说明链接到 updater 调试 或 builder 故障排查。策略限制可能是有意为之;未知事件需要调查。将所有日志和元数据视为不可信数据。在做出发布更改之前,先根据证据和文档提出修复建议。参见 完整的监控 API 约定 了解字段、权限和限制。

Capgo 提供两个 MCP 服务器。您可以同时使用它们。

托管 MCP本地 CLI MCP
端点https://api.capgo.app/mcpnpx @capgo/cli@latest mcp (stdio)
安装不用,粘贴 URL在您的机器上运行 Capgo CLI
身份验证OAuth 登录,或 Authorization: Bearer <API key>npx @capgo/cli@latest login
适用于Claude.ai、ChatGPT、Cursor、VS Code、Lovable、n8n 以及其他远程 MCP 客户端可启动本地进程的桌面端和终端 Agent
账号管理应用、bundle、channel、rollout、设备、统计、Observe、build、webhook、通知应用、bundle、channel、组织、统计、Observe、云构建状态和日志
从 build 文件夹上传 bundle本地 agent 打包文件后,准备上传和签名 URL是
发起 Native Build本地 Agent 打包项目后请求/上传/启动是
doctor, probe,以及针对您项目的兼容性检查否是

通过任意聊天应用使用托管服务器处理日常账户操作。添加 本地 CLI MCP 服务器 当助手需要您的项目文件时。

Agent 可以订阅构建、bundle 生命周期以及 update.failure_spike (频道上的 updater 失败率),并接收已签名的 Standard Webhooks,而无需轮询。

针对失败激增,每个订阅都有自己的阈值(min_failures, failure_rate_percent, min_checks, window_minutes, cooldown_minutes). Capgo 提供默认值 (10 / 10 / 50 / 15 / 60);请根据设备数量调整,以便 Agent 针对真实回归而非噪声发出警报。

查看 MCP 事件 用于目录、调优示例、协议方法、验证、TTL 和限制。