GraphQL Variables Meet JSON Schema: The New Pitfall When AI Agents Call Your API

When an MCP server exposes a GraphQL operation as a tool for AI agents, the operation's variables get turned into a JSON Schema, and that schema is what the agent sees. The two type systems look close enough that the translation seems mechanical. It isn't, and the gaps are easy to miss because nothing fails loudly.

Take a variable with a default value. GraphQL fills in the default when the caller leaves the variable out, but in JSON Schema a default is only a hint, and validators ignore it. Or take Int: GraphQL caps it at 32 bits, while JSON Schema's integer has no limit unless the generator adds one. So which contract is the real one? MCP says servers must validate tool inputs, but not against what.

We'll go through a set of these cases, look at how a few open-source GraphQL and OpenAPI MCP generators handle them, and work out which gaps a better generator could close, which come with the type systems, and which are decisions someone has to make on purpose. If you're putting a GraphQL API in front of agents, it should help you decide which parts of a generated schema to trust.