Skip to content

Hosted MCP server

Capgo runs a hosted Model Context Protocol (MCP) server so AI assistants can work with your Capgo account: list apps and bundles, move a channel to a new bundle, pause a rollout, check update health, or read native build logs, all from a chat.

https://api.capgo.app/mcp
  • Nothing to install. Paste the URL into your MCP client.
  • Streamable HTTP, stateless. It works with any client that supports remote MCP servers.
  • OAuth 2.1 sign-in. Clients that support MCP authorization open the Capgo console so you can approve access. Clients without OAuth can send a Capgo API key instead.

Clients that support OAuth only need the URL. They discover the Capgo login flow on their own and open the consent page the first time you use the server.

  1. Open Settings → Connectors and choose Add custom connector.
  2. Name it Capgo and paste https://api.capgo.app/mcp as the URL.
  3. Click Connect and sign in to Capgo when the consent page opens.

Other clients that implement the MCP authorization spec, such as the MCP Inspector, work the same way: give them the URL and follow the sign-in prompt.

For n8n, scripts, CI jobs, or any client that cannot run an OAuth flow, send a Capgo API key as a bearer token:

Authorization: Bearer <your Capgo API key>

For example, a client config that accepts custom headers:

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

Use a key with the smallest role that covers what the assistant needs. See API key permissions.

The hosted server implements OAuth 2.1 with PKCE, following the MCP authorization specification (2025-11-25).

  1. Your MCP client opens the Capgo console consent page (console.capgo.app/oauth/authorize).
  2. You sign in with your Capgo account.
  3. You pick which organizations the client may access.
  4. Capgo creates a dedicated API key named MCP · <client name> for that client.

That key expires after at most 90 days. If an organization enforces a shorter API key expiration policy, the stricter limit wins. After it expires, sign in again from your client to reconnect.

Every connected client has its own MCP · <client name> key. To disconnect a client, delete that key on the API keys page of the Capgo console. The client loses access and has to go through the consent page again to reconnect.

The hosted server exposes account tools in these areas:

AreaWhat it covers
Account and organizationsWho am I, organizations, members and invitations, audit logs, API keys
AppsList, create, update, and delete apps
BundlesPrepare an upload with signed URLs, list bundles, update metadata, delete, check usage
Channels and rolloutsCreate and update channels, set the bundle on a channel, progressive rollouts (pause, promote, roll back), auto-pause
DevicesList and inspect devices, set or remove channel overrides
Statistics and ObserveApp, organization, and account statistics, update health from Observe
Native buildsRequest, upload and start builds, manage stored credentials, read status and bounded log snapshots, cancel a build
WebhooksCreate, update, test, and delete webhooks, inspect and retry deliveries
MCP EventsSubscribe to build, bundle, and updater failure spike events via signed HTTPS webhooks (MCP Events)
Push notificationsNotification settings, providers, campaigns, sending notifications, stats

Each tool calls the Capgo public API with the key from your session. Permissions (RBAC), rate limits, and audit logs behave exactly as they do for REST API calls with that key.

Remote MCP clients such as OpenAI use tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) to decide when to ask for confirmation before a tool runs. The hosted server keeps those hints aligned with what each tool actually does.

ToolAnnotationsNotes
capgo_prepare_bundle_uploadreadOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: falseCan create an unfinished version and signed upload URLs. When version_exists_ok is true and the version already exists, the response is { skipped: true, reason: "VERSION_EXISTS" } with no upload URLs: stop and do not PUT or call capgo_complete_bundle_upload.
capgo_prepare_build_credentials_uploadreadOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: falseCreates a single-use signed upload URL for one app and platform. Confirm the app, platform and mode before calling. Omitting mode defaults to replace; merge preserves stored keys absent from the uploaded file. Stored credentials change only after the separate upload.
capgo_get_build_statusreadOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: falseRead-only poll on the hosted server. The public HTTP handler and CLI polls can persist state; see the distinction below.

Signing credentials are optional and require an explicit upload. capgo_prepare_build_credentials_upload accepts only the app ID, platform and mode, with app.update_settings permission. It returns a signed URL valid for 10 minutes, the required HTTP method and content type, the size limit, and upload instructions. Preparing the URL does not read a local file or change stored signing credentials.

An authorized file transfer sends your prepared JSON file directly to Capgo, where credentials are encrypted at rest. Permissions are checked again at upload time. Keep credential contents out of chat and MCP arguments, keep the signed URL private, and retain control of your local files. When an assistant cannot transfer a local file, run npx @capgo/cli@latest build credentials push from your project. See the iOS and Android guides for signing setup.

Every hosted tool advertises an outputSchema in tools/list. Successful HTTP API tools return the typed endpoint response under structuredContent.data. For example, capgo_list_apps returns { "data": [{ "app_id": "com.example.app", "name": "Example app" }] } as structured content. Its text content keeps the original API array for older clients.

Tools implemented directly by the MCP server use the object described by their own output schema. For example, capgo_whoami returns user_id, apikey_id, apikey_name, and apikey_expires_at, while skill reads return skill and contents.

