Name: Appcircle MCP Server
Author: appcircleio

LABSCO SUMMARY

Four tools open their own description with SIDE EFFECT, which is the cheapest possible way to tell an agent which calls it should stop and ask about.

A build pipeline surface is mostly reads with a few operations that cost money and start machines. Labelling those inline means a model does not have to infer intent from a verb — trigger_build could plausibly be a dry run, and the description settles it before the call rather than after. The metadata lock check is the other detail that shows real familiarity: store metadata being locked mid-release is a normal state and an integration that does not check it produces a confusing failure at the worst moment. Step-scoped logs on both build and publish is the practical touch — mobile build output is enormous and unscoped retrieval is unusable from a chat client.

What it is

An Appcircle client covering the mobile build and release pipeline end to end: build profiles with their configurations and workflows, commit history, build status and logs, variable groups, enterprise store and publish profiles, store metadata, and the publish flow itself.

What you get

Every write tool announces itself — trigger_build, cancel_build, start_publish and stop_publish each open their description with SIDE EFFECT and say plainly that this is a write action.
Builds are inspectable before and after: profiles, their configurations, their workflows, and a single workflow's detail.
Commits by branch, a single commit by UUID or git SHA, and the most recent commit on a branch — three lookups because those are three different questions.
get_build_logs can be scoped to a single step rather than returning the whole run, which for a mobile build is the difference between a readable answer and a wall.
The publish half mirrors it: publish profiles by platform, the flows configured on one, the run details for an app version, and step-scoped publish logs.
Store metadata is covered properly — listing metadata per app version, the available locales, Microsoft Intune metadata, and whether the metadata is currently locked for editing.
get_build_history_report returns the history optionally filtered by date range, which is the reporting view rather than the per-build one.

Requirements

An Appcircle access token (a Personal Access Key or API key). The hosted server at https://mcp.appcircle.io takes it as an Authorization: Bearer header; a local build reads it from APPCIRCLE_ACCESS_TOKEN and needs Python 3.10+.

Setup effort

Paste a URL with a key — add the endpoint to your client

See installation options

USE CASES

Finding out why a build failed

Check the build status, then pull the logs scoped to the failing step rather than the entire run.

get_build_statusget_build_logsget_build_profile_details

Working out what is about to be built

Read the branch's recent commits or the latest one, and check the workflow and configuration the build will run under.

get_commits_by_branchget_last_commitget_commit_detailsget_build_profile_workflowsget_workflow_detail

Starting or stopping a run

Trigger the build or cancel a queued one — both marked as side effects in their own descriptions, so the decision is explicit.

trigger_buildcancel_buildget_variable_groups

Getting a version to the store

Read the publish profile and its flows, check whether the store metadata is locked, then start the publish and follow its step logs.

get_publish_profilesget_publish_flowsget_publish_metadata_lock_statusstart_publishget_publish_step_logsstop_publish

Checking a listing before it goes live

Read the app version's store metadata, the locales it exists in, and the Intune metadata if you distribute through it.

get_app_version_metadataget_metadata_localesget_intune_metadataget_store_profilesget_store_profile_details

Reporting on how the pipeline is doing

Pull the build history over a date range instead of reconstructing it from individual builds.

get_build_history_reportget_build_profiles

47 tools

Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.

`cancel_build`

SIDE EFFECT: Cancels a queued or running build. This is a write/action tool -- it stops real, in-progress work; the build cannot be resumed afterward.

Args: task_id: The build's task ID (the "taskId" field returned by trigger_build).

Returns: Standard envelope (see docs/tool_contract.md):

Success: success (true), data ({"task_id": <uuid>, "cancelled": true}), meta (empty).
Error: success (false), error (tool, type, message, details). type is invalid_state (HTTP 409/422) when the build has already finished and can no longer be cancelled.

Examples: Cancel a build: cancel_build(task_id="task-uuid")

`get_build_insights_report`

Get a computed Build Insights Report over build history: Health Snapshot + Trends, Root Cause, Artifact Health, Workflow Quality, Queue Time, and Maturity Assessment analysis, aggregated server-side.

