Why Claude Code or Cursor rejects your MCP tool schema
You wrote an MCP server. It starts. Then a client says your tool schema is invalid, or the tools simply do not show up. This post lists the schema problems that users have reported against Claude Code, Cursor and others, what each report actually says, and how to check for them by hand and with a small script. I will mark every claim as one of three things. Confirmed means I read the official…
The wire material tells a story about why certain MCP tool schemas may be rejected by Claude Code or Cursor. The key points are:
1. The root of the inputSchema must have a type: object. This is confirmed as a rejection issue in the Claude Code GitHub repo. The spec requires inputSchema.type to be object at the root. To fix, ensure type: object is at the root of every inputSchema, even for tools with no parameters.
2. The $schema dialect must be draft-2020-12, not draft-07. The spec defaults to draft-2020-12 when no $schema field is provided. If using draft-07, it must be explicitly included. Some clients reject draft-07. To check, verify the $schema URL in inputSchema and outputSchema. If draft-07 is not needed, remove it or change it to draft-2020-12.
3. The root level of inputSchema and outputSchema should not contain keywords like oneOf or anyOf. While the spec allows these keywords in 2020-12, some clients may reject them if they only check that the root is an object. Keep these keywords under properties or remove them if they are not needed.
4. Descriptions in schemas may be truncated at 2048 characters by some clients. While not confirmed as a universal issue, it was reported in Claude Code issues. To address, ensure descriptions are within the 2048 character limit or format them differently.
The source material provides multiple examples of these issues causing rejection errors from Claude Code and Cursor. The fixes involve checking schemas manually or with a small script to ensure they conform to the spec and client expectations.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
