Overview: Resolving MCP Connection Failures
When pairing an AI coding assistant with FlightDeck, your assistant communicates with a local Model Context Protocol (MCP) server running on your Mac. The server exposes App Store Connect tools through a standard Streamable HTTP endpoint, binding by default to:
http://127.0.0.1:51122/mcp
Default Port Notice: Port 51122 is the shipping default port for FlightDeck macOS. FlightDeck supports custom ports (1024â65535). If you configured a custom port in FlightDeck Settings, always verify your active port in the running desktop app.
If your assistant reports ECONNREFUSED, hangs during tool discovery, returns HTTP 401 Unauthorized, or fails to see your App Store Connect applications, the breakdown usually stems from one of four layers:
- Daemon State: The FlightDeck desktop application is closed, or its MCP server toggle is turned off.
- Network Transport & Port Binding: Another application occupies the configured port (default
51122), the client was configured with a legacy or mismatched port, or the assistant attempted to use legacy Server-Sent Events (SSE) or request/sseinstead of Streamable HTTP (/mcp). - Local Authentication: Password protection is enabled in FlightDeck Desktop (Settings > MCP Server > Persistent MCP Password), but the client configuration lacks an active HTTP Bearer token or carries a stale token from a previous configuration. (Note: On fresh installations, local loopback authentication is disabled by default).
- Apple API Authorization: FlightDeck's MCP server is connected, but the active Apple API key has expired, been revoked, or lacks permission to view applications.
This guide provides a systematic, symptom-driven protocol to identify the failing layer, test local transport, and restore full communication.
The 12 Distinct Connection and Operation Failure States
When troubleshooting FlightDeck MCP, determine which of the twelve failure states matches your system before changing configuration files:
- Desktop App Stopped: The macOS application is closed. The socket does not listen (
ECONNREFUSED). - MCP Server Disabled: FlightDeck Desktop is open, but the MCP Server toggle in Settings is switched off.
- Port Mismatch: The client configuration points to a different port than the active port displayed in FlightDeck Desktop.
- Port Occupied: A third-party local service or orphan process is bound to the target port.
- Unsupported Transport: The client is configured for
stdioor legacy SSE rather than Streamable HTTP (/mcp). - Endpoint Path Error: The client attempts to query
/sseor root/instead of/mcp(returnsHTTP 404 Not Found). - HTTP 401 Unauthorized: Local password protection is enabled in FlightDeck, but the request lacks or provides an incorrect
Authorization: Bearer <token>header. - HTTP 403 Forbidden: The request Origin or Host header fails local DNS rebinding validation (non-loopback origin).
- MCP Initialize Failure: The client protocol version or handshake parameters fail negotiation.
- Tool Discovery Failure: The client connects, but
tools/listfails or omits expected capabilities due to feature policy. - Apple Credentials Invalid: The local MCP server is healthy, but Apple rejects the generated JWT (revoked key, clock skew, or malformed
.p8). - Apple Account Permissions Insufficient / No Apps Returned: The credentials are valid, but the API key role (e.g. Developer or Marketing) lacks permission to access apps or metadata, returning zero apps.
Prerequisites and System Requirements
Before troubleshooting, verify the following local requirements:
- macOS System: macOS 12.0 (Monterey) or later running on Apple Silicon or Intel.
- FlightDeck Desktop: Installed and operational from the Mac App Store.
- Local Terminal: Access to macOS Terminal or your IDE's integrated shell to run standard network inspection commands (
lsof,curl). - AI Coding Assistant: One of the supported MCP clients:
- Cursor (
~/.cursor/mcp.json) - Claude Code CLI (
claude mcp add) - Google Antigravity IDE (
~/.gemini/config/mcp_config.json) - Codeium Windsurf (
~/.codeium/windsurf/mcp_config.json) - Roo Code / Cline (
cline_mcp_settings.json)
Step-by-Step Diagnostic Protocol
Follow these diagnostic steps in sequence. Match your observed symptom to the corresponding check below.
Step 1: Diagnose Transport Failures (ECONNREFUSED or Connection Refused)
An ECONNREFUSED error indicates that no process is listening on the configured loopback address and port.
1. Check If the Server Process Is Listening
Open Terminal and run lsof against your configured port (substitute your custom port if changed from the default 51122):
PORT=51122
lsof -nP -iTCP:${PORT} -sTCP:LISTEN
- If the command returns nothing: The FlightDeck MCP server is not running. Launch FlightDeck Desktop, open Settings > MCP Server, and click Start Server. Ensure the status indicator turns green (Running).
- If the command returns a non-FlightDeck process (e.g., node, docker): Another process has claimed the port. Proceed to Step 2 to resolve the port conflict.
- If the command returns FlightDeck: The socket is listening. Verify that your assistant is targeting
127.0.0.1rather thanlocalhost(some Node.js client runtimes resolvelocalhostto IPv6::1, which will fail if the server binds exclusively to IPv4 loopback).
2. Test Basic HTTP Socket Reachability
Run a simple HTTP POST probe with curl targeting the /mcp route:
PORT=51122
curl -i -X POST http://127.0.0.1:${PORT}/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"ping"}'
Understanding Socket Checks vs. End-to-End Health: A successful HTTP response from curl (e.g. HTTP 200 OK or HTTP 401 Unauthorized) confirms only that the loopback TCP socket and Streamable HTTP middleware are responding. It does not prove that tool discovery succeeded, that client JSON-RPC capabilities were negotiated, or that Apple API credentials are valid. Always perform an end-to-end read-only query using your AI assistant.
Browser URL Limitations: Do not attempt to test MCP connection health by opening http://127.0.0.1:51122/mcp in Safari or Chrome. Web browsers issue GET requests without session context, which returns HTTP 405 Method Not Allowed. Furthermore, querying /sse returns HTTP 404 Not Found because FlightDeck uses the modern Streamable HTTP /mcp specification.
Step 2: Resolve Local Port Conflicts
If port 51122 is occupied by another development server or background container:
PORT=51122
# Identify the conflicting process PID and binary
lsof -i :${PORT}
You have two remediation paths:
- Terminate the Conflicting Process: If the occupying process is a stray development server, terminate it using its PID: ``
bash kill -15 <PID>`` - Assign a Custom Port in FlightDeck Desktop: - In FlightDeck Desktop, navigate to Settings > MCP Server. - Change the port field from
51122to an unused unprivileged port (for example,51123or51180). - Click Restart Server. - Update your client's configuration file to match the new port: ``text http://127.0.0.1:51123/mcp``
Step 3: Resolve HTTP 401 Unauthorized Errors
By default on local loopback, FlightDeck does not require authentication. However, when password protection is enabled in FlightDeck Desktop (Settings > MCP Server > Persistent MCP Password), the server enforces local HTTP Bearer token authentication on all inbound requests. The token is stored securely in your macOS Keychain under reference asc:mcp:http_password.
If your assistant reports HTTP 401 Unauthorized or fails during handshake:
- Verify Password Setting: Open FlightDeck Desktop. In the MCP Server settings panel, check whether Persistent MCP Password has a password configured.
- Copy the Active Setup Configuration: Click Copy Setup Prompt in Desktop Settings. This automatically generates a tailored configuration snippet matching your active password status.
- Inspect Client Headers: If password protection is enabled, verify that your client's configuration file supplies the token in the
headersdictionary:
{
"mcpServers": {
"flightdeck": {
"url": "http://127.0.0.1:51122/mcp",
"headers": {
"Authorization": "Bearer YOUR_COPIED_TOKEN"
}
}
}
}
[!CAUTION] Token Hygiene and Shared Logs: When sharing terminal logs or filing bug reports, never include active Bearer tokens or Apple API keys. FlightDeck's tokens protect access to your local developer tooling. If you accidentally disclose a token, click Clear Password or enter a new persistent password in FlightDeck Desktop Settings immediately. Old tokens are rejected instantly with
HTTP 401 Unauthorized.
[!CAUTION] Token Hygiene: FlightDeck regenerates its session Bearer token whenever you click Regenerate Token in Desktop Settings. If you regenerated the token, previously configured assistants will immediately receive
HTTP 401until updated. Never commit files containing active tokens to public Git repositories.
Step 4: Correct Client Transport and Protocol Mismatches
Different AI coding tools support different MCP transport protocols. Configuring the wrong transport format causes silent connection drops or protocol errors.
Claude Code CLI: Explicit Transport Flag Required
Claude Code defaults to stdio transport unless explicitly instructed to use HTTP. When adding FlightDeck via the CLI, always provide --transport http:
# Correct registration command
claude mcp add --transport http flightdeck http://127.0.0.1:51122/mcp
# If password protection is enabled, append the auth header:
claude mcp add --transport http flightdeck http://127.0.0.1:51122/mcp --header "Authorization: Bearer YOUR_COPIED_TOKEN"
To verify Claude Code's registration:
claude mcp list
Roo Code / Cline: Streamable HTTP vs Legacy SSE
FlightDeck does not implement legacy Server-Sent Events (GET /sse). If you select sse in Roo Code's settings, connection attempts return HTTP 405 Method Not Allowed.
In cline_mcp_settings.json, ensure "type": "streamable-http" is explicitly configured:
{
"mcpServers": {
"flightdeck": {
"type": "streamable-http",
"url": "http://127.0.0.1:51122/mcp"
}
}
}
Codeium Windsurf: serverUrl Property Name
Codeium Windsurf expects the configuration key serverUrl rather than url in ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"flightdeck": {
"serverUrl": "http://127.0.0.1:51122/mcp"
}
}
}
Step 5: Reload Client Configuration
Many IDEs do not hot-reload MCP configuration files when they are modified on disk.
- Cursor: Press
Cmd + Shift + P, execute Developer: Reload Window, then navigate to Cursor Settings > Features > MCP to verify that the green status indicator appears next toflightdeck. - Windsurf: Press
Cmd + Shift + P, execute Windsurf: Reload Window, and verify tool detection in the Cascade panel. - Claude Code CLI: Exit the active terminal session (
/exit) and launch a fresh session (claude).
Diagnostic Prompts for AI Coding Assistants
Once transport and authentication checks pass, use your AI coding assistant to verify end-to-end operational health without altering any Apple data.
Diagnostic Prompt 1: Connection Health Check
Paste this natural-language prompt into your assistant's chat window:
Using FlightDeck, check our connection status to App Store Connect. Tell me which account profile is active, verify that tools are discovered, and show me the first 3 apps in the account. Do not make any changes or stage any mutations.
What FlightDeck Executes Behind the Scenes
- The assistant issues an
apps_listquery across the loopback MCP connection. - FlightDeck retrieves the active
.p8private key from your encrypted macOS Keychain. - FlightDeck signs a short-lived ES256 JWT in application memory and queries
api.appstoreconnect.apple.com/v1/apps?limit=3. - The assistant reports the active profile and returns the list of accessible apps.
Diagnostic Prompt 2: Outcome-Based Automated Recovery Prompt
If your assistant reports that FlightDeck tools are missing or disconnected, paste this outcome-driven instruction to let your assistant inspect its client configuration:
Inspect our active MCP configuration for FlightDeck in this development environment. Verify that the server URL points to http://127.0.0.1:51122/mcp (or our custom port) using Streamable HTTP. If headers are required, verify the Authorization format. Check whether tool discovery succeeds and report the exact connection error if it fails.
Diagnostic Prompt 3: Read-Only Smoke-Test Prompt
After applying any connection fixes or restarting FlightDeck, execute this lightweight read-only smoke test to verify full protocol and Apple API health:
Perform a read-only smoke test of FlightDeck MCP: list our registered apps, check the latest build processing state for our primary app, and confirm that no mutations are staged in the Approval Center.
Troubleshooting Decision Matrix
Use this quick-reference table to match observed symptoms to immediate solutions:
| Observed Symptom | Underlying Root Cause | Verification Command or Check | Remediation Action |
|---|---|---|---|
ECONNREFUSED on port 51122 |
FlightDeck app closed or server stopped. | lsof -iTCP:51122 -sTCP:LISTEN returns empty. |
Open FlightDeck, navigate to Settings > MCP Server, click Start Server. |
Address already in use |
Another process is bound to port 51122. | lsof -i :51122 reveals non-FlightDeck PID. |
Kill conflicting PID or configure custom port (e.g. 51123) in FlightDeck Settings. |
HTTP 401 Unauthorized |
Missing or stale Bearer token in headers. | Check FlightDeck Settings > MCP Server > Require Password. | Copy active token from Desktop; update "Authorization": "Bearer ..." in client config. |
HTTP 405 Method Not Allowed |
Client attempted GET /sse or browser test. |
Review client log for SSE request. | Set "type": "streamable-http" in client settings; avoid browser URL tests. |
| Claude Code tools not detected | CLI was registered without --transport http. |
Run claude mcp list. |
Re-add with: claude mcp add --transport http flightdeck http://127.0.0.1:51122/mcp. |
Handshake succeeds, but apps_list returns 401 |
Apple API key revoked or clock skew on Mac. | Check Date & Time settings in macOS System Settings. | Verify API key is active in Apple portal; ensure macOS clock synchronization is enabled. |
Handshake succeeds, but apps_list returns 0 apps |
API key lacks permission or wrong team profile active. | Inspect Connection Profile in FlightDeck Desktop. | Verify API key role in Apple portal (Admin or App Manager); switch to correct team profile. |
Related Guides and Client Setup Tutorials
For client-specific setup instructions and governance workflows, see our companion guides:
- Connecting Cursor to App Store Connect via FlightDeck MCP â Complete Cursor IDE configuration.
- Connecting Claude Code CLI to FlightDeck MCP â Terminal setup for Claude Code.
- Connecting Google Antigravity, Windsurf & Roo Code to FlightDeck â Multi-client recipes and syntax.
- Human-in-the-Loop Governance & FlightDeck Approval Center â Understanding visual diff cards and safe write execution.