Check your installed MCP SDK version before trusting a documented fix
You will confirm which MCP SDK version your project runs and pick the fix that matches it. This keeps you from chasing workarounds for bugs that are already patched.
- Find resolved versionRead the lockfile for the SDK and zod
- Match the errorCompare the message with known reports
- Apply version-specific fixUpgrade or use the documented workaround
- Re-test the tool callConfirm the original error now shows
Why it matters
The right fix for an MCP error depends on the SDK version you run. Errors thrown inside a TypeScript SDK tool with an outputSchema were replaced by a misleading -32602 message, and that was fixed in 1.15.0 (source (opens external site)). Reports of keyValidator._parse is not a function with zod v4 point to a different fix, passing a raw shape or pinning zod (source (opens external site)). Apply the fix that matches your version, not the first one you find.
Steps
- Find the SDK version your project actually resolves from its lockfile, and note the zod version too.
- If you use the TypeScript SDK with an outputSchema and see -32602 saying no structured content was provided, upgrade to 1.15.0 or later. A commenter verified that on 1.15.0 the original error comes through with isError set (source (opens external site)).
- If you cannot upgrade, return a structuredContent object that matches the outputSchema alongside the text content, and keep the text as a JSON string. Treat this as required whenever a tool declares an outputSchema, since older versions do not map thrown errors to isError on their own.
- If you see
keyValidator._parse is not a function, check how the schema reachesserver.tool(). Passing a raw shape such as{ query: z.string() }instead of a z.object() wrapper was reported to resolve it (source (opens external site)). - Treat a zod 3.x downgrade, such as
npm install zod@^3.21.4, as a fallback only. One user reported it did not fix their case, and a contributor said the SDK itself needs a current Zod version when it is used alongside packages that depend on newer zod (source (opens external site)). - Re-run the failing tool call after each change, one change at a time, so you know which change helped.
- For Python, check whether your project uses FastMCP v2 or the bundled module before you choose. The maintainers confirmed the two are sufficiently diverged and that the relationship will be clarified in SDK 2.0 (source (opens external site)).
Common mistakes
- Applying a fix from an older report without checking the version you have installed.
- Assuming a closed issue means the bug is gone. One outputSchema issue was closed as stale, so test the call yourself.
- Treating one user's report as proof that a fix works in every setup.
- Downgrading a dependency to chase one error without re-testing the rest of your stack.
Checklist
0 of 8 done