Unlike get_build_history_report (which returns raw paginated records), this tool fetches every page internally, computes percentiles/grouping/MTTR/flaky detection in Python, and returns only the small aggregated result. Sections that can't be computed from the available data (e.g. a field stripped by an Appcircle role restriction) are omitted rather than rendered as zeros or fabricated, and flagged in meta.omitted_sections / meta.omitted_subsections. Only the current-period build history fetch is mandatory -- every other fetch (previous period, profiles, queue waiting, signing identities, per-profile workflow/trigger/configuration data) is best-effort: a 401/403 from a token lacking permission for that specific resource (e.g. an admin-only endpoint) omits just the dependent section/subsection instead of failing the whole call, and is listed in meta.failed_fetches.

A main-org access token sees build history spanning every sub-organization, but can only enumerate its own org's profiles (the Appcircle API itself enforces this -- not something this tool can fetch around). By default the report is scoped to the token's own organization: build records whose profile isn't in that token's own profile list are excluded before any section is computed, so every section always means the same scope. Set include_sub_orgs=True to keep cross-org records in history-derived metrics (Health Snapshot, Root Cause, Artifact Health, Speed/Reliability) -- Workflow Quality/Discipline/Security for those profiles still can't be resolved (the API limitation doesn't go away), so they're omitted for those specific profiles rather than fabricated, and listed in meta.unresolved_profiles. queue_time has no profile field to scope by, so it's always a tree-wide aggregate regardless of this flag.

Args: start_date: Optional start date (format: "YYYY-MM-DD") for the current period. end_date: Optional end date (format: "YYYY-MM-DD") for the current period. If both start_date and end_date are omitted, defaults to the last 30 days. If only one is given, the other is filled to a 30-day-wide window. sections: Optional list of sections to compute. Subset of ["health_snapshot", "root_cause", "artifact_health", "workflow_quality", "queue_time", "maturity_assessment"]. Defaults to all six. Invalid section names return a validation error. include_sub_orgs: If True, keep cross-org build records in history-derived metrics instead of filtering them to the token's own org (default False). See the note above on what stays unresolved either way.

Returns: Standard envelope (see docs/tool_contract.md):

Success: success (true), data (date_range, sections.health_snapshot, sections.root_cause, sections.artifact_health, sections.workflow_quality, sections.queue_time, sections.maturity_assessment), meta (requested_sections, omitted_sections, omitted_subsections, failed_fetches, cross_org_builds_excluded, unresolved_profiles).
Error: success (false), error (tool, type, message, details).

Examples: Full report, last 30 days: get_build_insights_report() Root cause only, custom range: get_build_insights_report( start_date="2026-01-01", end_date="2026-01-31", sections=["root_cause"] ) Include cross-org records from a main-org token: get_build_insights_report(include_sub_orgs=True)

`get_build_logs`

Get the logs for a build, optionally scoped to a single step.

By default returns only the tail of the log (last 200 lines, capped at 64 KB) to avoid flooding the model's context. Pass full_log=True for the entire log instead (still capped at 256 KB as a safety net). Pass step to scope the output to one workflow step's log block, matched by its exact name as it appears in the log (e.g. "Xcode Select", or "Custom Script(1)" when a workflow has more than one step of the same type) -- the log marks each step with "Step started: <name>" / "Step completed: <name>[, Ver: <version>]" lines. A failed step still gets a "Step completed:" line; look for "@@[error]" lines inside the step's body instead. Use grep to keep only lines containing a case-insensitive substring before truncation (e.g. grep="error").

Args: commit_id: The commit ID (UUID). build_id: The build ID (UUID). step: Optional exact step name (case-insensitive) to scope the output to just that step's log block. If no step with this name is found, returns a validation_error listing the step names actually present in the log. full_log: If True, return the entire log (or entire step, if step is given) instead of the default tail. Still capped at 256 KB. Default: False. tail_lines: Number of lines to keep from the end when not using full_log. Default: 200. Max: 1000. Ignored when full_log=True. grep: Case-insensitive substring filter applied to lines before truncation.

Returns: Standard envelope (see docs/tool_contract.md):

