# 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. Last verified against MCP specification 2026-07-28: Overview (JSON Schema usage, _meta, icons) on 2026-11-18.

## Error message you’ll see

```text
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: https://github.com/MarkusPfundstein/mcp-gsuite/issues/63

```text
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: https://github.com/HubSpot/mcp-server/issues/2

## 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)](https://modelcontextprotocol.io/specification/2026-07-28/basic/index#schema-validation)

## 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.

1. Read the keyword named in the finding or the API error path (tools.N points at the Nth tool sent).
2. 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.
3. Give every array an "items" schema: stricter validators require it.
4. Generate schemas from your types (zod, Pydantic) instead of writing them by hand.

### TypeScript SDK

```ts
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

```python
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"
```

## 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](https://isokron.ai/mcp-check/checks/spec-schema-dialect)
- [inputSchema has type "object" at the root](https://isokron.ai/mcp-check/checks/spec-input-schema-root-object)
- [No $ref to a network or external URI](https://isokron.ai/mcp-check/checks/spec-ref-remote)
- [MCP tool input and output schemas](https://isokron.ai/mcp-check/checks/schema)

## Further reading

- [How to test an MCP server without fooling yourself](https://isokron.ai/research/how-to-test-an-mcp-server)

Counts toward: MCP specification 2026-07-28.

Rubric: https://isokron.ai/mcp-check/rubric

Check your tool list: https://isokron.ai/mcp-check
