AgentArmorHQ
Sign in
Supply chain

Confirm your MCP SDK version and wire format before debugging transport errors

AgentArmorHQ team2 min read

You will check the installed mcp version and whether your server exposes the session headers the Inspector needs. Ruling out version and CORS problems first keeps you from chasing transport bugs that are not in your code.

Before checking versions and headers

  • Old mcp 1.1.2 installed despite README docs
  • Unknown session returns 400, client stuck
  • Inspector never reads mcp-session-id header

After confirming version and CORS

  • Current stable mcp release installed and restarted
  • Unknown session returns 404, client reinitializes
  • mcp-session-id exposed to the Inspector via CORS

Why it matters

A 400 from a streamable HTTP MCP server can come from the SDK version rather than your code. On Python SDK 2.3.4, an unknown Mcp-Session-Id returned 400 instead of 404, which stops clients from reinitializing, and the fix landed in PR #1945 (source (opens external site)). Separately, the Inspector cannot read mcp-session-id from a cross-origin server unless CORS exposes it (source (opens external site)). Check both before you touch the session logic.

Steps

  1. Check the installed mcp version in the project environment. Do not trust the version in the README. An mcp 1.1.2 install lacked FastMCP even though the README documented it (source (opens external site)).
  2. Upgrade to a current stable release. Pinning an old release candidate such as 1.2.0rc1 is unverified, since no one in that issue confirmed the pin works (source (opens external site)).
  3. Confirm the build includes PR #1945, which returns 404 for unknown or expired session IDs and is in the v1.x line and on main (source (opens external site)). Then restart the server so the new code is running.
  4. Send a request with a made-up or stale Mcp-Session-Id and record the status code. A 404 lets the client discard the session and reinitialize. A 400 on an unknown session points to an older SDK.
  5. If you use the Inspector's direct connection against a different origin, configure CORS on your server or reverse proxy so the browser can read mcp-session-id. Without it, the Inspector sends the follow-up request with no session ID and gets a 400 (source (opens external site)).
  6. Add mcp-protocol-version to the exposed headers as well. The Inspector reads that value to resolve the protocol version (source (opens external site)).
  7. Only after the version and headers check out, debug the actual transport flow.

Common mistakes

  • Trusting the README's feature list without checking the installed package version.
  • Pinning a release candidate and assuming it is tested.
  • Forgetting to restart the server after upgrading, so old code keeps running.
  • Skipping CORS checks when the Inspector and server run on different origins, then blaming the session logic.

Checklist

0 of 7 done

Sources

  1. FastMCP missing in mcp 1.1.2 from PyPI even though README shows it
  2. MCP Python SDK returns 400 instead of 404 for unknown Mcp-Session-Id: fixed in v1.x?
  3. Inspector 0.17.0 direct connection fails on streamable HTTP: mcp-session-id header not exposed via CORS
Was this guide useful?