Troubleshoot a connection

Run the exact configured command in a terminal. A missing executable, invalid package name, bad path, or absent environment variable usually appears immediately.

Diagnose in order:

1. Can the host parse its configuration?
2. Can it find and start the executable?
3. Does the process stay alive long enough to initialize?
4. Can client and server agree on protocol behavior?
5. Does discovery return the expected capabilities?
6. Does one minimal call work?

This turns “the server disappeared” into a specific failed boundary.

For a stdio server, stdout is the protocol. Startup banners and debug logs on stdout can break the connection. Send diagnostic text to stderr instead.

Run the configured command with the same working directory and environment the host uses. A command that succeeds in your interactive shell may depend on aliases, a version manager, or variables the desktop host never inherits. Use absolute paths temporarily to prove resolution, then choose a maintainable configuration.

Check the host log for the server process exit code and stderr. Then change one thing and retry the same discovery request.

If initialization fails after an upgrade, compare the pinned SDK, protocol revision, server arguments, and advertised capability schema with the last working record. Roll back one version rather than widening access or reinstalling unrelated components.

Do not solve a path error by granting access to the entire filesystem. Fix the path or configuration while keeping the smallest useful scope.

Write down the failed layer, evidence, one change, and retest result. That small discipline preserves the clues that random configuration changes erase.