Success: success (true), data (the resulting log text), meta (total_lines, returned_lines, truncated, full_log, step, steps -- the ordered list of all step names found in the log -- and grep, when provided).
Error: success (false), error (tool, type, message, details). When step is given but not found, type is validation_error and details.available_steps lists the step names found in the log.

Examples: Default tail: get_build_logs(commit_id="c-uuid", build_id="b-uuid") Full log: get_build_logs(commit_id="c-uuid", build_id="b-uuid", full_log=True) One step: get_build_logs(commit_id="c-uuid", build_id="b-uuid", step="Xcode Select") Errors only: get_build_logs(commit_id="c-uuid", build_id="b-uuid", grep="error")

`get_build_profiles`

Get build profiles for the current organization (paginated).

Returns a list of build profiles with their IDs, names, platform types, repository information, build status, and configuration details. Optionally filter by profile name using the search parameter, and/or by platform, last build status, and repository source. Optionally sort.

Args: page: Page number (1-based). Default: 1. size: Page size (1-100). Default: 25. Values above 100 are capped at 100. search: Optional search term to filter profiles (case-insensitive partial match on profile name; the API's search may also match other profile fields). For example, search="iOS" will return profiles with "iOS" in their name, and possibly others matching on a different field. platform: Optional list of platform codes to filter by. Allowed values: 1=iOS, 2=Android. last_build_status: Optional list of last build status codes to filter by. Allowed values: 0=Success, 1=Failed, 2=Canceled, 3=Timeout, 90=Waiting, 91=Running. repository_source: Optional list of repository source codes to filter by. Allowed values: 1=GitHub, 2=Bitbucket, 3=GitLab, 4=Azure DevOps, 6=Public Repository, 7=Private Repository, 8=SSH. sort: Optional sort field code. Allowed values: 1=Profile Name, 2=Create Date, 3=Last Build Date. sort_direction: Optional sort direction code. Allowed values: 1=ASC, 2=DESC.

Returns: Standard envelope (see docs/tool_contract.md):

Success: success (true), data (list of build profile objects), meta (count, page, page_size, search_term, platform, last_build_status, repository_source, sort, sort_direction).
Error: success (false), error (tool, type, message, details). Profile objects exclude connectionEnvironmentKey and webhookSecret.

Examples: Get first page (default size 25): get_build_profiles() Get page 2 with 10 items: get_build_profiles(page=2, size=10) Search for iOS profiles: get_build_profiles(search="iOS") Filter by platform and last build status: get_build_profiles(platform=[1], last_build_status=[1]) Sort by create date descending: get_build_profiles(sort=2, sort_direction=2)

`get_publish_profiles`

Get publish profiles for the current organization for a given platform type (paginated).

Returns a list of publish profiles with their IDs, names, app versions, version information, flow status information, and profile settings. Optionally filter by flow status, target marketplace, release-candidate binary presence, and store status. Optionally sort.

Args: platform_type: Platform type of publish profiles ("ios" or "android"). page: Page number (1-based). Default: 1. size: Page size (1-100). Default: 25. Values above 100 are capped at 100. flow_status: Optional flow status code to filter by (single value). Allowed values: 0=Success, 1=Failed, 2=Canceled, 3=Timeout, 90=Waiting, 91=Running, 92=Completing, 99=Unknown, 200=NotStarted, 201=Stopped, 202=InProgress, 203=AwaitingResponse. market_place_type: Optional list of target marketplace codes to filter by. Allowed values depend on platform_type: ios: 0=Not Available, 1=App Store Connect, 4=Intune. android: 0=Not Available, 2=Google Play, 3=AppGallery, 4=Intune. has_rc_binary: Optional filter for whether the profile has a release-candidate binary. store_status: Optional list of store status codes to filter by. Allowed values depend on platform_type (many more codes for ios than android, e.g. ios: "IN_REVIEW", "READY_FOR_SALE", "REJECTED", etc.; android: "NOT_AVAILABLE", "DRAFT", "IN_PROGRESS", "HALTED", "COMPLETED"). sort: Optional sort field code. Allowed values: 1=Profile Name, 2=Create Date. sort_direction: Optional sort direction code. Allowed values: 1=ASC, 2=DESC.

Returns: Standard envelope (see docs/tool_contract.md):

Success: success (true), data (list of publish profile objects), meta (page, page_size, platform_type, flow_status, market_place_type, has_rc_binary, store_status, sort, sort_direction, pagination metadata).
Error: success (false), error (tool, type, message, details).

Examples: Get first page of iOS profiles: get_publish_profiles(platform_type="ios") Get page 2 with 10 items: get_publish_profiles(platform_type="android", page=2, size=10) Filter by flow status: get_publish_profiles(platform_type="ios", flow_status=0) Filter by marketplace and store status: get_publish_profiles(platform_type="ios", market_place_type=[1], store_status=["IN_REVIEW"])

`get_publish_step_logs`

Get the logs for a publish flow run, optionally scoped to a single step.

The log returned for a given step_id may include other steps of the same publish flow run in the same log text (Appcircle stores one combined log per run). By default returns only the tail of the log (last 200 lines, capped at 64 KB) to avoid flooding the model's context. Pass full_log=True for the entire log instead (still capped at 256 KB as a safety net). Pass step to scope the output to one workflow step's log block, matched by its exact name as it appears in the log (e.g. "Send to Microsoft Intune") -- the log marks each step with "Step started: <name>" / "Step completed: <name>[, Ver: <version>]" lines. Use grep to keep only lines containing a case-insensitive substring before truncation (e.g. grep="error").

Args: platform_type: Platform type ("ios" or "android"). profile_id: The publish profile ID (e.g. UUID). publish_id: The publish flow run ID (the "id" field from get_publish_details). step_id: The step ID (a step's "id" field from get_publish_details' steps list). step: Optional exact step name (case-insensitive) to scope the output to just that step's log block. If no step with this name is found, returns a validation_error listing the step names actually present in the log. full_log: If True, return the entire log (or entire step, if step is given) instead of the default tail. Still capped at 256 KB. Default: False. tail_lines: Number of lines to keep from the end when not using full_log. Default: 200. Max: 1000. Ignored when full_log=True. grep: Case-insensitive substring filter applied to lines before truncation.

Returns: Standard envelope (see docs/tool_contract.md):

Success: success (true), data (the resulting log text), meta (total_lines, returned_lines, truncated, full_log, step, steps -- the ordered list of all step names found in the log -- and grep, when provided).
Error: success (false), error (tool, type, message, details). When step is given but not found, type is validation_error and details.available_steps lists the step names found in the log.

Examples: Default tail: get_publish_step_logs(platform_type="ios", profile_id="p-uuid", publish_id="pub-uuid", step_id="step-uuid") Full log: get_publish_step_logs(platform_type="ios", profile_id="p-uuid", publish_id="pub-uuid", step_id="step-uuid", full_log=True) One step: get_publish_step_logs(platform_type="ios", profile_id="p-uuid", publish_id="pub-uuid", step_id="step-uuid", step="Send to Microsoft Intune") Errors only: get_publish_step_logs(platform_type="ios", profile_id="p-uuid", publish_id="pub-uuid", step_id="step-uuid", grep="error")

`trigger_build`

SIDE EFFECT: Starts a new real build run on Appcircle. This is a write/action tool -- it queues an actual build (consuming build minutes/credits), it does not just read data.

Trigger a new build either on a branch (latest synced commit) or for one specific commit. Exactly one of these two modes must be used:

Branch mode (default): requires profile_id and workflow_id. branch_name is optional (falls back to the profile's default branch if omitted).
Commit mode: requires commit_id (the commit's own id, e.g. from get_last_commit/get_commits_by_branch/get_commit_details -- not the git hash). workflow_id is optional in this mode (falls back to the last-used or default workflow for that commit's profile if omitted). profile_id and branch_name are not used in this mode (the commit_id already scopes to one profile/branch) and must not be given together with commit_id/branch_name respectively.

No environment-variable overrides can be passed through this tool.

Args: profile_id: The build profile ID (e.g. UUID). Required in branch mode; unused in commit mode. workflow_id: The workflow ID (e.g. UUID). Required in branch mode. Optional in commit mode (uses the last-used/default workflow for that commit if omitted). branch_name: Optional branch name (e.g. "main"). Branch mode only; falls back to the profile's default branch if omitted. Must not be given together with commit_id. commit_id: The commit's own ID (not its git hash) to trigger a build for a specific commit instead of the latest one on a branch. Must not be given together with branch_name. configuration_id: Optional build configuration ID (e.g. UUID) to use instead of the branch/commit's default configuration.

Returns: Standard envelope (see docs/tool_contract.md):

Success: success (true), data ({"taskId": <uuid>, "queueItemId": <uuid>}), meta (trigger_mode, profile_id, workflow_id, branch_name, commit_id, configuration_id).
Error: success (false), error (tool, type, message, details). type is validation_error for a bad combination of arguments, or invalid_state (HTTP 409/422) when the target branch/commit/workflow is not in a state that allows triggering a build right now.

Examples: Trigger on a branch's latest commit: trigger_build(profile_id="p-uuid", workflow_id="wf-uuid", branch_name="main") Trigger on the profile's default branch: trigger_build(profile_id="p-uuid", workflow_id="wf-uuid") Trigger for a specific commit: trigger_build(commit_id="commit-uuid") Trigger for a specific commit with an explicit workflow: trigger_build(commit_id="commit-uuid", workflow_id="wf-uuid")

INSTALLATION

Connect your client

Server setup

Setup

TERMINAL

git clone https://github.com/appcircleio/appcircle-mcp.git
cd appcircle-mcp
pip install .
which appcircle-mcp

Hosted endpoint

ENDPOINT URL

https://mcp.appcircle.io

Authentication: An Appcircle access token (Personal Access Key or API key), sent by your client as an Authorization: Bearer header on each request

MCP Clients

Claude Desktop, Antigravity

JSON

{
  "mcpServers": {
    "appcircle": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.appcircle.io",
        "--header",
        "Authorization: Bearer <YOUR_APPCIRCLE_ACCESS_TOKEN>"
      ]
    }
  }
}

