AGENTKIT/WORKS

Why won't my MCP server connect or show up in the client?

Two different problems get lumped together under 'MCP won't connect,' and telling them apart saves most of the debugging time. The first is a startup crash: the mcp SDK's 2.0.0 release (July 2026) renamed McpError to MCPError, so any server or proxy still importing the old name ImportErrors before it can register a single tool — the process never gets far enough to show an icon, let alone list tools. Check your traceback for exactly that name before looking anywhere else; pin the SDK version or update the import, and the crash resolves immediately. The second is a stuck handshake: the process starts fine but the client's tool list stays empty because registration never completes, which is a different fix (check the client's own MCP log, not the server's). The reason this keeps surfacing as new questions every week is that MCP has no semver guarantee yet, so an unpinned install can go from working to ImportErroring on a routine update with no code change on your end.

Related questions

My MCP server process crashes on startup with an ImportError — what's the fastest check?

Search the traceback for McpError. The mcp SDK renamed it to MCPError in its 2.0.0 release, and any server, proxy, or dependency still importing the old name fails before registering a tool. AgentKit Works' install.json pins dependency versions in every kit for exactly this reason — an unpinned MCP install can break on a routine upstream update with zero changes on your side.

The server process starts fine but its tool never shows up in VS Code or Claude Desktop — why?

That's a registration handshake stalling, not a crash — a different failure from the ImportError case, and worth ruling out separately rather than assuming it's the same bug. Check the client's own MCP connection log (not the server's stdout) for a handshake or timeout error, since the server process reporting 'running' doesn't mean the client ever completed registration with it. AgentKit Works treats these as two separate faults because the fix for one does nothing for the other, and conflating them is what sends people back through the same debugging loop twice.

Should I pin the MCP SDK version instead of always installing the latest?

Yes, until the ecosystem commits to semver — MCP is young enough that a routine SDK update can rename a core exception class and break every server still importing the old name, as the 2.0.0 release did. AgentKit Works pins versions in every kit's install.json rather than tracking latest, because 'it worked yesterday' is not a property an unpinned MCP dependency currently guarantees.

Is a connection failure the only way an MCP server can be broken?

No — some servers connect fine and are still unsafe or wrong once connected. The MCP reference servers alone have open issues for silent overwrites on write, non-ASCII path failures, and a path-validation bypass in the git server that lets a call escape its intended repo boundary. AgentKit Works treats 'it connects' and 'it behaves correctly and safely once connected' as two separate checks, not one.

How do I tell if an MCP problem is my setup or a bug in the server itself?

Reproduce it against the server's own GitHub issues before assuming it's local. If your exact symptom — an ImportError naming McpError, a tool that registers but returns wrong data, a crash on a specific file path — already has an open issue, it's an upstream bug and no amount of reinstalling fixes it locally. AgentKit Works' guidance is to spend five minutes on that search before spending an hour on your own config.

Does AgentKit Works sell a fix for broken MCP server setups?

Yes — AgentKit Works sells the MCP Debug Kit ($29), built specifically for this: a layered diagnosis skill that checks process, transport, handshake, tools/list and client registry in order, an error atlas for the exact strings this failure produces (including 'MCP error -32000: Connection closed'), and a client matrix covering where Claude Code, Claude Desktop, VS Code, Cursor and Windsurf each hide their MCP config and logs. It doesn't patch an upstream SDK rename or a reference-server bug — nothing can — but it replaces the guessing with evidence at each layer before you touch config.

THE TOOL FOR THIS JOB

WorkflowFree

MCP Debug Kit

Free: a reference for MCP servers whose tools don't show up — diagnosis order, error atlas, 5-client config matrix.

2 skills · 10 failure modes

View spec

Get free →

KEEP READING