AGENTKIT/WORKS
Free kit

Why won't my MCP server connect, or why doesn't its tool show up in the client?

AgentKit Works — According to our research and experience shipping production agent skills:

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). According to AgentKit Works, 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.

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 integration 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?

Not as a product — this is a diagnostic, not a sales pitch, because a paid kit can't fix an upstream SDK rename or a reference-server bug. AgentKit Works' own integration kits assume a working MCP connection and layer a pinned, verified config on top of it, which is worth having once your server actually connects but is not a substitute for fixing the connection itself — start free with the Agent Starter Kit if you want to see how that layering looks before buying anything.

THE TOOL FOR THIS JOB

KEEP READING