Fix DeepSeek Harness MCP Connection Errors
Isolate the failing MCP entry, then check its transport, executable or URL, required environment and connection diagnostics in that order. Recover the basic session before re-enabling one server. A Web UI that loads does not establish MCP tool discovery, and a listed tool does not establish a successful call.
Sharing includes the public link only, without local progress or private configuration.
1. Isolate one failing MCP server
Record whether the failure occurs during profile startup, server discovery or a tool call. Note the serverName and the first relevant error before reconnect messages obscure it. Temporarily disable the failing entry in the patch that owns it and confirm the basic profile starts; preserve a copy so you can restore the intended configuration.
The reviewed CLI ships the MCP client dependency but enables no server by default. An added server is a separately configured executable or service. Use a server you intended to trust and isolate one entry at a time so two unrelated failures do not get mistaken for one problem.
2. Check the stdio executable or HTTP endpoint
For stdio, compare command, args and cwd with the server’s own startup instructions. Check the executable in the same environment that launches dsh. For Streamable HTTP, compare the configured URL with the actual MCP endpoint; a working service homepage is not a connection test for that endpoint.
Treat this as a sequence of narrow checks: can the executable be located, can the server start, can the client negotiate, then can it discover tools? Running a stdio server directly may leave it waiting for protocol input. Silence alone is neither success nor a reason to terminate it as a hang.
- Keep the server command and its argument list separate; do not convert a structured args list into one shell string.
- Resolve a relative working directory against the actual configuration and launch environment.
- Use the transport supported by the server instead of swapping it because another service used a different one.
node --version
npm --versionWhat to check: If the configured server command uses Node or npx, these checks establish that this terminal can find that runtime. They do not launch the server or perform an MCP handshake.
3. Pass the server’s required environment explicitly
In the reviewed stdio implementation, ambient names containing KEY, PASSWORD, SECRET or TOKEN are scrubbed before the server starts. Required credentials therefore need an explicit mapping in the MCP entry’s env configuration. A key visible to the parent shell is not proof that the MCP child received it.
Check names and presence rather than values. Keep the DSH model-provider key separate from a GitHub token, database credential or other secret required by an MCP server. For HTTP, check the server’s documented authentication header and its configuration source without publishing it.
4. Verify the effective entry and recover tool discovery
Inspect the composed profile to confirm that the MCP row you edited is the one actually used. Check its enabled state, transport, command or URL and server namespace. A later complete-row override can remove fields from an earlier patch. Do not add timeout or retry fields copied from a different release without checking the current configuration reference.
After repairing the entry, re-enable that one server and observe connection and discovery before calling a tool. If automatic reconnection has stopped, reload the repaired configuration or restart the profile. Use the server’s own read-only diagnostic tool, if available, before requesting a mutation.
npx --yes @deepseek-ai/dsh@0.2.0-rc.2 --profile web --dump-configWhat to check: Find the effective MCP entry and its source-layer comments. This only composes configuration; it does not connect to the server. Review command arguments, headers and env values for secrets before sharing output.
5. Capture evidence for the failure stage
A useful report names the dsh version, platform and launch shell, MCP server package or service version, selected transport, and first sanitized connection error. State whether the server failed to start, tools never appeared, or a discovered tool failed when called.
Changing many servers, plugins and provider settings at once destroys that comparison. Keep the repaired entry and a minimal reproduction so another person can test the same stage. Raw startup diagnostics can contain sensitive configuration; inspect them before posting an excerpt.
MCP failure stages and the next useful check
| Stage | Example symptom | Next check |
|---|---|---|
| Process startup | Executable not found or process exits. | command, args, cwd, runtime and server prerequisites. |
| Connection | Endpoint or transport negotiation fails. | stdio versus Streamable HTTP, endpoint and authentication. |
| Discovery | Profile runs but expected server tools are absent. | First connection diagnostic and the effective MCP entry. |
| Tool call | A tool is listed but its request fails. | The server’s call error, outage state and tool-specific access. |
Frequently asked questions
Why does my MCP server not receive the token from my terminal?
The reviewed stdio bridge scrubs secret-like ambient variable names before spawning the server. Explicitly map the required name in the MCP entry’s env configuration and verify that the configured value source is available. Do not print the token while checking it.
Does a working Web UI prove the MCP server connected?
No. The Web server, MCP connection and tool discovery are separate stages. Confirm the expected server-qualified tools appear, then test an appropriate read-only call.
Should I increase the timeout for every MCP startup failure?
First fix command, transport, environment and the earliest diagnostic. A nonexistent executable or wrong endpoint will not work after a longer wait. Use only timeout fields accepted by the exact MCP client version; startup and tool-call timing are different settings.
Why does a directly launched stdio server appear to do nothing?
A stdio server can be waiting for an MCP client to send protocol messages. Use its own documented startup checks and the client’s negotiation diagnostics. An idle terminal does not establish a successful handshake.
Is Discussion #522 proof that the same bug affects my version?
A community report is evidence of a reported observation, not a reproduced cause or a publisher-confirmed fix for your release. Compare the exact server, transport and versions before treating it as your diagnosis.
First-party sources
Open the pinned or retrieved source before acting on a changed release candidate.
Community reports
These are open user reports hosted in the official repository. They are not publisher confirmation and have not been independently reproduced by this guide unless a separate local reproduction is linked.