JSON schema compatibility issues

MCP Server
1

With a minimal reproduction, it seems that the JSON schema produced by Apollo Server isn’t compatible with eg Mastra’s MCP client since inputs that require “definitions” are not strictly adhering to the MCP spec and are being stripped by the @modelcontextprotocol/sdk/client. This means clients/frameworks that then need to dereference the JSON schema to propose zod definitions like Mastra does cannot load these tools.

Schema:

input OperationInput {
  text: String!
}

type OperationResult {
  result: Boolean!
}

type Query {
  operation(input: OperationInput!): OperationResult
}

... and then a tool

query Operation($input: OperationInput!) {
    operation(input: $input) {
        result
    }
}
2

Hi @glenn for reporting this issue. We’ve seen similar problems from customers using other MCP clients and open-source AI models. This is a known limitation across the MCP ecosystem, not specific to our implementation.

As a quick workaround, we suggest using more popular MCP clients such as Claude Desktop, Cursor and Goose which properly handles JSON schemas with $ref definitions and supports the full JSON Schema specification. These clients have proven to be the most compatible choice for MCP integrations with complex schemas.

For a long-term solution, we’ve added schema flattening (converting $ref references to inline schemas) to our product backlog. This will generate flattened tools instead of using references:

Current (with $ref):

{
  "properties": {
    "input": {"$ref": "#/definitions/OperationInput"}
  },
  "definitions": {
    "OperationInput": {
      "type": "object",
      "properties": {"text": {"type": "string"}}
    }
  }
}

Future (flattened):

{
  "properties": {
    "input": {
      "type": "object",
      "properties": {"text": {"type": "string"}}
    }
  }
}