MCP server disconnected on macOS: a practical checklist
Find the failing boundary before reinstalling anything. A local MCP connection can fail when the client launches the executable, starts the agent, negotiates the protocol or calls a particular tool. “Disconnected” alone does not identify which step failed. The checks below separate those cases using Ganado Bridge’s local preview as a worked example.
By Ganado · Published 20 September 2026 · Bridge examples target 0.1.0-preview.2. This is a diagnostic workflow, not a claim that every MCP failure has the same cause.
Start with the earliest observable failure
| What you see | What to check next |
|---|---|
The process never starts; the log reports ENOENT. | Confirm the executable and script paths. This is not yet evidence of an MCP protocol failure. |
| The process exits immediately with a configuration message. | Read that exact message. Verify the runtime, required setting and extracted files before changing permissions. |
| Tools appear, but one file action fails. | Inspect the path, file state, OS access and expected hash. The connection may already work. |
| A command starts, then the assistant loses track of it. | Read the returned process session. Do not run a mutating command again merely to recover its output. |
The distinction matters. Reauthorizing a transport will not fix a stale file hash. Updating a JSON path will not restore a process session that was lost when its agent restarted. Work from the first concrete error, not the last generic message shown by the client.
1. Confirm the executable actually used
From the folder containing the extracted Bridge build, run:
node --version
node -p 'process.execPath'
node bin/bridge.mjs doctor
node bin/bridge.mjs configThe second command reports the absolute Node executable path. Compare it with the client entry rather than assuming the client sees the same shell setup. A version manager upgrade or moving the extracted folder can make a previously valid path stale. The path property is defined in the Node.js documentation.
For this Bridge version, use Node 22.22+ within 22.x or Node 24.x. “Newer Node” is not automatically inside the supported range. The release instructions specify the runtime and bundled dependencies.
Keep each argument as a separate JSON array element. A path containing spaces is one argument; do not add shell quote characters inside the value. Preserve other servers when editing a shared configuration. For a complete example, see the Cursor configuration guide.
2. Distinguish a disabled agent from a broken agent
The Bridge MCPB wrapper starts disabled. Its visible Enable owner-level local file and terminal access setting must be accepted before the wrapper starts the tools. A manual command uses serve --allow-local-access instead. This difference is deliberate in the published package.
Do not remove a consent check, relabel a shell tool as read-only or widen OS access just to make an error disappear. First decide whether the proposed access is appropriate. A configuration that the user declines is not a technical defect.
The MCPB manifest describes the executable, arguments and configurable settings that a supporting host resolves. An accepted manifest does not prove that a particular host successfully launched its process. See the MCPB manifest specification.
3. Keep protocol output separate from diagnostics
For a local stdio connection, the client communicates with a child process. Protocol messages belong on standard output; diagnostic text belongs on standard error. A wrapper that prints a welcome banner into protocol output can corrupt the conversation. The transport contract is described in the MCP stdio specification.
With Bridge, run node bin/bridge.mjs selftest as a separate diagnostic command. Do not configure the client to run selftest or doctor as its MCP server: those commands produce diagnostic reports and finish. The client entry needs the server command.
If the standalone self-test succeeds but the host does not connect, the next experiment is to compare the exact runtime, arguments and settings used by the host. Reinstalling every dependency would change several variables without identifying the mismatch.
4. A tool error is not always a connection error
A stale SHA-256 is a conflict, not permission denial. Re-read the current file and reassess the intended change. Do not fetch a fresh hash and immediately overwrite a file without checking what changed. A literal edit that matches zero or several occurrences needs a more precise fragment.
A protected or missing path needs a path-level check. Confirm that it is the intended machine and file, then review the access the OS actually grants. Test with a disposable file in a folder you control. Do not diagnose on confidential data or disable system protections to get a green status.
Incomplete output is not an empty result. Bridge marks bounded search and process-output limits. Inspect the returned continuation information or narrow the task. For a started process, poll its existing session and check its final exit code. Sessions are not recoverable after an agent restart in this release.
5. Report enough evidence, not your whole computer
A useful report contains the Bridge version, client name/version, operating system, the step that first failed, a redacted error and whether the standalone self-test passed. Leave out passwords, raw customer files, private paths and full terminal histories.
The first-task report form is public. Use private support for sensitive concerns, still with a minimal reproduction. A paid licence is not a fix for a broken installation; evaluate the local build first.