inputSchema and outputSchema are valid JSON Schema
Every MCP tool schema must be valid against its dialect (JSON Schema 2020-12 by default), with resolvable local $refs and compilable patterns; one invalid schema can make the model API refuse every tool sent with it.
Check spec-schema-valid · MCP specification 2026-07-28 · default severity: blocking · rubric 2.1.0
Error message you’ll see
API Error: 400 tools.44.custom.input_schema: JSON schema is invalid. It must match JSON Schema draft 2020-12 (https://json-schema.org/draft/2020-12). […]Claude API (400), for a schema that fails the 2020-12 meta-schema. Where this was reported
Invalid schema for function 'hubspot_search_objects': In context=('properties', 'filterGroups', 'items', 'properties', 'filters', 'items', 'properties', 'values'), array schema missing items.OpenAI API, for an array argument with no "items". Where this was reported
What fails
The schema is checked against the JSON Schema 2020-12 meta-schema, and every local $ref and every regular expression in "pattern" must resolve or compile. An invalid schema makes argument validation fail or behave unpredictably.
The rule
Schemas MUST be valid according to their declared or default dialect
Source: MCP specification 2026-07-28: Overview (JSON Schema usage, _meta, icons)
How to fix it
Correct the keyword named in the message. Common causes: a misspelled type name, "required" that is not an array of strings, a broken $ref pointer, or a regular expression that does not compile.
- Read the keyword named in the finding or the API error path (tools.N points at the Nth tool sent).
- Fix the usual causes: a misspelled type ("str", "int"), "required": true instead of an array, a $ref to a missing $defs entry, a pattern that does not compile.
- Give every array an "items" schema: stricter validators require it.
- Generate schemas from your types (zod, Pydantic) instead of writing them by hand.
TypeScript SDK
import { McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod';
const server = new McpServer({ name: 'issues', version: '1.0.0' });
server.registerTool(
'tag_issue',
{
title: 'Tag issue',
description: 'Add labels to one issue. Use when the user asks to label or categorise an issue.',
inputSchema: z.strictObject({
issue_id: z.string().describe('Issue ID, for example ISS-42'),
labels: z.array(z.string()).min(1).max(20).describe('Labels to add'),
}),
annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
},
async ({ issue_id, labels }) => ({ content: [{ type: 'text', text: 'Done' }] }),
);Python SDK
from typing import Annotated
from pydantic import Field
from mcp.server.mcpserver import MCPServer
from mcp.types import ToolAnnotations
server = MCPServer("issues")
@server.tool(
title="Tag issue",
annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=False, openWorldHint=False),
)
def tag_issue(
issue_id: Annotated[str, Field(description="Issue ID, for example ISS-42")],
labels: Annotated[list[str], Field(description="Labels to add", min_length=1, max_length=20)],
) -> str:
"""Add labels to one issue. Use when the user asks to label or categorise an issue."""
return "Done"Run against @modelcontextprotocol/server 2.4.0, mcp 2.3.0 and fastmcp 4.2.2 on 2026-11-18; the checker confirms this check passes on the tool list each snippet produces.
Questions
Why does one tool’s schema break all my tools?
Clients send every tool in one model request. If any schema fails validation the API refuses the request, so no tool works until that schema is fixed. The tools.N index in the error is the position in the combined list.
How do I find which schema is invalid?
Paste the tools/list answer into the checker: it validates each schema against the 2020-12 meta-schema and names the tool and keyword.
Related checks
- Schemas use JSON Schema 2020-12
- inputSchema has type "object" at the root
- No $ref to a network or external URI
- All checks in MCP tool input and output schemas
Further reading
How this check is graded
It counts toward: MCP specification 2026-07-28. See the rubric.
Last verified against MCP specification 2026-07-28: Overview (JSON Schema usage, _meta, icons) on 2026-11-18. The rule above is quoted in the source’s own words. This page as Markdown.
Check your tool list: paste your tools/list, nothing is sent anywhere