Fix: MCP Server Disconnected Error (2026)

The Error

Your MCP server tool call completes successfully, but Claude Code immediately tears down the stdio transport and respawns the server:

Closing transport (stdio transport error: Error)

From the MCP logs (found at ~/Library/Caches/claude-cli-nodejs/-Users-{username}/mcp-logs-{server-name}/):

{"debug":"Calling MCP tool: my_tool_name","timestamp":"2026-04-14T05:41:34.761Z"}
{"debug":"STDIO connection dropped after 139s uptime","timestamp":"2026-04-14T05:41:34.880Z"}
{"debug":"Connection error: Received a progress notification for an unknown token: {\"method\":\"notifications/progress\",\"params\":{\"progress\":1,\"total\":1,\"message\":\"Completed\",\"progressToken\":5}}","timestamp":"2026-04-14T05:41:34.880Z"}
{"debug":"Closing transport (stdio transport error: Error)"}
{"debug":"Tool 'my_tool_name' completed successfully in 119ms"}
{"debug":"Starting connection with timeout of 30000ms"}

The tool call succeeded, but the transport was torn down anyway. If another tool call was in-flight, it fails with “MCP server disconnected.”

Quick Fix

If you control the MCP server: stop emitting terminal progress notifications after dispatching the tool response.

# BEFORE (causes the bug):
1. Process the request
2. Send the tool response
3. Send progress notification (progress=1, total=1) <-- races the response
# AFTER (fix):
1. Process the request
2. Send the tool response
3. Do NOT send terminal progress after response

What Causes This

The MCP protocol allows servers to emit notifications/progress messages during long-running operations. These notifications include a progressToken that matches the client’s in-flight request.

Here is the race condition:

  1. Claude Code sends a tool call request with a _meta.progressToken
  2. The MCP server processes the request and sends back the result
  3. Claude Code receives the result and removes the progressToken from its in-flight request map
  4. The MCP server sends a terminal progress notification (progress == total) for the same token
  5. The notification arrives after the token has been removed from the map
  6. Claude Code treats the unknown-token notification as a fatal stdio transport error
  7. The entire transport is torn down and the server process is respawned

The MCP spec’s progress notifications section does not specify what a client should do when receiving a progress notification for an unknown token. Most MCP SDK implementations drop it with a debug log. Claude Code’s implementation treats it as transport corruption.

Full Solution

For MCP Server Authors

Remove terminal progress notifications that fire after the response. Only send progress notifications before the tool response:

// Send progress BEFORE the result, not after
async function handleToolCall(request: any) {
 const progressToken = request._meta?.progressToken;
 // Progress notification during work (before response)
 if (progressToken) {
 await sendProgress(progressToken, 0.5, 1.0);
 }
 const result = await doExpensiveWork(request.params);
 // Return the result - do NOT send progress=1/total=1 after this
 return { type: "text", text: JSON.stringify(result) };
}

For MCP Server Users (Cannot Modify Server)

Option 1: Wrap the server with a stdio proxy that filters progress

#!/bin/bash
# mcp-progress-filter.sh
# Sits between Claude Code and the MCP server, filtering late progress
REAL_SERVER="$@"
$REAL_SERVER | while IFS= read -r line; do
 # Pass through everything except progress notifications
 if echo "$line" | grep -q '"notifications/progress"'; then
 echo "$line" >> /tmp/mcp-filtered-progress.log
 else
 echo "$line"
 fi
done

Configure Claude Code to use the wrapper:

{
 "mcpServers": {
 "my-server": {
 "command": "/path/to/mcp-progress-filter.sh",
 "args": ["python", "-m", "my_mcp_server"]
 }
 }
}

Option 2: Accept the reconnection delay

If the server reconnects automatically (Claude Code does respawn it), the main impact is latency. The 30-second reconnection timeout is acceptable for non-critical use cases.

Check Your MCP Logs

The logs that confirm this issue are at:

# macOS
ls ~/Library/Caches/claude-cli-nodejs/-Users-$(whoami)/mcp-logs-*/

Look for entries matching:

"Connection error: Received a progress notification for an unknown token"

Prevention

  • When authoring MCP servers, only send progress notifications before the tool response, never after
  • If your server must send a terminal progress notification, send it before the JSON-RPC response in the same write batch
  • Test your MCP server with Claude Code specifically, not just generic MCP clients, since Claude Code has stricter transport error handling
I hit this exact error six months ago. Then I wrote a CLAUDE.md that tells Claude my stack, my conventions, and my error handling patterns. Haven't seen it since. I run 5 Claude Max subs, 16 Chrome extensions serving 50K users, and bill $500K+ on Upwork. These CLAUDE.md templates are what I actually use. Not theory — production configs. **[Grab the templates — $99 once, free forever →](https://zovo.one/lifetime?utm_source=ccg&utm_medium=cta-mcp&utm_campaign=claude-code-mcp-server-disconnected)** 47/500 founding spots. Price goes up when they're gone.

Configure it → Build your MCP config with our MCP Config Generator.

Try it: Paste your error into our Error Diagnostic for an instant fix.

Frequently Asked Questions

Does this error affect all operating systems?

This error can occur on macOS, Linux, and Windows (WSL). The exact error message may differ slightly between platforms, but the root cause and fix are the same. macOS users may see additional Gatekeeper or notarization prompts. Linux users should check that the relevant system packages are installed. Windows users should ensure they are running inside WSL2, not native Windows.

Will this error come back after updating Claude Code?

Updates can occasionally reintroduce this error if the update changes default configurations or dependency requirements. After updating Claude Code, verify your project still builds and runs correctly. If the error returns, reapply the fix and check the changelog for breaking changes.

Can this error cause data loss?

No, this error occurs before or during an operation and does not corrupt existing files. Claude Code’s edit operations are atomic — they either complete fully or not at all. However, if the error occurs during a multi-step operation, you may have partial changes that need to be reviewed with git diff before continuing.

How do I report this error to Anthropic if the fix does not work?

Open an issue at github.com/anthropics/claude-code with: (1) the full error message including stack trace, (2) your Node.js version (node --version), (3) your Claude Code version (claude --version), (4) your operating system and version, and (5) the command or operation that triggered the error.