[BUG] Cowork/Desktop: MCP tool inputSchema with property-level anyOf [X, null] (Optional[X]) is silently stripped before reaching the model

Found 3 possible duplicate issues:

1. https://github.com/anthropics/claude-code/issues/48687
2. https://github.com/anthropics/claude-code/issues/25865
3. https://github.com/anthropics/claude-code/issues/3084

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

Found 3 possible duplicate issues: 1. MCP tools/list flattens anyOf array-or-null filter schema to scalar string #48687 2. [[BUG] Notion MCP connector serializes JSON object parameters as strings, breaking update/move/create operations #25865](https://github.com/anthropics/claude-code/issues/25865) 3. [[BUG] MCP FastMCP Pydantic model parameters serialized as JSON strings causing validation errors #3084](https://github.com/anthropics/claude-code/issues/3084) This issue will be automatically closed as a duplicate in 3 days. If your issue is a duplicate, please close it and 👍 the existing issue instead To prevent auto-closure, add a comment or 👎 this comment 🤖 Generated with Claude Code

Cross-references:

• Same symptom (closed dup): #48687
• Canonical schema-strip issue: #18260
• Same root cause, object variant: #25865 (still open, multiple Cowork confirmations through 2026-03-27)
• Same root cause, "fixed in CLI" per @ollie-anthropic on 2026-XX: #3084

→ My report shows the fix landed in CLI but not in Desktop/Cowork

I filed https://github.com/anthropics/claude-code/issues/58747, which is similar except with a type union instead of anyOf. Possibly the same root cause?

Worth separating the two diagnostic layers, because the bug is on the consuming end and the stripping pattern is more specific than just Optional[X]:

1. Confirm the server is emitting the correct schema. Your curl against the raw tools/list response already does this — keywords arrives with anyOf: [{"items": ..., "type": "array"}, {"type": "null"}] intact. That's the proof the server is doing its job and the SDK isn't truncating mid-stream.
2. Confirm what the model actually sees. This is where Desktop diverges from CLI. The model's tool-definition view (visible in the Cowork tab's "tools available" panel when you expand a tool) shows the post-processed schema — that's where the anyOf is gone.

