Explore subagents fail with API 400 error due to $schema in MCP tool schemas

[shane-click]

Bug Description

Explore subagents (launched via the Agent tool with subagent_type: Explore) fail immediately with an API 400 error. General-purpose agents work fine with the same configuration.

Error

API Error: 400 {"type":"error","error":{"type":"invalid_request_error",
"message":"tools.134.custom.input_schema.properties: Property keys should match pattern '^[a-zA-Z0-9_.-]{1,64}$'"}}

Root Cause

Multiple MCP tool plugins include a $schema key at the top level of their parameters object (a standard JSON Schema keyword):

• Playwright plugin: "$schema": "https://json-schema.org/draft/2020-12/schema"
• Vercel integration: "$schema": "http://json-schema.org/draft-07/schema#"
• Context7 plugin: "$schema": "http://json-schema.org/draft-07/schema#"

The $ character in $schema does not match the Anthropic API's required pattern ^[a-zA-Z0-9_.-]{1,64}$.

Why general agents work but Explore agents don't

The general-purpose agent type appears to handle tool schemas differently (likely using deferred/lazy loading), so the API never sees the raw $schema key. The Explore agent type sends full tool schemas to the API upfront, triggering the validation error.

Reproduction Steps

1. Have Playwright, Context7, or Vercel MCP tools enabled
2. Launch an Explore subagent via the Agent tool
3. The subagent immediately fails with the 400 error above
4. Launch a general-purpose subagent with the same prompt — it works fine

Expected Behavior

Claude Code should strip JSON Schema meta-keywords ($schema, $id, etc.) from MCP tool input schemas before sending them to the Anthropic API, regardless of agent type.

Environment

• Claude Code CLI
• macOS (Darwin 25.3.0)
• Plugins: Playwright, Context7, TypeScript LSP, Frontend Design
• Connected integrations: Vercel, Gmail, GoDaddy, Twilio, Chrome

[mauritsblomlinkthings]

Confirming on Windows + additional findings

Environment: Windows 11, Claude Code CLI (Opus 4.6, 1M context), 17 MCP servers connected

Same issue here — general-purpose agents and all other subagent types fail with:

API Error: 400 tools.16.custom.input_schema: JSON schema is invalid.
It must match JSON Schema draft 2020-12

Key additional finding: Anthropic-hosted MCP servers are also affected

This is not limited to npm/TypeScript SDK servers. Even the Anthropic-hosted claude.ai Gmail integration includes "$schema": "http://json-schema.org/draft-07/schema#" in its tool parameter schemas. So stripping $schema from MCP tool schemas needs to happen in Claude Code itself — fixing individual MCP servers won't fully resolve it.

Verified via ToolSearch in the main session — all MCP tools across all servers (hosted and npm-based) include the $schema property:

Server type	Example	$schema present
Anthropic-hosted	claude.ai Gmail	Yes (draft-07)
npm (TypeScript SDK)	@modelcontextprotocol/server-github, context7	Yes (draft-07)
npm (direct zod)	@gongrzhe/server-gmail-autoauth-mcp, @sylphlab/pdf-reader-mcp	Yes (draft-07)
Python-based	superset, whatsapp	TBD — likely unaffected

Why the main session works

The main session uses deferred/lazy tool loading — tools are only sent to the API when needed. Agents send all tool definitions upfront in a single request, triggering the API's $schema property validation ($ doesn't match pattern ^[a-zA-Z0-9_.-]{1,64}$).

Upstream status

• MCP TypeScript SDK v2 (PR #1606) removes Zod from public APIs, which structurally fixes this — but v2 is not yet released (latest is v1.27.1).
• The v1 fix PR (#1432) was closed without merging.

Suggested fix

Claude Code should strip JSON Schema meta-keywords ($schema, $id) from all MCP tool input_schema objects before sending them to the Anthropic API — for all agent types, not just the main session.

[github-actions]

Closing for now — inactive for too long. Please open a new issue if this is still relevant.