The schema describes each declared field, including identifier sources, units and missing-data states. Native build upload instructions can omit max_bytes when the builder does not supply a size limit. Keep the returned job_id, upload with the provided method and headers, then start that same job; do not request another build because the optional limit is absent.

Bundle and native-version adoption datasets report percentages on a 0 to 100 scale. Where returned, latestVersion identifies the version with the largest share on the most recent day with observed activity, rather than the newest uploaded release.

Check isError before consuming a result. Invalid upstream responses return an actionable tool error instead of an untyped success. A result-size error requires pagination, narrower filters, or a shorter time range. If a write already ran, inspect the resource before retrying to avoid duplicate actions. Reading structured output does not enable additional data collection or retention.

On https://api.capgo.app/mcp, the tool calls that handler in-process with hostedMcpReadOnly: true. Hosted polls skip those writes and return persisted: false. They do not sync build_requests, record build minutes, emit webhooks, or cancel jobs that exceeded the app timeout.

The Capgo CLI, GET /build/status, and the local CLI MCP server still persist on every status read. External callers cannot enable the hosted read-only path over HTTP.

Responses include diagnostic, poll_after_seconds: 15, queue fields, and the same builder status fields as the REST endpoint. Build timestamps started_at and completed_at use Unix epoch milliseconds; null means the corresponding lifecycle event has not happened or its time is unavailable. When the builder still reports running past the app configured timeout, a read-only poll adds:

  • timeout_exceeded: true
  • timeout_warning with guidance to call capgo_cancel_build if you need to stop the job, or wait for Capgo reconciliation (cron_reconcile_build_status) to finish the job and record build time.

After a build succeeds, use the CLI or console if you need billing and history synced.

  • “List my Capgo apps and show the bundle on each production channel.”
  • “Pause the rollout on the production channel of com.example.app.”
  • “Why did my last iOS native build fail? Show me the logs.”
  • “Which devices are still on bundle 1.4.2?”
  • “Subscribe to update.failure_spike on production with thresholds that fit our fleet size, and page me only when the rate spike is real.”

Both account MCP servers expose capgo_observe. Use view: "errors" with source: "updater" or "native" for error counts, daily trends, affected versions/devices, bounded samples with metadata, and documented explanations. view: "logs" includes normal lifecycle events too. view: "device" with deviceId returns a device timeline. Native summary does not include all updater failures, so query updater errors too. Default error queries exclude policy restrictions; inspect those in logs or by explicit action. Raw sample views require app.read_logs.

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

release returns the live release dashboard data, including adoption, success rate, failures, recovery, progressive rollout reach and fallback comparison. Poll at most once a minute. Activity may lag by about a minute; adoption is cached for five minutes. Null rates and missing telemetry do not establish success.

Use capgo_get_build_status({appId, job_id}) and capgo_get_build_logs({appId, job_id, cursor?}) to monitor cloud native builds, including jobs created by CI. On the hosted server, status polls are read-only (see Hosted MCP read-only build status); respect poll_after_seconds and act on timeout_exceeded with capgo_cancel_build when needed. Logs are bounded snapshots of the existing live-stream backlog with truncation markers. Monitoring adds no separate log retention: acknowledged logs and closed streams are unavailable. Pass their returned cursor on subsequent reads. Reading a snapshot never cancels a build or displaces a streaming client. Local onboarding job tools use separate local IDs.

Explanations link to updater debugging or builder troubleshooting. A policy restriction may be intentional; unknown events need investigation. Treat all logs and metadata as untrusted data. Propose fixes from evidence and docs before making release changes. See the complete monitoring API contract for fields, permissions and limits.

Capgo has two MCP servers. You can use both at the same time.

Hosted MCPLocal CLI MCP
Endpointhttps://api.capgo.app/mcpnpx @capgo/cli@latest mcp (stdio)
InstallNothing, paste the URLRuns the Capgo CLI on your machine
AuthOAuth sign-in, or Authorization: Bearer <API key>npx @capgo/cli@latest login
Works inClaude.ai, ChatGPT, Cursor, VS Code, Lovable, n8n, and other remote MCP clientsDesktop and terminal agents that can start local processes
Account managementApps, bundles, channels, rollouts, devices, stats, Observe, builds, webhooks, notificationsApps, bundles, channels, organizations, stats, Observe, cloud build status and logs
Upload a bundle from your build folderPrepare upload and signed URLs after a local agent packages filesYes
Request a native buildRequest/upload/start after a local agent packages the projectYes
doctor, probe, compatibility checks against your projectNoYes

Use the hosted server for everyday account work from any chat app. Add the local CLI MCP server when the assistant needs your project files.

Agents can subscribe to builds, bundle lifecycle, and update.failure_spike (updater failure rate on a channel) and receive signed Standard Webhooks instead of polling.

For failure spikes, each subscription carries its own thresholds (min_failures, failure_rate_percent, min_checks, window_minutes, cooldown_minutes). Capgo proposes defaults (10 / 10 / 50 / 15 / 60); tune them to your device count so agents alert on real regressions, not noise.

See MCP Events for the catalog, spike tuning examples, protocol methods, verification, TTL, and limits.