Claude Code

CLAUDE CODE · TERMINAL

claude mcp add appcircle https://mcp.appcircle.io \
--transport http \
--header "Authorization: Bearer <YOUR_APPCIRCLE_ACCESS_TOKEN>"

Cursor

CURSOR · JSON

{
  "mcpServers": {
    "appcircle": {
      "url": "https://mcp.appcircle.io",
      "headers": {
        "Authorization": "Bearer <YOUR_APPCIRCLE_ACCESS_TOKEN>"
      }
    }
  }
}

VS Code

VS CODE · JSON

{
  "servers": {
    "appcircle": {
      "type": "http",
      "url": "https://mcp.appcircle.io",
      "headers": {
        "Authorization": "Bearer <YOUR_ACCESS_TOKEN>"
      }
    }
  }
}

Windsurf

WINDSURF · JSON

{
  "mcpServers": {
    "appcircle": {
      "serverUrl": "https://mcp.appcircle.io",
      "headers": {
        "Authorization": "Bearer <YOUR_ACCESS_TOKEN>"
      }
    }
  }
}

Gemini CLI

GEMINI CLI · JSON

{
  "mcpServers": {
    "appcircle": {
      "httpUrl": "https://mcp.appcircle.io",
      "headers": {
        "Authorization": "Bearer <YOUR_ACCESS_TOKEN>"
      }
    }
  }
}

