MCP Works in Terminal but Not Desktop: Check the Launch

If an MCP server works in your terminal but not your desktop app, compare the process each one launches. The apparent command can be identical while its executable, runtime, working directory or available variables differ. First establish whether the server starts at all; only then investigate protocol messages and tool discovery.

This guide concerns a desktop host launching a local stdio server. A remote HTTP connector has different failure boundaries. Also distinguish an app's chat, coding and other modes: test the exact mode that fails.

Capture the first useful error

The official local-server guide recommends checking configuration syntax, absolute paths, application logs and manual server launch. It documents Claude Desktop MCP logs under ~/Library/Logs/Claude on macOS and %APPDATA%\Claude\logs on Windows. Confirm the documentation for your actual client and installation.

Earliest failure	Start with	Do not conclude yet
Executable not found / ENOENT	Configured command and executable resolution	That the MCP package is defective
Process starts, then exits	Runtime compatibility, arguments and required variables	That broad filesystem access is needed
Process stays alive, invalid JSON appears	stdout content and launch wrappers	That the provider credential is wrong
Protocol works, tool list is empty	Discovery and client exposure	That reinstalling Node will fix it

A server waiting silently in a terminal may merely be waiting for input. That is not a successful MCP interaction. Compare a harmless tool call as well as process startup.

Compare these four launch facts

Write a small worksheet with terminal and desktop columns: executable path, runtime version, working directory and the presence of each required variable. Record the exact configured arguments locally, but redact credentials before sharing them.

For a Node-based server you control, this temporary startup diagnostic uses documented Node process properties. Place it in executable server code after imports, not inside a JSON configuration file:

console.error(JSON.stringify({
  executable: process.execPath,
  nodeVersion: process.version,
  cwd: process.cwd(),
  apiKeyPresent: Boolean(process.env.EXAMPLE_API_KEY)
}));

Replace the example variable name with the one your server actually requires. Do not print its value or dump the entire environment. Executable and directory paths may include your username, so redact those before posting logs. Remove the diagnostic after resolving the issue.

The snippet is illustrative. It reports process facts; it cannot prove that a credential is valid or that the desktop client accepts the server's protocol.

Fix only the demonstrated mismatch

If the desktop host cannot resolve the executable, use the client's documented launch configuration and the actual installed executable path. Avoid copying another person's version-manager directory. A versioned path can stop working when that runtime is removed.

If the package runner is found but the runtime is not, inspect the environment available to that process. Pointing to npx by an absolute path does not establish that every executable it needs can be found. Use the server publisher's supported invocation; do not guess a package's internal dist/index.js path.

If a relative configuration or data path resolves differently, supply the supported absolute path or working-directory option. If a required variable is missing, configure only the needed variable through the host's supported mechanism. A value exported in an interactive shell is not evidence that another process received it.

Prove the fix in the failing app

Fully restart the desktop client using its documented procedure, then check discovery and run one read-only tool against a known fixture. Repeat once after another cold launch. Keep the terminal command, server version and fixture constant so that the comparison means something.

If launch succeeds but parsing fails, continue with MCP stdout contamination. If parsing succeeds but tools are absent, use connected but no tools. Review permissions separately before expanding access.

Documentation checked October 12, 2026. The Node diagnostic was checked independently; no desktop-client reproduction is claimed.