Skip to main content
TestFlight setup and beta distribution Level: Intermediate 12 min read

Managing TestFlight Internal and External Beta Groups via MCP

A complete developer guide to creating, organizing, and managing TestFlight beta testing groups using FlightDeck MCP. Learn how to configure internal vs external cohorts, attach builds, set public links, and safely delete obsolete groups.

Published: 2026-11-02 • Last Updated: 2026-11-02 • Author: Kip Lawrence
Key MCP Tools: beta_groups_listbeta_group_createbeta_group_deletebuilds_listbuild_beta_details_getbuild_add_to_beta_groupbuild_remove_from_beta_group

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:

TEXT
+-----------------------------------------------------------------------------------+
|                           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:

  1. Calls apps_list to resolve your project's numeric appId.
  2. Calls beta_groups_list(appId: "<appId>").
  3. Calls builds_list(appId: "<appId>") to cross-reference active builds.
  4. 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:

  1. Verification: The assistant verifies that "Engineering Alpha" does not already exist in beta_groups_list.
  2. Staging: The assistant stages beta_group_create with isInternalGroup: true and hasAccessToAllBuilds: true.
  3. 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."
  4. Execution & Readback: Upon your click in the Desktop UI, the mutation executes, and the assistant calls beta_groups_list to verify that Apple returned a valid groupId.

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:

  1. The assistant stages beta_group_create with isInternalGroup: false, publicLinkEnabled: true, and publicLinkLimit: 500.
  2. You approve the proposal in FlightDeck Desktop.
  3. The assistant executes the continuation and reads back the new group details, including the generated Apple publicLink URL (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 is PROCESSING, Apple backend ingestion is still active.
  • Export Compliance: Must be attested via ITSAppUsesNonExemptEncryption or 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:

  1. Phase 1 (Create Group): Stage beta_group_create $\rightarrow$ Human approves in Desktop UI $\rightarrow$ Execute $\rightarrow$ Capture verified groupId.
  2. Phase 2 (Assign Build): Using the verified groupId, stage build_add_to_beta_group $\rightarrow$ Human approves $\rightarrow$ Execute $\rightarrow$ Verify build status.
  3. 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 stage beta_group_delete to discard the empty group.

5. Summary of Best Practices

  1. Isolate Internal Developers: Use internal groups (isInternalGroup: true) with hasAccessToAllBuilds: true for your engineering team to test builds without waiting for Beta App Review.
  2. Cap Public Links: When enabling public links on external groups, always configure publicLinkLimit (e.g. 200 or 500) to prevent uncontrolled quota exhaustion.
  3. Verify Before Mutating: Run beta_groups_list and builds_list prior to requesting additions to eliminate naming collisions and duplicate API calls.
  4. 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.

Connect Your AI Agent to App Store Connect

FlightDeck runs locally on your Mac, keeping private keys secure in your macOS Keychain and executing mutations only after your explicit approval.

Download FlightDeck on Mac App Store