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

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

• #5973 - Same error with tools.21
• #4886 - Same error with tools.21
• #657 - Invalid Input Schema: OneOf Unsupported
• #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