The pattern that's getting stripped is more specific than Optional[X] in general — based on a similar repro I worked through, the trigger is **any property-level anyOf array whose members are type schemas rather than $ref schemas**. So Optional[list[str]] (your case), Optional[dict[str, Any]], and Optional[CustomTypedDict] all hit it. Inline $ref-only anyOf (e.g. anyOf: [{"$ref": "#/$defs/Foo"}, {"$ref": "#/$defs/Bar"}]) survives — which is suggestive of where the bug lives in Desktop's preprocessing pipeline (probably a schema-flattener that drops the array when it can't reduce it to a single named type).

For other people hitting this thread: if you're not sure whether your server is upstream or downstream of the bug, MCP Inspector (@modelcontextprotocol/inspector) gives you a clickable view of the tools/list response so you can confirm the schema is intact server-side. For a one-shot non-interactive scan that records the on-wire schema for each tool, npx @incultnitostudiosllc/mcp-probe test "<launch command>" writes the resolved inputSchema to its scorecard output — useful for diffing against what Desktop ends up showing.

CLI preserving the full schema while Desktop strips it is the smoking gun — same SDK, different preprocessing path. Whichever team owns the Cowork tool-bridge layer is where the fix lives.

Confirming this on Windows with a fresh repro — same root cause (property-level anyOf: [X, null] stripped), extending the original macOS report.

Environment

• Claude Desktop on Windows; the MCP server is installed as a Claude Extension (ant.dir.cursortouch.windows-mcp).
• MCP server: Windows-MCP (CursorTouch) v0.7.1 — FastMCP + Pydantic v2, stdio.

Tool / parameter. The mouse tools Scroll / Click / Move / Type declare:

def scroll_tool(loc: list[int] | None = None, ...)

FastMCP emits the standard Optional[list] shape:

"loc": { "anyOf": [ {"type": "array", "items": {"type": "integer"}}, {"type": "null"} ], "default": null }

What reaches the model: the anyOf is stripped — only {"default": null} survives (no type). The argument [1000, 600] is then sent as the string "[1000, 600]".

Server rejection (Pydantic):

1 validation error for call[scroll_tool]
loc
  Input should be a valid list [type=list_type, input_value='[1000, 600]', input_type=str]

Two data points this adds to #56263:

1. Reproduces on Windows desktop too (the original repro was macOS).
2. Hits list[int] (coordinate pairs), not only list[str] — so it breaks even basic mouse-coordinate tools, i.e. any FastMCP tool with an optional list/tuple input.

A server-side X | str-and-coerce workaround is viable only for scalars (Windows-MCP already does this for booleans via _as_bool) but doesn't scale to lists/objects — preserving the anyOf block client-side is the real fix.

Related: #58771, #18260 ($ref variant), #26094 (object params).

Still reproduces — independent repro on a newer build with a different server stack (server-agnostic, client-side confirmed)

Hit this independently on 2026-06-22. Adds two new data points and confirms it's unfixed ~7 weeks on.

Environment

Claude Desktop 1.14271.0 (Code tab), macOS 15.5
MCP server: TypeScript — @modelcontextprotocol/sdk 1.29.0 + Zod 4.4.3, streamable-HTTP, bridged into Desktop via mcp-remote 0.1.38
Original report was FastMCP 3.2.4 + Pydantic (Python). Same bug on a completely different server stack ⇒ the trigger is purely the anyOf [X, null] JSON-Schema shape, not any server framework.
Same trigger, same strip. Param declared z.number().min(0).nullable().optional(). Server emits (verified by reproducing the SDK conversion and an in-process client.listTools()):

"amount": { "description": "Deal amount…", "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }
What the model receives in Desktop:

"amount": { "description": "Deal amount…" }
anyOf gone → LLM sends a string → server rejects expected number, received string. Passing null to clear a field is also impossible (arrives as the string "null").

New data point 1 — the client also injects additionalProperties: false. It's not only dropping the union; it overlays additionalProperties:false on the object schema. The faithful server/connector output has additionalProperties absent. So the ingestion path makes two unrequested mutations to the declared schema.

New data point 2 — a same-client A/B that isolates transport, not client. Earlier narrowing varied client and transport together (Desktop+mcp-remote vs CLI+direct-HTTP). In a single Desktop session I had the same server reachable two ways:

via mcp-remote (stdio bridge) → schema stripped
via a native Desktop HTTP connector (direct HTTP, same /api/mcp endpoint) → schema intact (anyOf preserved, no additionalProperties injected)
Same client, differing only by ingestion path ⇒ the defect is in the stdio-bridged tool-schema ingestion within the desktop client; direct-HTTP ingestion in the same client is unaffected.

mcp-remote re-confirmed innocent. Read its mcpProxy (0.1.38 — it only filters tools/list by tool name, spreads the rest verbatim) and captured its raw stdout for tools/list: full anyOf present, additionalProperties absent. That stdout is exactly the byte stream the desktop client reads, so the strip happens strictly after.

Mechanism note. The stripper drops the type-bearing combinator (anyOf/type/items) but keeps sibling scalar keywords — description always, and default when present (which is why the Python repro showed {default, description} and the TS repro showed {description}). Single-type params (e.g. { "type": "string" }) are unaffected; only union/anyOf params are lost.

Workaround that works: route the server through direct HTTP instead of the mcp-remote stdio bridge — Desktop Settings → Connectors (custom connector to the HTTPS MCP URL), or the standalone Claude Code CLI with a type:"http" server. Both preserve the full schema.

Note re: "Not affected: Claude Code CLI (preserves full schema)" (verified 2026-05-05) — I just reproduced the identical symptom today (2026-07-22) from a Claude Code session, against our own MCP server (@modelcontextprotocol/sdk 1.27.1, zod 4.3.6).

Two parameters with the same underlying shape (z.array(z.string()).max(50)), one plain-optional and one .nullable().optional(), on sibling tools in the same server:

• non-nullable: surfaced to the model correctly as {"items":{"type":"string"},"type":"array"}
• nullable (anyOf: [array, null]): surfaced to the model as a bare {} — no type info at all

Confirmed server-side the raw tools/list schema is correct in both cases (checked via the SDK's own zod-json-schema-compat.js), so the stripping is happening between that response and whatever schema Claude Code exposes to the model. Once a field is untyped like this, non-string values (arrays, numbers) get serialized as strings before the call reaches the server, which then rejects them — full detail and a second scalar (non-array) case in my comment on #73137.

Given this reproduced inside a Claude Code session, either this has regressed since the May verification, or the CLI is affected under some conditions not covered by that earlier check — flagging in case it's useful for narrowing down where the stripping actually happens.

Still reproducing four months on, and with two differences from the original report that may help
narrow it.

Environment: Claude Desktop 1.40609.1, Claude Code CLI 2.1.258, macOS 26.6.2, Python MCP SDK
1.29.1. Same A/B as this issue: server registered in claude_desktop_config.json is affected;
the same server registered with claude mcp add is not.

1. The collapse is more complete than described here

This issue reports the anyOf block being removed "leaving only default and description". In our
case the property becomes an empty object — default and description are gone too.

Server sends (verified with the mcp Python client against the live endpoint):

"pre_agg_query": {
  "anyOf": [{"type": "string"}, {"type": "null"}],
  "default": null,
  "description": "Aggregation lambda applied after the filter and before the limit, e.g. ..."
}

Model sees, via claude_desktop_config.json:

"pre_agg_query": {}

2. Descriptions are also dropped from plain-typed properties

#78237 notes that plain typed sibling fields "survive sanitization intact". That does not hold here —
they survive structurally but still lose their descriptions. On a 13-property tool:

| Property | Server sends | via claude_desktop_config.json | via claude mcp add |
|---|---|---|---|
| pre_agg_query | anyOf[string,null], default, description | {} | intact |
| run_date | anyOf[string(format:date),null], description | {} | intact |
| limit | type:integer, default:10, description | {"default":10,"type":"number"} | intact |
| base | type:string, enum[4], default, description | {"default":"ALERTS","enum":[…],"type":"string"} | intact |

So on the affected path the transformation is: every properties[*].description removed regardless of
type; property-level anyOf collapsed to {}; integer → number; format: date dropped; and a
$schema: "http://json-schema.org/draft-07/schema#" key added that the server never sent.

Worth stressing that the tool-level description survives intact on both paths. That is what makes
this so easy to miss — the model still gets the tool summary and only the per-parameter contract is
missing, so it confabulates parameter syntax instead of failing loudly.

3. Minimal reproducer — one tool, one parameter

from typing import Optional

from mcp.server.fastmcp import FastMCP
from pydantic import Field

mcp = FastMCP("schema-repro")


@mcp.tool()
def echo_note(
    note: Optional[str] = Field(
        None,
        description=(
            "SENTINEL-DESCRIPTION-VISIBLE: if the model can read this sentence, "
            "the client preserved the parameter description."
        ),
    ),
) -> str:
    """Echo a note back. The tool-level description survives; the parameter one does not."""
    return f"note={note!r}"


if __name__ == "__main__":
    mcp.run()

Register it in claude_desktop_config.json with an absolute interpreter path, fully quit and relaunch
Desktop, then ask: *"What is the description of the note parameter of echo_note? Quote it
verbatim."* The sentinel is unreachable. Register the identical command with
claude mcp add schema-repro -- /abs/python /abs/server.py and it comes back word for word.

Why this bites hard in practice

On the server this was found with, two parameters accept a sandboxed lambda expression, and the entire
grammar of what is accepted lives in their descriptions. With those stripped the model invents syntax,
every call is rejected by the server's validator, and neither the user nor the server author can see
why — the server logs a rejected query and the schema looks fine from its side.

Two things it is not, both checked: not content filtering (limit's description is plain prose and
is dropped, while the tool-level description containing literal lambda code samples survives), and not
a trust rule for third-party servers (a third-party npx -y @zereight/mcp-gitlab registered through
Claude Code keeps its descriptions and its anyOf).