Schema error using MCP server with Gemini 2.5

[rectalogic]

Initial Checks

• I confirm that I'm using the latest version of Pydantic AI
• I confirm that I searched for my issue in https://github.com/pydantic/pydantic-ai/issues before opening this issue

Description

Gemini chokes on $schema in the JSON schema returned by MCP servers.

> GEMINI_API_KEY=XXX uv run --with pydantic-ai client.py
Secure MCP Filesystem Server running on stdio
Allowed directories: [ '/private/tmp' ]
Traceback (most recent call last):
  File "/private/tmp/client.py", line 15, in <module>
    asyncio.run(main())
  File "/Users/aw/.local/share/uv/python/cpython-3.11.10-macos-aarch64-none/lib/python3.11/asyncio/runners.py", line 190, in run
    return runner.run(main)
           ^^^^^^^^^^^^^^^^
  File "/Users/aw/.local/share/uv/python/cpython-3.11.10-macos-aarch64-none/lib/python3.11/asyncio/runners.py", line 118, in run
    return self._loop.run_until_complete(task)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/aw/.local/share/uv/python/cpython-3.11.10-macos-aarch64-none/lib/python3.11/asyncio/base_events.py", line 654, in run_until_complete
    return future.result()
           ^^^^^^^^^^^^^^^
  File "/private/tmp/client.py", line 11, in main
    result = await agent.run('Summarize the file client.py')
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/aw/Library/Caches/uv/archive-v0/UT4lACLsamDruEsIvP3Xe/lib/python3.11/site-packages/pydantic_ai/agent.py", line 327, in run
    async for _ in agent_run:
  File "/Users/aw/Library/Caches/uv/archive-v0/UT4lACLsamDruEsIvP3Xe/lib/python3.11/site-packages/pydantic_ai/agent.py", line 1414, in __anext__
    next_node = await self._graph_run.__anext__()
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/aw/Library/Caches/uv/archive-v0/UT4lACLsamDruEsIvP3Xe/lib/python3.11/site-packages/pydantic_graph/graph.py", line 782, in __anext__
    return await self.next(self._next_node)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/aw/Library/Caches/uv/archive-v0/UT4lACLsamDruEsIvP3Xe/lib/python3.11/site-packages/pydantic_graph/graph.py", line 760, in next
    self._next_node = await node.run(ctx)
                      ^^^^^^^^^^^^^^^^^^^
  File "/Users/aw/Library/Caches/uv/archive-v0/UT4lACLsamDruEsIvP3Xe/lib/python3.11/site-packages/pydantic_ai/_agent_graph.py", line 262, in run
    return await self._make_request(ctx)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/aw/Library/Caches/uv/archive-v0/UT4lACLsamDruEsIvP3Xe/lib/python3.11/site-packages/pydantic_ai/_agent_graph.py", line 314, in _make_request
    model_response, request_usage = await ctx.deps.model.request(
                                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/aw/Library/Caches/uv/archive-v0/UT4lACLsamDruEsIvP3Xe/lib/python3.11/site-packages/pydantic_ai/models/gemini.py", line 131, in request
    async with self._make_request(
  File "/Users/aw/.local/share/uv/python/cpython-3.11.10-macos-aarch64-none/lib/python3.11/contextlib.py", line 210, in __aenter__
    return await anext(self.gen)
           ^^^^^^^^^^^^^^^^^^^^^
  File "/Users/aw/Library/Caches/uv/archive-v0/UT4lACLsamDruEsIvP3Xe/lib/python3.11/site-packages/pydantic_ai/models/gemini.py", line 227, in _make_request
    raise ModelHTTPError(status_code=status_code, model_name=self.model_name, body=r.text)
pydantic_ai.exceptions.ModelHTTPError: status_code: 400, model_name: gemini-2.5-pro-exp-03-25, body: {
  "error": {
    "code": 400,
    "message": "Invalid JSON payload received. Unknown name \"$schema\" at 'tools.function_declarations[0].parameters': Cannot find field.\nInvalid JSON payload received. Unknown name \"$schema\" at 'tools.function_declarations[1].parameters': Cannot find field.\nInvalid JSON payload received. Unknown name \"$schema\" at 'tools.function_declarations[2].parameters': Cannot find field.\nInvalid JSON payload received. Unknown name \"$schema\" at 'tools.function_declarations[3].parameters': Cannot find field.\nInvalid JSON payload received. Unknown name \"$schema\" at 'tools.function_declarations[4].parameters': Cannot find field.\nInvalid JSON payload received. Unknown name \"$schema\" at 'tools.function_declarations[5].parameters': Cannot find field.\nInvalid JSON payload received. Unknown name \"$schema\" at 'tools.function_declarations[6].parameters': Cannot find field.\nInvalid JSON payload received. Unknown name \"$schema\" at 'tools.function_declarations[7].parameters': Cannot find field.\nInvalid JSON payload received. Unknown name \"$schema\" at 'tools.function_declarations[8].parameters': Cannot find field.\nInvalid JSON payload received. Unknown name \"$schema\" at 'tools.function_declarations[9].parameters': Cannot find field.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "tools.function_declarations[0].parameters",
            "description": "Invalid JSON payload received. Unknown name \"$schema\" at 'tools.function_declarations[0].parameters': Cannot find field."
          },
          {
            "field": "tools.function_declarations[1].parameters",
            "description": "Invalid JSON payload received. Unknown name \"$schema\" at 'tools.function_declarations[1].parameters': Cannot find field."
          },
          {
            "field": "tools.function_declarations[2].parameters",
            "description": "Invalid JSON payload received. Unknown name \"$schema\" at 'tools.function_declarations[2].parameters': Cannot find field."
          },
          {
            "field": "tools.function_declarations[3].parameters",
            "description": "Invalid JSON payload received. Unknown name \"$schema\" at 'tools.function_declarations[3].parameters': Cannot find field."
          },
          {
            "field": "tools.function_declarations[4].parameters",
            "description": "Invalid JSON payload received. Unknown name \"$schema\" at 'tools.function_declarations[4].parameters': Cannot find field."
          },
          {
            "field": "tools.function_declarations[5].parameters",
            "description": "Invalid JSON payload received. Unknown name \"$schema\" at 'tools.function_declarations[5].parameters': Cannot find field."
          },
          {
            "field": "tools.function_declarations[6].parameters",
            "description": "Invalid JSON payload received. Unknown name \"$schema\" at 'tools.function_declarations[6].parameters': Cannot find field."
          },
          {
            "field": "tools.function_declarations[7].parameters",
            "description": "Invalid JSON payload received. Unknown name \"$schema\" at 'tools.function_declarations[7].parameters': Cannot find field."
          },
          {
            "field": "tools.function_declarations[8].parameters",
            "description": "Invalid JSON payload received. Unknown name \"$schema\" at 'tools.function_declarations[8].parameters': Cannot find field."
          },
          {
            "field": "tools.function_declarations[9].parameters",
            "description": "Invalid JSON payload received. Unknown name \"$schema\" at 'tools.function_declarations[9].parameters': Cannot find field."
          }
        ]
      }
    ]
  }
}

