Overview: Organizing TestFlight Cohorts with MCP
TestFlight organizes pre-release testing into Beta Groups. Rather than distributing builds to an unorganized collection of individual email addresses, Apple requires you to partition testers into structured cohorts with defined permissions, build access rules, and public link configurations.
Using FlightDeck's Model Context Protocol (MCP) server, your AI coding assistant (Cursor, Claude Code, Antigravity, or Windsurf) can query existing cohorts, create new internal or external testing groups, attach eligible builds, and prune obsolete groups without manually navigating the App Store Connect web portal.
This guide explains how TestFlight beta groups work, how to execute group operations using natural-language AI prompts, and how FlightDeck's Desktop Approval Center safeguards your production developer account from accidental mutations.
1. TestFlight Group Architecture: Internal vs. External Cohorts
Apple enforces strict structural differences between Internal and External beta groups. Because group type is permanently fixed at creation, choosing the correct cohort architecture upfront is essential:
+-----------------------------------------------------------------------------------+
| TESTFLIGHT COHORT ARCHITECTURE |
+-----------------------------------------------------------------------------------+
| |
| +------------------+ |
| | Target App | |
| +--------+---------+ |
| | |
| +-------------------+-------------------+ |
| | | |
| +--------v---------+ +--------v---------+ |
| | Internal Group | | External Group | |
| | (Max 100 testers)| |(Max 10,000 tester| |
| +--------+---------+ +--------+---------+ |
| | | |
| +---------+---------+ +---------+---------+ |
| | | | | | |
| +----v-----+ +-----v----+ +----v----+ +--v----+ +--v-------+ |
| |Build (no | |Team Users| | Build | | Email | | Public | |
| | review) | | (Devs) | |(Review) | |Testers| | Link | |
| +----------+ +----------+ +---------+ +-------+ +----------+ |
+-----------------------------------------------------------------------------------+
| Dimension | Internal Beta Groups (isInternalGroup: true) | External Beta Groups (isInternalGroup: false) |
|---|---|---|
| Tester Eligibility | Must belong to your Apple Developer team (Account Holder, Admin, App Manager, Developer, or Marketing roles in Users and Access). | Anyone with a valid email address or via an open public TestFlight invitation link. |
| Tester Capacity | Up to 100 testers per Apple Developer organization across all apps. | Up to 10,000 testers per application across all external groups. |
| Beta App Review | None required. Builds become available once ingestion processing reaches VALID, export compliance is cleared, and Apple edge distribution propagates. | Mandatory for the first build of every new marketing version (e.g. 1.0.0 vs 1.1.0). Subsequent builds for the same version typically do not trigger re-review unless significant changes are flagged. |
| Public Links | Unsupported. Apple rejects public links on internal cohorts with HTTP 400 Bad Request. | Supported. Generates a public testflight.apple.com/join/... URL with customizable capacity limits (1 to 10,000). |
| Build Access Default | hasAccessToAllBuilds: true allows internal testers to receive newly uploaded builds automatically upon processing completion. | Typically set to hasAccessToAllBuilds: false so external users receive only vetted release candidates. |
Note on Type Immutability: Apple does not allow converting an internal group into an external group (or vice versa) after creation. If a group was configured with the wrong cohort type, you must create a new group and delete the obsolete one.
2. FlightDeck MCP Group Capabilities & Safety Invariants
FlightDeck provides high-level semantic tools for group lifecycle management alongside granular safety controls:
beta_groups_list: High-level read tool that lists all beta groups for an application ID, returning group names, IDs, cohort flags (isInternalGroup), public link status, and build counts.beta_group_create: High-level mutating tool that creates a new beta group. Supports setting group name, internal/external status, public link enablement, and public link limits.beta_group_delete: High-level compensating cleanup tool that permanently deletes a beta group container.build_add_to_beta_group: Attaches an eligible pre-release build to a specific beta group.build_remove_from_beta_group: Disassociates an active build from a beta group, revoking tester access to that build.
Human Governance in the Approval Center
In FlightDeck, any mutating operation (POST, PATCH, DELETE) is protected by AI Approval: ON by default. When an assistant calls beta_group_create, beta_group_delete, or build_add_to_beta_group, FlightDeck stages the request as an immutable proposal card.
The tool returns status: "HUMAN_APPROVAL_REQUIRED", a stagingId, and a cryptographic continuationSecret. The assistant pauses and prompts you to review the target app, group name, and blast radius in the FlightDeck Desktop Approval Center before changes are executed against Apple's live API.
3. Step-by-Step Prompt Workflows
3.1 Inspecting Existing TestFlight Groups
Before creating new cohorts or attaching builds, always instruct your AI assistant to perform a non-destructive read of your existing groups.
Using FlightDeck, show me all TestFlight beta groups configured for [App Name]. Detail which groups are internal versus external, what builds are currently assigned, whether public links are enabled, and how many testers are enrolled. Do not stage or execute any changes. What the Assistant Does:
- Calls
apps_listto resolve your project's numericappId. - Calls
beta_groups_list(appId: "<appId>"). - Calls
builds_list(appId: "<appId>")to cross-reference active builds. - Outputs a structured inventory table summarizing group IDs, cohort types, and assigned versions.
3.2 Creating an Internal Beta Group for Engineering & QA
Internal groups give core engineers and internal QA testers direct over-the-air access to builds without waiting for Beta App Review, once automated ingestion processing completes, export compliance is attested, and builds are assigned.
Help me create an internal TestFlight group called "Engineering Alpha" for [App Name]. Check whether a group with this name already exists. Ensure internal cohort settings are configured and automatic build access is enabled. Show me the exact parameters before staging the mutation for my approval. Execution Flow:
- Verification: The assistant verifies that "Engineering Alpha" does not already exist in
beta_groups_list. - Staging: The assistant stages
beta_group_createwithisInternalGroup: trueandhasAccessToAllBuilds: true. - Approval Center Notification: FlightDeck emits
HUMAN_APPROVAL_REQUIRED. Your assistant prompts: > "I have staged the creation of internal beta group 'Engineering Alpha'. Please authorize this proposal in the FlightDeck Desktop Approval Center." - Execution & Readback: Upon your click in the Desktop UI, the mutation executes, and the assistant calls
beta_groups_listto verify that Apple returned a validgroupId.
3.3 Creating an External Beta Group with Public Link Capacity
External groups allow inviting outside testers via email or through an open public link, subject to Apple's Beta App Review rules.
Create an external TestFlight group called "Community Beta" for [App Name]. Enable a public signup link with a maximum capacity limit of 500 testers. Do not grant access to all builds automatically. Stage the proposal and explain the approval requirements. Execution Flow:
- The assistant stages
beta_group_createwithisInternalGroup: false,publicLinkEnabled: true, andpublicLinkLimit: 500. - You approve the proposal in FlightDeck Desktop.
- The assistant executes the continuation and reads back the new group details, including the generated Apple
publicLinkURL (https://testflight.apple.com/join/...).
3.4 Associating a Build with a Beta Group
Attaching a build to a group is a distinct mutation. Because Apple generates group IDs dynamically during creation, build association must always be staged after the group ID exists.
Check recent builds for [App Name] using FlightDeck. Verify that the latest build has completed Apple processing and that export compliance is cleared. Once verified, associate that build with our "Community Beta" group. Show me the build details and stage the association for my approval. Verification Checklist Before Associating:
- Processing State: Must be
processingState == "VALID". If it isPROCESSING, Apple backend ingestion is still active. - Export Compliance: Must be attested via
ITSAppUsesNonExemptEncryptionor manual declaration. - External Review Gate: If associating with an external group, the assistant verifies whether Beta App Review is required (
build_beta_details_get). If it is the first build for this version, external testers cannot download the build until Apple approves the beta review submission.
The assistant stages build_add_to_beta_group for your approval in FlightDeck Desktop.
3.5 Safely Deleting an Obsolete Beta Group
When a testing cycle finishes, you can prune the group without harming testers enrolled elsewhere in your account.
Safety Invariant — Blast Radius of Group Deletion: Calling beta_group_delete unlinks assigned builds and disables the group's public link. It does not delete testers from your App Store Connect account or remove them from other active beta groups.
Check the details for group "Legacy QA" under [App Name]. Confirm how many testers belong to it and whether any builds are attached. If this group is obsolete, stage its deletion for my review in FlightDeck. The assistant verifies group attributes and stages beta_group_delete for your explicit confirmation.
4. Multi-Step Orchestration and Non-Atomic Safety
Apple's App Store Connect REST API does not provide atomic multi-entity transactions. Creating a group, adding testers, and attaching a build are three independent operations.
FlightDeck enforces a sequential approval protocol:
- Phase 1 (Create Group): Stage
beta_group_create$\rightarrow$ Human approves in Desktop UI $\rightarrow$ Execute $\rightarrow$ Capture verifiedgroupId. - Phase 2 (Assign Build): Using the verified
groupId, stagebuild_add_to_beta_group$\rightarrow$ Human approves $\rightarrow$ Execute $\rightarrow$ Verify build status. - Phase 3 (Enroll Testers): Stage tester additions using the verified
groupId$\rightarrow$ Human approves $\rightarrow$ Execute $\rightarrow$ Read back membership.
Partial-Failure Recovery
If an intermediate step fails (for example, if group creation succeeds but build attachment fails because Beta App Review prerequisites were unmet):
- No Phantom Rollback: FlightDeck never silently deletes newly created groups.
- Diagnostic Readout: The assistant reports exactly which operation succeeded and provides actionable recovery options: resolve the prerequisite and retry
build_add_to_beta_group, select a different eligible build, or explicitly stagebeta_group_deleteto discard the empty group.
5. Summary of Best Practices
- Isolate Internal Developers: Use internal groups (
isInternalGroup: true) withhasAccessToAllBuilds: truefor your engineering team to test builds without waiting for Beta App Review. - Cap Public Links: When enabling public links on external groups, always configure
publicLinkLimit(e.g. 200 or 500) to prevent uncontrolled quota exhaustion. - Verify Before Mutating: Run
beta_groups_listandbuilds_listprior to requesting additions to eliminate naming collisions and duplicate API calls. - Inspect in Approval Center: Always check the proposal card in the FlightDeck Desktop Approval Center to verify the target group name, application ID, and cohort classification before confirming execution.