Codex

CODEX · TOML

[mcp_servers.appcircle]
url = "https://mcp.appcircle.io"

[mcp_servers.appcircle.http_headers]
Authorization = "Bearer <YOUR_ACCESS_TOKEN>"

GitHub Copilot

GITHUB COPILOT · JSON

{
  "mcpServers": {
    "appcircle": {
      "type": "http",
      "url": "https://mcp.appcircle.io",
      "headers": {
        "Authorization": "Bearer ${APPCIRCLE_ACCESS_TOKEN}"
      }
    }
  }
}

This is for GitHub Copilot CLI: add it to ~/.copilot/mcp-config.json, then restart the Copilot CLI session and run /mcp show to check. Copilot CLI does not fill in ${APPCIRCLE_ACCESS_TOKEN} by itself: set that environment variable before you start it. The header can also carry the token itself, as Bearer followed by the token. Copilot in VS Code uses the VS Code tab.

Claude Desktop — Local stdio

For the local build above: <YOUR_PATH_WHICH_APPCIRCLE_MCP> is the path that which appcircle-mcp printed, and <YOUR_APPCIRCLE_ACCESS_TOKEN> your Appcircle token.

CLAUDE DESKTOP — LOCAL STDIO · JSON

{
  "mcpServers": {
    "appcircle": {
      "command": "<YOUR_PATH_WHICH_APPCIRCLE_MCP>",
      "args": [],
      "env": {
        "APPCIRCLE_ACCESS_TOKEN": "<YOUR_APPCIRCLE_ACCESS_TOKEN>"
      }
    }
  }
}

