Fix a Local MCP Connection Refused Error

MaskPilot MCP listens on 127.0.0.1:38427 on the current computer by default, but an existing configuration may use another port. Always use the local connection address shown on the MCP page in the client. A connection refused message usually means the caller did not reach that local listener. An incorrect access token produces an unauthorized response instead, so diagnose these cases separately.

Step 1: Check whether the local service exists

Copy the actual connection address from the MaskPilot MCP page, temporarily replace the final /mcp with /health, and open it on the same computer. The default address is:

http://127.0.0.1:38427/health

A healthy response includes ok: true and the service name. If the health check is unavailable, confirm that:

1. The MaskPilot client is running.
2. MCP is enabled in settings.
3. Enabling MCP did not report that the port was already in use.
4. The health check uses the port currently shown by the client instead of assuming the default port.
5. Local security software is not preventing MaskPilot from listening on the loopback address.

The health check proves only that the local service is running. It does not prove that the client is signed in or that the current account can call tools.

Step 2: Confirm where the caller runs

Copy the complete MCP endpoint shown in the client. Its default value is:

http://127.0.0.1:38427/mcp

The caller should run on the same computer in an environment that can reach the Windows loopback network. Inside WSL, a container, a remote development host, or a strict network sandbox, 127.0.0.1 may refer to that environment instead of MaskPilot on Windows.

Do not replace the address with a LAN IP or forward the local port to the public internet. MaskPilot local MCP does not listen on 0.0.0.0 and is not a remote service.

Step 3: Interpret the HTTP result

• Connection refused: No reachable service is listening on the local port. Check the client, MCP setting, and caller environment first.
• 404: The request path is wrong. Confirm that it ends in /mcp.
• 401: The service is reachable, but the Bearer Token is missing or does not match. Opening /mcp in a browser address bar sends GET without the token, so it also receives 401 first and is not a valid MCP call test. Continue with the invalid token checklist.
• 405: A request with the correct Bearer Token used a method other than POST.
• JSON-RPC error: HTTP is connected. In addition to the method, arguments, and account permission, check whether the caller and server support the same MCP protocol version.

Step 4: Reload the caller configuration

If the health check works but the AI tool still appears offline:

1. Verify that the configured URL is complete and has no extra spaces.
2. Confirm that the Bearer Token environment variable name matches the configuration.
3. After setting or resetting the token, fully quit and reopen the AI tool or its terminal.
4. Inspect the caller’s MCP log to see the host, port, and path it actually requested.
5. Check recent calls in MaskPilot. No record usually means the request did not arrive or did not reach the tool-call stage.

For Codex, regenerate the configuration by following the local MCP connection guide. Do not place the access token directly in a configuration file that may be committed, and do not expose it in screenshots or logs.

Step 5: Check protocol version compatibility

The current MaskPilot client declares MCP 2025-06-18 and uses an initialize-based connection flow. The caller must support that version or provide a compatible fallback from the modern MCP flow to legacy initialization.

If the health check works but the log contains server/discover, Unsupported protocol version, method not found, or error code -32601, the caller may be attempting only the modern protocol. This is different from a port or token failure. In that case:

1. Check whether the caller still supports 2025-06-18 or a legacy initialization fallback.
2. Update MaskPilot and the caller to mutually compatible releases.
3. Do not fabricate protocol headers or rewrite requests to bypass negotiation.
4. If it still fails, record both versions, the original error, and the caller log before contacting support.

The official MCP version compatibility matrix distinguishes the modern per-request protocol from the legacy initialization flow. Only a dual-era caller can fall back automatically to a legacy server.

Connected, but tools still fail

After the connection is established, tool calls still require the MaskPilot client to remain signed in and are limited by the current account and member permissions. Keep the original error message and review AI permissions and tokens instead of treating a permission denial as a network failure.