Invalid JSON Schema in Tool Definition in Claude Code

[jordanburke]

Invalid JSON Schema in Tool Definition (tool 208)

Error

API Error: 400 {
  "type": "invalid_request_error",
  "message": "tools.208.custom.input_schema: JSON schema is invalid.
              It must match JSON Schema draft 2020-12
              (https://json-schema.org/draft/2020-12)"
}

Reproduction

1. Configure Dokploy MCP server in Claude Code/Desktop
2. Start a conversation
3. Error appears when loading tool definitions

Note: Disabling the Dokploy MCP server resolves the error, confirming the issue is with this server's tool definitions.

Expected

Tool schemas should conform to JSON Schema draft 2020-12 specification.

Suggested Fix

The tool at index 208 has an invalid input_schema. Common issues:

• Missing or incorrect $schema declaration
• Invalid type values
• Malformed required array or properties object
• Invalid constraint definitions

Please validate the schema at tool 208 against the JSON Schema spec.

Valid schema example:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "param": { "type": "string", "description": "..." }
  },
  "required": ["param"],
  "additionalProperties": false
}

[jordanburke]

Root Cause Identified

After extensive testing, I've identified the real root cause:

The Issue is in the MCP SDK, Not the Tool Definitions

The @modelcontextprotocol/sdk v1.20.1 generates JSON Schema draft-07 but Claude's API strictly requires draft 2020-12.

Evidence:

// In @modelcontextprotocol/sdk/dist/esm/server/mcp.js
zodToJsonSchema(tool.inputSchema, {
    strictUnions: true  // Missing: target: "2020-12"
})

This generates schemas with "$schema": "http://json-schema.org/draft-07/schema#" which Claude rejects.

Related Issue

This is a known problem tracked in SEP-834 - the MCP specification didn't originally specify which JSON Schema version to use. Anthropic's API is strict about requiring 2020-12 while the SDK defaults to draft-07.

Temporary Fix

For Local Testing: Patch your local node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:

# Backup original
cp node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js{,.backup}

# Add target: "2020-12" to zodToJsonSchema calls
sed -i '' 's/zodToJsonSchema(tool\.inputSchema, {$/zodToJsonSchema(tool.inputSchema, {\n                            target: "2020-12",/' node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js

sed -i '' 's/zodToJsonSchema(tool\.outputSchema, {$/zodToJsonSchema(tool.outputSchema, {\n                        target: "2020-12",/' node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js

# Rebuild project
npm run build

Long-term Solution

This requires a fix in the @modelcontextprotocol/sdk package itself. The SDK needs to:

1. Add target: "2020-12" option to all zodToJsonSchema() calls
2. Or update to a newer version that implements SEP-834

Previous Changes Still Needed

The changes I made to replace z.object({}).optional() with z.record(z.unknown()).optional() are still good practice (more semantically correct for Docker Swarm configs), but they weren't the cause of the validation errors.