Skip to main content
AI agents, MCP, and App Store Connect Level: Intermediate 14 min read

Troubleshooting FlightDeck MCP Connection Errors: ECONNREFUSED and Port Conflicts

Diagnose and resolve connection failures between AI coding assistants (Cursor, Claude Code, Antigravity, Windsurf, Roo Code) and FlightDeck's local MCP server. Covers port conflicts, transport mismatches, and authentication.

Published: 2026-11-01 • Last Updated: 2026-11-01 • Author: Kip Lawrence
Key MCP Tools: apps_list

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:

TEXT
http://127.0.0.1:51122/mcp
Note

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:

  1. Daemon State: The FlightDeck desktop application is closed, or its MCP server toggle is turned off.
  2. 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 /sse instead of Streamable HTTP (/mcp).
  3. 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).
  4. 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:

  1. Desktop App Stopped: The macOS application is closed. The socket does not listen (ECONNREFUSED).
  2. MCP Server Disabled: FlightDeck Desktop is open, but the MCP Server toggle in Settings is switched off.
  3. Port Mismatch: The client configuration points to a different port than the active port displayed in FlightDeck Desktop.
  4. Port Occupied: A third-party local service or orphan process is bound to the target port.
  5. Unsupported Transport: The client is configured for stdio or legacy SSE rather than Streamable HTTP (/mcp).
  6. Endpoint Path Error: The client attempts to query /sse or root / instead of /mcp (returns HTTP 404 Not Found).
  7. HTTP 401 Unauthorized: Local password protection is enabled in FlightDeck, but the request lacks or provides an incorrect Authorization: Bearer <token> header.
  8. HTTP 403 Forbidden: The request Origin or Host header fails local DNS rebinding validation (non-loopback origin).
  9. MCP Initialize Failure: The client protocol version or handshake parameters fail negotiation.
  10. Tool Discovery Failure: The client connects, but tools/list fails or omits expected capabilities due to feature policy.
  11. Apple Credentials Invalid: The local MCP server is healthy, but Apple rejects the generated JWT (revoked key, clock skew, or malformed .p8).
  12. 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):

BASH
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.1 rather than localhost (some Node.js client runtimes resolve localhost to 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:

BASH
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"}'
Warning

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:

BASH
PORT=51122
# Identify the conflicting process PID and binary
lsof -i :${PORT}

You have two remediation paths:

  1. Terminate the Conflicting Process: If the occupying process is a stray development server, terminate it using its PID: ``bash kill -15 <PID> ``
  2. Assign a Custom Port in FlightDeck Desktop: - In FlightDeck Desktop, navigate to Settings > MCP Server. - Change the port field from 51122 to an unused unprivileged port (for example, 51123 or 51180). - 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:

  1. Verify Password Setting: Open FlightDeck Desktop. In the MCP Server settings panel, check whether Persistent MCP Password has a password configured.
  2. Copy the Active Setup Configuration: Click Copy Setup Prompt in Desktop Settings. This automatically generates a tailored configuration snippet matching your active password status.
  3. Inspect Client Headers: If password protection is enabled, verify that your client's configuration file supplies the token in the headers dictionary:
JSON
{
  "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 401 until 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:

BASH
# 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:

BASH
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:

JSON
{
  "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:

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 to flightdeck.
  • 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:

TEXT
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

  1. The assistant issues an apps_list query across the loopback MCP connection.
  2. FlightDeck retrieves the active .p8 private key from your encrypted macOS Keychain.
  3. FlightDeck signs a short-lived ES256 JWT in application memory and queries api.appstoreconnect.apple.com/v1/apps?limit=3.
  4. 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:

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

TEXT
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.

For client-specific setup instructions and governance workflows, see our companion guides:

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