Example Code

import asyncio
from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStdio

server = MCPServerStdio('npx', ['-y', '@modelcontextprotocol/server-filesystem', '.'])
agent = Agent('gemini-2.5-pro-exp-03-25', mcp_servers=[server])


async def main():
    async with agent.run_mcp_servers():
        result = await agent.run('Summarize the file client.py')
    print(result.data)

if __name__ == "__main__":
    asyncio.run(main())

Python, Pydantic AI & LLM client version

Python 3.11.10
Pydantic 0.0.44
LLM gemini-2.5-pro-exp-03-25

[Kludex]

That issue unfortunately is because the MCP server generates a more complete JSON schema, and Gemini doesn't support that.

[rectalogic]

Hmm, Gemini docs say they support "a select subset of the OpenAPI schema format". And I don't see $schema in that subset.
https://ai.google.dev/gemini-api/docs/function-calling#function_declarations

Is there any way in pydantic-ai to modify the schema returned from the MCP server to remove any $schema keys before it is sent to the LLM? e.g. post-process the ToolDefinition instances and modify their schemas?

[rectalogic]

OK, I was able to get it working with Gemini by subclassing the MCPServers to post-process the ToolDefinition:

import typing as t

from pydantic_ai.mcp import MCPServerHTTP, MCPServerStdio
from pydantic_ai.tools import ToolDefinition


class MCPServerMixin(MCPServer):
    @t.override
    async def list_tools(self) -> list[ToolDefinition]:
        return [self._modify_schema(tool) for tool in await super().list_tools()]

    def _modify_schema(self, tool: ToolDefinition) -> ToolDefinition:
        tool.parameters_json_schema.pop("$schema", None)
        return tool


class MCPServerStdioSchema(MCPServerMixin, MCPServerStdio):
    pass


class MCPServerHTTPSchema(MCPServerMixin, MCPServerHTTP):
    pass

[TensorTemplar]

This affects all GoogleGLAProvider models in 0.46, not only Gemini 2.5

[Kludex]

• I've implemented the fix on Drop JSON schema url from schema on Gemini #1342. 🙏