Skip to main content
Building, signing, and binary uploads Level: Advanced 12 min read

Uploading macOS Applications (.pkg) to the Mac App Store via MCP

A comprehensive developer guide to packaging, sandboxing, and uploading macOS .pkg installer packages to the Mac App Store using FlightDeck MCP.

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

Overview: Packaging and Distributing macOS Apps to the App Store

Unlike iOS applications—which are always packaged as .ipa archives—macOS distribution involves multiple file formats and signing requirements depending on whether you distribute directly to users outside the App Store or submit to Apple's Mac App Store.

For the Mac App Store, Apple requires a signed installer package (.pkg) containing your sandboxed application bundle (.app), or an upload executed via Xcode Organizer. Direct directory bundles—such as raw .app folders or .xcarchive bundles—cannot be uploaded directly to App Store Connect ingestion APIs.

TEXT
┌────────────────────────────────────────────────────────────────────────┐
│                     LOCAL PACKAGING & SIGNING                          │
│                                                                        │
│   MyApp.app (Sandboxed) ──► Signed with "Apple Distribution"           │
│           │                                                            │
│           ▼                                                            │
│   [ productbuild --component ] ──► Signed with "Mac Installer Distr"   │
│           │                                                            │
│           ▼                                                            │
│       MyApp.pkg (Flat XAR Package)                                     │
└───────────┬────────────────────────────────────────────────────────────┘
            │
            ▼
┌────────────────────────────────────────────────────────────────────────┐
│                   FLIGHTDECK MCP WORKFLOW PIPELINE                     │
│                                                                        │
│   MyApp.pkg ──► [ build_upload_preview ]                               │
│                       │ (In-process XAR parsing & SHA-256 hash)        │
│                       ▼                                                │
│                 [ Approval Center Confirmation ]                       │
│                       │ (Human-in-the-loop review)                     │
│                       ▼                                                │
│                 [ build_upload_start ] ──► Apple Ingestion Pipeline    │
└────────────────────────────────────────────────────────────────────────┘

FlightDeck includes native support for inspecting and uploading macOS .pkg packages through its MCP tools (build_upload_preview and build_upload_start). This guide explains how to package and sandbox your macOS app correctly, how FlightDeck validates flat packages, and how to execute the upload using natural-language AI prompts.


1. Mac App Store Distribution Requirements

Before packaging a macOS application for App Store Connect, verify that your project complies with Apple's strict platform requirements:

1. Mandatory App Sandboxing

Every application submitted to the Mac App Store must have App Sandbox enabled. In your target's .entitlements file:

XML
<key>com.apple.security.app-sandbox</key>
<true/>

Without this entitlement, Apple's automated binary ingestion system will immediately reject the package with error ITMS-90236: Missing App Sandbox.

2. Dual Cryptographic Signatures

A macOS package requires two separate certificates from your Apple Developer account:

  • Application Binary Signature: The executable code inside MyApp.app must be signed with your Apple Distribution certificate (or legacy 3rd Party Mac Developer Application).
  • Installer Package Signature: The outer .pkg installer container must be signed with your Mac Installer Distribution certificate (or legacy 3rd Party Mac Developer Installer).

3. Build Versioning Constraints

  • CFBundleShortVersionString: The public marketing version (e.g., 1.2.0).
  • CFBundleVersion: The internal build number (e.g., 12). Must be strictly higher than any previously uploaded build for that marketing version.

2. Mac App Store Submission vs Developer ID Notarization

Developers frequently confuse Mac App Store submission with direct distribution outside the App Store. They use different tooling, certificates, and validation pipelines:

Feature Mac App Store Submission Developer ID Direct Distribution
Distribution Channel Mac App Store Direct download, DMG, website, or Sparkle updater
App Signature Apple Distribution / 3rd Party Mac Developer App Developer ID Application
Installer Signature Mac Installer Distribution Developer ID Installer
App Sandbox Mandatory Optional (Hardened Runtime required)
Notarization (notarytool) Not used (Apple ingests, reviews, and signs via FairPlay) Mandatory (must staple notarization ticket)
Upload Destination App Store Connect (buildUploads API / FlightDeck) Apple Notary Service (xcrun notarytool)
Warning