Appcircle MCP Server

Four tools open their own description with SIDE EFFECT, which is the cheapest possible way to tell an agent which calls it should stop and ask about.

What it is

What you get

Requirements

Setup effort

Finding out why a build failed

Working out what is about to be built

Starting or stopping a run

Getting a version to the store

Checking a listing before it goes live

Reporting on how the pipeline is doing

47 tools

cancel_build

get_app_version_metadata

get_build_activity_log

get_build_configuration_details

get_build_history_report

get_build_insights_report

get_build_logs

get_build_profile_details

get_build_profile_workflows

get_build_profiles

get_build_queue_waiting_report

get_build_status

get_bundle_identifiers

get_certificates

get_commit_details

get_commits_by_branch

get_distribution_app_version_report

get_distribution_profile_details

get_distribution_profiles

get_distribution_sent_report

get_enterprise_app_store_app_usage_report

get_intune_metadata

get_keystores

get_last_commit

get_metadata_locales

get_provisioning_profiles

get_publish_activity_log

get_publish_details

get_publish_flows

get_publish_metadata_lock_status

get_publish_profile_details

get_publish_profiles

get_publish_resign_report

get_publish_status_report

get_publish_step_logs

get_signing_activity_log

get_signing_report

get_store_profile_details

get_store_profiles

get_testing_groups

get_variable_groups

get_workflow_detail

send_app_version_to_testers

start_publish

stop_publish

trigger_build

update_app_version_release_notes

What to know first

Tools you get

Requires

Heavy Standing cost

Connect your client

Server setup

Setup

Hosted endpoint

MCP Clients

Claude Desktop, Antigravity

Claude Code

Cursor

VS Code

Windsurf

Gemini CLI

Codex

GitHub Copilot

Claude Desktop — Local stdio

Same category

XcodeBuild MCP

`cancel_build`

`get_app_version_metadata`

`get_build_activity_log`

`get_build_configuration_details`

`get_build_history_report`

`get_build_insights_report`

`get_build_logs`

`get_build_profile_details`

`get_build_profile_workflows`

`get_build_profiles`

`get_build_queue_waiting_report`

`get_build_status`

`get_bundle_identifiers`

`get_certificates`

`get_commit_details`

`get_commits_by_branch`

`get_distribution_app_version_report`

`get_distribution_profile_details`

`get_distribution_profiles`

`get_distribution_sent_report`

`get_enterprise_app_store_app_usage_report`

`get_intune_metadata`

`get_keystores`

`get_last_commit`

`get_metadata_locales`

`get_provisioning_profiles`

`get_publish_activity_log`

`get_publish_details`

`get_publish_flows`

`get_publish_metadata_lock_status`

`get_publish_profile_details`

`get_publish_profiles`

`get_publish_resign_report`

`get_publish_status_report`

`get_publish_step_logs`

`get_signing_activity_log`

`get_signing_report`

`get_store_profile_details`

`get_store_profiles`

`get_testing_groups`

`get_variable_groups`

`get_workflow_detail`

`send_app_version_to_testers`

`start_publish`

`stop_publish`

`trigger_build`

`update_app_version_release_notes`