Tool schema validation errors

[Ebruzzone]

Tool schema validation errors starting January 7, 2026

Description

Starting from January 7, 2026, several tools from this MCP server are failing with schema validation errors when used with Anthropic's Claude API (via Azure). The errors specifically mention invalid $ref references in the JSON schema.

Error Examples

Tool: send-mail

Invalid $ref in schema: '#/properties/body/properties/Message/properties/bccRecipients/items' 
does not exist. Ensure all $ref targets are defined in the schema's definitions or $defs.

Tool: update-calendar-event

Invalid $ref in schema: '#/properties/body/properties/attendees/items/properties/proposedNewTime/properties/end' 
does not exist. Ensure all $ref targets are defined in the schema's definitions or $defs.

Exception Example

Anthropic.Exceptions.AnthropicBadRequestException: Status Code: BadRequest
{"type":"error","error":{"type":"invalid_request_error","message":"tools.3.custom.input_schema: Invalid $ref in schema: '#/properties/body/properties/attendees/items/properties/proposedNewTime/properties/end' does not exist. Ensure all $ref targets are defined in the schema's definitions or $defs.. Learn more about tool use at https://docs.claude.com/en/docs/tool-use."},"request_id":"req_011CWtKtLQAGPXHYXjkrwzQy"}
   at Anthropic.AnthropicClient.Execute[T](HttpRequest`1 request, CancellationToken cancellationToken) in /home/runner/work/anthropic-sdk-csharp/anthropic-sdk-csharp/src/Anthropic/AnthropicClient.cs:line 137
   at Anthropic.Services.MessageService.Create(MessageCreateParams parameters, CancellationToken cancellationToken) in /home/runner/work/anthropic-sdk-csharp/anthropic-sdk-csharp/src/Anthropic/Services/MessageService.cs:line 49
   at Microsoft.Extensions.AI.AnthropicClientExtensions.AnthropicChatClient.GetResponseAsync(IEnumerable`1 messages, ChatOptions options, CancellationToken cancellationToken) in /home/runner/work/anthropic-sdk-csharp/anthropic-sdk-csharp/src/Anthropic/AnthropicClientExtensions.cs:line 156
   at Microsoft.Extensions.AI.LoggingChatClient.GetResponseAsync(IEnumerable`1 messages, ChatOptions options, CancellationToken cancellationToken)

Environment

• MCP Server: Tested with both older and latest versions
• LLM Provider: Anthropic Claude (via Azure)
• Date issue started: January 7, 2026
• Previous behavior: All tools worked correctly until January 6, 2026

Observations

• The issue appears to affect multiple MS365 tools (at least send-mail and update-calendar-event confirmed)
• Other MCP servers (like DBHub) continue to work without issues
• The tools' schemas haven't changed, suggesting a change in the LLM provider's validation

Questions

• Are you experiencing similar validation errors with your deployments?
• Have you tested these tools with other LLM providers (OpenAI, etc.) recently?
• Are there plans to update the tool schemas to address stricter validation requirements?

[eirikb]

Is this an Azure issue?

Must I use Azure to replicate this, or can I do it locally?

The server works fine locally for me:

> send a funny email to eirikb@eirikb.no - make up subject and body ;) oh and make it a real good joke about programming

● ms - send-mail (MCP)(body: {"Message":{"subject":"Why do programmers prefer dark mode?","body":{"contentType":"text","content":"Because light attracts bugs.\n\n---\n\nBonus joke:\n\nA SQL query walks into a
                      bar, walks up to two tables and asks...\n\"Can I join you?\"\n\n---\n\nAnd one more for the road:\n\nThere are only 10 types of people in the world:\nThose who understand binary, those who
                      don't, and those who didn't expect this joke to be in base 3.\n\n---\n\nHave a great day!\n\n// This email was sent without any unit
                      tests"},"toRecipients":[{"emailAddress":{"address":"eirikb@eirikb.no","name":"Eirik"}}]}})
  ⎿  {
       "message": "OK!"
     }

● Done! Sent a programming joke email to eirikb@eirikb.no with:

  Subject: Why do programmers prefer dark mode?

  Body:
  Because light attracts bugs.

  ---A SQL query walks into a bar, walks up to two tables and asks...
  "Can I join you?"

  ---There are only 10 types of people in the world:
  Those who understand binary, those who don't, and those who didn't expect this joke to be in base 3.

  ---// This email was sent without any unit tests


> /status
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 Settings:  Status   Config   Usage  (tab to cycle)

 Version: 2.0.76

[Ebruzzone]

Thanks for the quick test! The fact that it works locally for you confirms the MCP server itself is fine.
I believe this might be related to stricter schema validation recently implemented by Claude's API rather than an Azure-specific issue. The timing (January 7, 2026) coincides with some infrastructure changes on the Anthropic/Microsoft side.
To help narrow it down:

Could you test directly against Claude's API (via Anthropic's endpoint, not through your local client) to see if the validation error appears there too?
I'm using Claude via Azure, but the error message comes directly from Anthropic's framework API validation

The tools work fine with other LLM providers, which suggests this is specific to how Claude's API validates the $ref in JSON schemas. It's possible the validation was updated and the change propagated to production endpoints on January 7th.
I can provide more details about the exact schema structure if that helps, but I wanted to check if you can replicate it when calling Claude's API directly first.
Thanks again for looking into this!

[eirikb]

I tried to investigate this a bit more, and it seems the json schema we make is broken.
This would be the schema sent to clients from the server.

We provide a Zod, a correct zod that is, but the MCP SDK spits out wrong paths on $ref.
At least it looks like that for me.

I actually don't know why claude code works locally, but it might be just lenient and guessing the type and doing a good job at it. At least it works - or seems to work.

So - who's fault is it really? I think it is: zod-to-json-schema which is what @modelcontextprotocol/sdk uses to make the schema. I believe it is related to this: StefanTerdell/zod-to-json-schema#77
But to fix this the MCP SDK has to either set $refStrategy to none or set a basePath - it does neither.

[Ebruzzone]

Thanks for the investigation! That makes sense - so it's an issue in the MCP SDK's usage of zod-to-json-schema that generates invalid $ref paths.
My workaround plan:
I'm thinking of creating a middleware layer that:

• Fetches tools from your MCP server
• Processes the schemas to expand/remove the problematic $ref paths
• Re-exposes the tools with corrected schemas to my application
• Maps the tool calls back to your original MCP server

Would this approach work, or are there any issues I should be aware of when doing this kind of schema transformation?

Is there a way to force the MCP SDK to output schemas without $ref (like setting $refStrategy: "none") that I could try locally, or would that require changes to your build process?

If I understand, I can use the workaround while waiting for a proper fix upstream in the MCP SDK or zod-to-json-schema.

[Ebruzzone]

I confirm that the workaround works. So for now it isn't problematic for us anymore.

[eirikb]

I confirm that the workaround works. So for now it isn't problematic for us anymore.

I wonder - should someone (you?) create an issue on the MCP SDK? Would that make sense?
I mean all they need to do is to add a flag and it will work fine, and the only reason they haven't done this before is that nobody has had the issue (or noticed it before)?