DEV Community

MilkyWay008
MilkyWay008

Posted on

Your MCP tools stopped working after an update? Blame the mcp 2.0 SDK migration

#ai #tutorial #mcp

If you run any AI tooling that uses MCP, the last couple of weeks might have been rough. The pattern kept showing up in GitHub issues: somebody does a routine update, and suddenly their MCP servers "just stop working." No error, or a cryptic one. The gateway reports healthy, the server says enabled, the tools never show up.

It hit across a lot of different tools around the same time. AutoGen's MCP extensions, LlamaIndex's MCP tools, Copilot CLI, Claude Desktop configs, a few agent frameworks I won't single out...... all broke roughly the same way. That's not random bad luck.

The common thread: the mcp Python SDK jumped to 2.0.0 near the end of July, and 2.0.0 ships breaking changes. A bunch of wrapper libraries pinned mcp>=1.x with no upper bound, so the next update pulled 2.0.0 and everything built against the old API fell over.

What actually changed

A handful of concrete, mechanical breaks:

  • streamable_http_client() used to hand back a 3-tuple. It's 2 now. Old code that unpacks three values throws ValueError on startup.
  • Names moved. streamablehttp_client became streamable_http_client. Code that only checks for the old name quietly loses HTTP transport.
  • Types flipped from camelCase to snake_case. .inputSchema is now input_schema, .isError is now is_error.
  • The client only accepts JSON Schema draft 2020-12 now, not draft-07. A server that declares the old $schema gets rejected outright.
  • The protocol handshake changed (a modern server/discover over a legacy initialize), which is what tripped up Copilot CLI.

None of that is malicious. It's a major version, majors break things. The infuriating part is that a lot of the ecosystem didn't cap the dependency, so the breakage stayed quiet until you updated.

How to confirm it's this

Check what version you're on:

pip show mcp
# or
uv pip show mcp
Enter fullscreen mode Exit fullscreen mode

If it's 2.0.0 and your tool was built against 1.x, that's almost certainly the culprit. No repro needed, no config archaeology.

The fix, by tool

Most of the time, pin back to what your tool was built against:

pip install "mcp<2"
# or restore the exact pin your tool declares, eg
pip install "mcp==1.28.1"
Enter fullscreen mode Exit fullscreen mode

For the specific cases worth knowing:

  • AutoGen (autogen-ext[mcp]): pin mcp<2. Upstream caps it at >=1.11,<2.
  • LlamaIndex (llama-index-tools-mcp): pin to 0.4.x, or patch client.py to unpack the 2-tuple (read, write) instead of three values. Sessions work again right away.
  • Copilot CLI: pin to 1.0.81-0. The 81-1 build is the regression.
  • Hermes: restore the pinned mcp and starlette, restart the gateway, then run mcp test to confirm the tools reconnect.

One case has no clean pin: if your MCP server is getting rejected on its schema dialect (that draft-07 error in Claude Desktop), the client only speaks 2020-12 now. The verified workaround there is a thin stdio proxy that rewrites the outputSchema $schema to 2020-12. Ugly, but it works.

The actual lesson

I could go on about specifics, but the honest takeaway is boring: pin your dependencies. If a tool's updater pulls an unpinned major version over a declared minor pin, that's a bug in the updater, but you can protect yourself by not letting chain-updates run loose.

When you update AI tooling, glance at the mcp version after. If MCP servers go quiet and there's no obvious error, check that package first before you start tearing down configs.

I could be wrong, but I've now seen this exact failure across five separate vendors in a week, same root cause, same class of fix. If your MCP setup broke after an update and nothing else explains it, your mcp package version is worth a look. Give it a shot before you nuke your config.

Top comments (0)