Do not attempt to notarize a Mac App Store build using xcrun notarytool. The notarization service only accepts binaries signed with Developer ID certificates and will reject packages signed with Mac App Store distribution certificates.


3. Creating the Signed .pkg Installer Package

To generate an uploadable .pkg from your compiled and sandboxed .app bundle, use Apple's productbuild utility:

Step 1: Sign Embedded Frameworks and the Inner Application Bundle

Code signing for macOS must proceed from the inside out: sign embedded dylibs, frameworks, and helper tools first, followed by the main application bundle:

BASH
# 1. Sign embedded frameworks and dynamic libraries
for framework in ./build/Release/MyApp.app/Contents/Frameworks/*.framework; do
  codesign --force --options runtime --timestamp \
    --sign "Apple Distribution: Acme Corporation (ABCDE12345)" \
    "$framework"
done

# 2. Sign embedded helper tools or XPC services with their entitlements
# (Repeat for each binary in Contents/MacOS/ or Contents/XPCServices/)

# 3. Sign the main application bundle with sandboxing entitlements
codesign --force --options runtime --timestamp \
  --sign "Apple Distribution: Acme Corporation (ABCDE12345)" \
  --entitlements MyApp.entitlements \
  ./build/Release/MyApp.app

Verify the signature:

BASH
codesign -dvvv ./build/Release/MyApp.app

Step 2: Package and Sign the Installer Package

Use Apple's productbuild --component utility to wrap the .app inside a signed flat installer package destined for /Applications:

BASH
productbuild \
  --component ./build/Release/MyApp.app /Applications \
  --sign "Mac Installer Distribution: Acme Corporation (ABCDE12345)" \
  ./build/MyApp.pkg
Tip

Complex Multi-Component Packages: For simple standalone applications, productbuild --component is the standard Apple command. For multi-bundle installations requiring custom pre-install scripts or distribution XML definition files, developers synthesize a distribution file with productbuild --synthesize and compile with productbuild --distribution. For standard Mac App Store submissions, --component produces the required flat XAR package format.

Step 3: Verify the Package Signature

Verify that the package was signed with the correct installer certificate:

BASH
pkgutil --check-signature ./build/MyApp.pkg

Expected output:

TEXT
Package "MyApp.pkg":
   Status: signed by a developer certificate issued by Apple for Mac App Store submission
   Certificate Chain:
    1. Mac Installer Distribution: Acme Corporation (ABCDE12345)
    2. Apple Worldwide Developer Relations Certification Authority
    3. Apple Root CA

4. How FlightDeck Validates macOS Packages

FlightDeck's build_upload_preview tool performs comprehensive local validation on .pkg files before any data is sent over the network.

Pure In-Process XAR Inspection

A modern macOS .pkg file is an XAR archive (eXtensible ARchive with magic header 0x78617221). FlightDeck's ArtifactInspector inspects .pkg files using a pure in-process parser without shelling out to external command-line binaries:

  1. Magic Header & Table of Contents: Reads the XAR header, decompresses the XML Table of Contents (TOC), and enforces memory limits to protect against malicious zip-bomb payloads.
  2. Metadata Extraction: Extracts CFBundleIdentifier, CFBundleShortVersionString, CFBundleVersion, and target platform (MAC_OS).
  3. Cryptographic Checksums: Streams the package file to compute SHA-256 and MD5 checksums.
  4. App Store Connect Matching: Compares the extracted CFBundleIdentifier against the selected application record in App Store Connect to prevent uploading the wrong binary.

Rejection of Raw Directory Bundles

If a developer accidentally attempts to upload a .app or .xcarchive directory bundle directly, FlightDeck detects the directory package and throws an informative error:

TEXT
UnsupportedArtifactException: The .app directory bundle exists at ".../MyApp.app",
but .app directory bundles cannot be uploaded directly to App Store Connect.
A Mac App Store upload requires an appropriate packaged artifact (.pkg).
FlightDeck does not perform App Store distribution signing or packaging.
Please package and sign your application using Xcode or productbuild prior to upload.
Note

Implementation Evidence & Verification Boundaries: FlightDeck's in-process .pkg parser and upload streaming pipeline are fully implemented and validated in the application repository. In testing environments without a live Apple Developer account or enrolled macOS app record, local preview inspection (build_upload_preview) is verified offline (Level 3 evidence), while live binary ingestion on Apple's Mac App Store servers (Level 4 evidence) requires production App Store Connect credentials.


5. Executing the Upload Workflow via AI Prompts

With your .pkg file prepared, you can orchestrate the preview and upload through natural-language prompts.

Step 1: Pre-Upload Inspection Prompt

MARKDOWN
Inspect the macOS installer package at ./build/MyApp.pkg for my Mac App Store app "Quest Desktop". Verify the bundle identifier, version, and build number before initiating an upload.

What the AI Assistant Does:

  • Invokes FlightDeck's build_upload_preview tool with the path to the .pkg and the target app ID.
  • Displays the verified package properties:
  • File: MyApp.pkg
  • Platform: MAC_OS
  • Bundle ID: com.mycompany.questdesktop
  • Version: 2.1.0 (Build 45)
  • SHA-256 Checksum: 7f83b...d29a
  • Status: Ready for upload.

Step 2: Upload Execution Prompt

MARKDOWN
Upload ./build/MyApp.pkg to App Store Connect for app "Quest Desktop". Explain what operations will be executed and stage the mutation for my approval.

What the AI Assistant & FlightDeck Do:

  1. Under FlightDeck's Approval Center ON mode, the AI assistant invokes build_upload_start.
  2. FlightDeck stages the mutation and displays a human-in-the-loop confirmation card on your desktop showing the target app, package name, file size, and calculated SHA-256 hash.
  3. Once you click Approve, FlightDeck: - Creates a buildUploads container on Apple's App Store Connect API (POST /v1/buildUploads). - Registers the .pkg asset (POST /v1/buildUploadFiles). - Streams the binary chunks directly to Apple's presigned storage endpoint. - Finalizes the asset registration with the verified MD5 checksum (PATCH /v1/buildUploadFiles/{id}). - Polls until Apple registers the upload and begins ingestion processing.

6. Verifying Ingestion Processing

Once the upload transfer completes, Apple's backend processes the package. You can verify processing status with a follow-up prompt:

MARKDOWN
Check the processing status of the newly uploaded build for "Quest Desktop". Let me know once the build state is VALID and ready for TestFlight or release.

What FlightDeck Does:

  • Calls builds_list or build_get to monitor Apple's server-side ingestion pipeline.
  • Reports when Apple transitions the build state from PROCESSING to VALID.

For complete details on processing states and diagnostics, see Checking Build Processing State.


7. Troubleshooting Common macOS Upload Errors

1. ITMS-90236: Missing App Sandbox

  • Cause: The application was built without the com.apple.security.app-sandbox entitlement.
  • Fix: Add <key>com.apple.security.app-sandbox</key><true/> to your macOS entitlements file, recompile, re-package with productbuild, and re-upload.

2. ITMS-90242: Invalid Code Signing (Installer Package)

  • Cause: The .pkg package was signed with an application certificate instead of a Mac Installer certificate, or was created without a signature.
  • Fix: Ensure you pass --sign "Mac Installer Distribution: ..." when running productbuild. Check with pkgutil --check-signature MyApp.pkg.

3. UnsupportedArtifactException in FlightDeck

  • Cause: A path to MyApp.app or MyApp.xcarchive was provided instead of MyApp.pkg.
  • Fix: Wrap the application bundle into a flat .pkg using productbuild before previewing or uploading with FlightDeck.

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