[BUG] Strict MCP schema validation in v2.0.21+ breaks working MCPs with no opt-out or migration path

[PHMD]

Description

Claude Code v2.0.21 introduced strict MCP tool schema validation that breaks previously working MCP servers without providing:

1. A way to opt-out of validation
2. Warning about the breaking change
3. Graceful degradation (disable problematic MCPs instead of blocking entire session)

Affected MCPs

• Official Perplexity MCP (@perplexity-ai/mcp-server)
• time MCP (yokingma/time-mcp)
• Potentially many others in the ecosystem

Error Message

API Error: 400 
{
  "type":"error",
  "error":{
    "type":"invalid_request_error",
    "message":"tools.XX.custom.input_schema: input_schema does not support oneOf, allOf, or anyOf at the top level"
  }
}

Impact

User Experience:

• Users wake up to broken Claude Code after auto-update
• Entire session is blocked (not just the problematic MCP)
• No clear error message about which MCP is causing the issue
• Users weren't using the problematic MCP, but it still blocks startup

Ecosystem Impact:

• Breaking change with no migration period
• MCP maintainers weren't notified in advance
• Official MCPs (like Perplexity) are affected

Steps to Reproduce

1. Have Claude Code v2.0.20 or earlier with working MCPs
2. Auto-update to v2.0.21+
3. Launch Claude Code
4. Session fails to start due to schema validation

Timeline of Issue

• Before v2.0.21: Perplexity MCP worked fine (lenient validation)
• v2.0.21 (Oct 2025): Added structuredContent support and strict validation
• v2.0.21+: Previously working MCPs now fail validation at startup

Expected Behavior

One or more of:

1. Opt-out flag: Environment variable like CLAUDE_CODE_DISABLE_MCP_SCHEMA_VALIDATION=true
2. Graceful degradation: Skip problematic MCPs with warning, continue session
3. Clear error messages: Tell user which MCP is failing and how to fix it
4. Migration period: Warn users for a few versions before enforcing strictly

Actual Behavior

• Hard failure at startup
• No way to bypass validation
• Entire session blocked
• User has to manually debug which MCP is causing issues

Workaround

Downgrade Claude Code:

npm install -g @anthropic-ai/claude-code@2.0.20

Environment

• Claude Code: v2.0.21 - v2.0.29
• Platform: macOS (Darwin 24.5.0)
• Node: v22.14.0
• Auto-updates: Enabled (default)

Suggested Solutions

Option 1: Environment Variable Opt-Out

export CLAUDE_CODE_SKIP_MCP_SCHEMA_VALIDATION=true

Option 2: Graceful Degradation

⚠️  Warning: Perplexity MCP has invalid schema (oneOf at top level)
    Skipping this MCP. Claude Code will continue without it.
    Fix: Update MCP or see docs.anthropic.com/mcp-validation

Option 3: Config-Level Control

{
  "mcpServers": {
    "perplexity": {
      "skipSchemaValidation": true,
      ...
    }
  }
}

Related Issues

• [BUG] API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"tools.21.custom.input_schema: input_schema does not support oneOf, allOf, or anyOf at the top level"}} #5973 - Same error with tools.21
• [BUG] input_schema does not support oneOf, allOf, or anyOf at the top level #4886 - Same error with tools.21
• Here's a concise, technical GitHub issue title: Invalid Input Schema: OneOf Unsupported in Tool Configuration This title: - Identifies the specific technical problem (input schema limitation) - Uses precise terminology (OneOf, input schema) - Clearly ind #657 - Invalid Input Schema: OneOf Unsupported
• HELP! I can't do 💩! Invalid Tool Input Schema: Unsupported JSON Schema Composition #4295 - Unsupported JSON Schema Composition

Request

Please provide a way for users to continue using Claude Code while MCP maintainers fix their schemas. A breaking change without an opt-out is very disruptive.

Cross-reference

Filed related issue with Perplexity MCP: perplexityai/modelcontextprotocol#57

[PHMD]

Update: Additional Context on Root Cause

Further investigation reveals this may be a more nuanced issue:

What We Found

The Perplexity MCP package pushed TWO breaking updates in the last 24 hours:

• v0.13.0 (Oct 29, 9:16 PM)
• v0.14.0 (Oct 30, 12:14 AM)

When users run npx -y @perplexity-ai/mcp-server, it fetches the latest version, which now has invalid schemas.

The Problem

Even v2.0.20 (before structuredContent support) rejects these new packages, suggesting:

1. Some schema validation existed before v2.0.21
2. OR the MCP packages' schemas are so invalid that even basic validation fails
3. OR there's caching behavior with npx that's complicated

Why This Still Matters

Regardless of when strict validation was added, the core UX issues remain:

• No graceful degradation (entire session blocked)
• No clear error about which MCP is problematic
• No opt-out for users while MCP maintainers fix issues
• Breaking changes propagate immediately via npx -y fetching latest

Workaround

Users can pin to working versions:

{
  "mcpServers": {
    "perplexity": {
      "args": ["-y", "@perplexity-ai/mcp-server@0.2.2"]
    }
  }
}

The request for graceful degradation and better error messages still stands.

[github-actions]

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

[github-actions]

This issue has been automatically closed due to 60 days of inactivity. If you're still experiencing this issue, please open a new issue with updated information.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.