MCP schema is non-deterministic

[tonybaloney]

Description

I noticed that the logfire remote MCP server tools/list API returns the response in a slightly different order about 6% of the time.

I don't know how the schema is being serialized, but my guess is that whatever you're using for a hashmap is not a stable, ordered map.

This matters because Claude Code, GitHub Copilot, Codex etc. give a 90% discount to cached input tokens, but the logfire schema changes every few calls which invalidates a ~2,000 token chunk of the cache (and costs more money).

Python, Logfire & OS Versions, related packages (not required)

[hramezani]

Thanks @tonybaloney for reporting this. We will investigate the problem and update you here!

[tonybaloney]

I would appreciate understanding the root cause if you can share that as well.

[hramezani]

I investigated the problem but couldn't find the root cause TBH. I also couldn't reproduce the problem locally.

So, I am going to sort the tools alphabetically in the tools list. it will be available on production next week. I will let you know here.

I would appreciate more info to help us debug the problem.

Thanks!

[tonybaloney]

Some additional concrete details that might help locate the offending code path:

The flap is all-or-nothing across every tool the server returns — when it happens, all 49 logfire tools in tools/list change shape together. That points at a single shared serialization decision (per process or per request), not anything tool-specific.

The change is in the order of keys inside parameters, with identical content otherwise:

Form A (observed in most calls):

"parameters": {
  "type": "object",
  "properties": { ... },
  "required": [ ... ],
  "additionalProperties": false
}

Form B (observed in ~6% of calls):

"parameters": {
  "additionalProperties": false,
  "properties": { ... },
  "required": [ ... ],
  "type": "object"
}

So the key set is {type, properties, required, additionalProperties} in both cases; only the ordering differs. SHA-1 of the full tools/list response varies between exactly two distinct hashes across many calls — never a third one — which suggests two specific code paths producing the same logical schema, rather than truly random hash-map iteration.

Because clients (and the upstream provider caches) only see the JSON bytes, even though the semantic content is identical the byte-exact cache match fails. Most provider caches operate at 128-token block granularity, so the disturbed region propagates down through the entire tools blob — which is why a ~2,000-token chunk drops out per flap.

If it helps narrow it down: Form B has additionalProperties as the first key of parameters, which is unusual for both Pydantic model_json_schema() output (which normally starts with properties or type) and for json.dumps(sort_keys=True) (which would put additionalProperties first alphabetically and sort properties/required/type, but that doesn't match what's observed either since the four-key order in Form B isn't alphabetical). The Form B order looks like what you'd get from a dict constructed in this specific sequence:

schema = {"additionalProperties": False}
schema["properties"] = ...
schema["required"] = ...
schema["type"] = "object"

i.e. an additionalProperties flag set first (possibly from extra="forbid" config), then fields appended, then type patched in at the end. Whereas Form A looks like the natural Pydantic ordering with additionalProperties appended at the end.

A workaround on the client side is to canonicalise key order before sending the schema upstream, but it would be much more efficient if the server emitted bytes deterministically in the first place.

[hramezani]

Thanks for the detailed report — your follow-up message was really helpful in narrowing this down.

We've merged a fix and it will be available in the next release. I'll follow up here once it's deployed to production.

[hramezani]

@tonybaloney, the PRs have been deployed on prod.

Please check it when you have time and let us know.

Thanks!