Support OpenAI and Anthropic native MCP support via MCPServerTool builtin tool (#3101)

Co-authored-by: Douwe Maan <[email protected]>
Co-authored-by: Param <[email protected]>

Author: 3 people

docs/builtin-tools.md

@@ -11,6 +11,7 @@ Pydantic AI supports the following built-in tools:
 - **[`ImageGenerationTool`][pydantic_ai.builtin_tools.ImageGenerationTool]**: Enables agents to generate images
 - **[`UrlContextTool`][pydantic_ai.builtin_tools.UrlContextTool]**: Enables agents to pull URL contents into their context
 - **[`MemoryTool`][pydantic_ai.builtin_tools.MemoryTool]**: Enables agents to use memory
+- **[`MCPServerTool`][pydantic_ai.builtin_tools.MCPServerTool]**: Enables agents to use remote MCP servers with communication handled by the model provider
 
 These tools are passed to the agent via the `builtin_tools` parameter and are executed by the model provider's infrastructure.
 
@@ -52,7 +53,7 @@ print(result.output)
 
 _(This example is complete, it can be run "as is")_
 
-With OpenAI, you must use their responses API to access the web search tool.
+With OpenAI, you must use their Responses API to access the web search tool.
 
 ```py {title="web_search_openai.py"}
 from pydantic_ai import Agent, WebSearchTool
@@ -419,6 +420,149 @@ print(result.output)
 
 _(This example is complete, it can be run "as is")_
 
+## MCP Server Tool
+
+The [`MCPServerTool`][pydantic_ai.builtin_tools.MCPServerTool] allows your agent to use remote MCP servers with communication handled by the model provider.
+
+This requires the MCP server to live at a public URL the provider can reach and does not support many of the advanced features of Pydantic AI's agent-side [MCP support](mcp/client.md),
+but can result in optimized context use and caching, and faster performance due to the lack of a round-trip back to Pydantic AI.
+
+### Provider Support
+
+| Provider | Supported | Notes                 |
+|----------|-----------|-----------------------|
+| OpenAI Responses | ✅ | Full feature support. [Connectors](https://platform.openai.com/docs/guides/tools-connectors-mcp#connectors) can be used by specifying a special `x-openai-connector:<connector_id>` URL.  |
+| Anthropic | ✅ | Full feature support |
+| Google  | ❌ | Not supported |
+| Groq  | ❌ | Not supported |
+| OpenAI Chat Completions | ❌ | Not supported |
+| Bedrock | ❌ | Not supported |
+| Mistral | ❌ | Not supported |
+| Cohere | ❌ | Not supported |
+| HuggingFace | ❌ | Not supported |
+
+### Usage
+
+```py {title="mcp_server_anthropic.py"}
+from pydantic_ai import Agent, MCPServerTool
+
+agent = Agent(
+    'anthropic:claude-sonnet-4-5',
+    builtin_tools=[
+        MCPServerTool(
+            id='deepwiki',
+            url='https://mcp.deepwiki.com/mcp',  # (1)
+        )
+    ]
+)
+
+result = agent.run_sync('Tell me about the pydantic/pydantic-ai repo.')
+print(result.output)
+"""
+The pydantic/pydantic-ai repo is a Python agent framework for building Generative AI applications.
+"""
+```
+
+1. The [DeepWiki MCP server](https://docs.devin.ai/work-with-devin/deepwiki-mcp) does not require authorization.
+
+_(This example is complete, it can be run "as is")_
+
+With OpenAI, you must use their Responses API to access the MCP server tool:
+
+```py {title="mcp_server_openai.py"}
+from pydantic_ai import Agent, MCPServerTool
+
+agent = Agent(
+    'openai-responses:gpt-5',
+    builtin_tools=[
+        MCPServerTool(
+            id='deepwiki',
+            url='https://mcp.deepwiki.com/mcp',  # (1)
+        )
+    ]
+)
+
+result = agent.run_sync('Tell me about the pydantic/pydantic-ai repo.')
+print(result.output)
+"""
+The pydantic/pydantic-ai repo is a Python agent framework for building Generative AI applications.
+"""
+```
+
+1. The [DeepWiki MCP server](https://docs.devin.ai/work-with-devin/deepwiki-mcp) does not require authorization.
+
+_(This example is complete, it can be run "as is")_
+
+### Configuration Options
+
+The `MCPServerTool` supports several configuration parameters for custom MCP servers:
+
+```py {title="mcp_server_configured_url.py"}
+import os
+
+from pydantic_ai import Agent, MCPServerTool
+
+agent = Agent(
+    'openai-responses:gpt-5',
+    builtin_tools=[
+        MCPServerTool(
+            id='github',
+            url='https://api.githubcopilot.com/mcp/',
+            authorization_token=os.getenv('GITHUB_ACCESS_TOKEN', 'mock-access-token'),  # (1)
+            allowed_tools=['search_repositories', 'list_commits'],
+            description='GitHub MCP server',
+            headers={'X-Custom-Header': 'custom-value'},
+        )
+    ]
+)
+
+result = agent.run_sync('Tell me about the pydantic/pydantic-ai repo.')
+print(result.output)
+"""
+The pydantic/pydantic-ai repo is a Python agent framework for building Generative AI applications.
+"""
+```
+
+1. The [GitHub MCP server](https://github.com/github/github-mcp-server) requires an authorization token.
+
+For OpenAI Responses, you can use a [connector](https://platform.openai.com/docs/guides/tools-connectors-mcp#connectors) by specifying a special `x-openai-connector:` URL:
+
+_(This example is complete, it can be run "as is")_
+
+```py {title="mcp_server_configured_connector_id.py"}
+import os
+
+from pydantic_ai import Agent, MCPServerTool
+
+agent = Agent(
+    'openai-responses:gpt-5',
+    builtin_tools=[
+        MCPServerTool(
+            id='google-calendar',
+            url='x-openai-connector:connector_googlecalendar',
+            authorization_token=os.getenv('GOOGLE_API_KEY', 'mock-api-key'), # (1)
+        )
+    ]
+)
+
+result = agent.run_sync('What do I have on my calendar today?')
+print(result.output)
+#> You're going to spend all day playing with Pydantic AI.
+```
+
+1. OpenAI's Google Calendar connector requires an [authorization token](https://platform.openai.com/docs/guides/tools-connectors-mcp#authorizing-a-connector).
+
+_(This example is complete, it can be run "as is")_
+
+#### Provider Support
+
+| Parameter             | OpenAI | Anthropic |
+|-----------------------|--------|-----------|
+| `authorization_token` | ✅ | ✅ |
+| `allowed_tools`       | ✅ | ✅ |
+| `description`         | ✅ | ❌ |
+| `headers`             | ✅ | ❌ |
+
 ## API Reference
 
 For complete API documentation, see the [API Reference](api/builtin_tools.md).

docs/mcp/overview.md

@@ -2,7 +2,9 @@
 
 Pydantic AI supports [Model Context Protocol (MCP)](https://modelcontextprotocol.io) in two ways:
 
-1. [Agents](../agents.md) act as an MCP Client, connecting to MCP servers to use their tools, [learn more …](client.md)
+1. [Agents](../agents.md) can connect to MCP servers and user their tools
+    1. Pydantic AI can act as an MCP client and connect directly to local and remote MCP servers, [learn more …](client.md)
+    2. Some model providers can themselves connect to remote MCP servers, [learn more …](../builtin-tools.md#mcp-server-tool)
 2. Agents can be used within MCP servers, [learn more …](server.md)
 
 ## What is MCP?

docs/models/google.md

@@ -140,7 +140,7 @@ agent = Agent(model)
 
 #### Customizing Location or Project
 
-You can specify the location and/or projectwhen using Vertex AI:
+You can specify the location and/or project when using Vertex AI:
 
 ```python {title="google_model_location.py" test="skip"}
 from pydantic_ai import Agent

pydantic_ai_slim/pydantic_ai/__init__.py

@@ -12,6 +12,7 @@
 from .builtin_tools import (
     CodeExecutionTool,
     ImageGenerationTool,
+    MCPServerTool,
     MemoryTool,
     UrlContextTool,
     WebSearchTool,
@@ -213,6 +214,7 @@
     'CodeExecutionTool',
     'ImageGenerationTool',
     'MemoryTool',
+    'MCPServerTool',
     # output
     'ToolOutput',
     'NativeOutput',

pydantic_ai_slim/pydantic_ai/builtin_tools.py

@@ -16,6 +16,7 @@
     'UrlContextTool',
     'ImageGenerationTool',
     'MemoryTool',
+    'MCPServerTool',
 )
 
 _BUILTIN_TOOL_TYPES: dict[str, type[AbstractBuiltinTool]] = {}
@@ -263,6 +264,64 @@ class MemoryTool(AbstractBuiltinTool):
     """The kind of tool."""
 
 
+@dataclass(kw_only=True)
+class MCPServerTool(AbstractBuiltinTool):
+    """A builtin tool that allows your agent to use MCP servers.
+
+    Supported by:
+
+    * OpenAI Responses
+    * Anthropic
+    """
+
+    id: str
+    """The ID of the MCP server."""
+
+    url: str
+    """The URL of the MCP server to use.
+
+    For OpenAI Responses, it is possible to use `connector_id` by providing it as `x-openai-connector:<connector_id>`.
+    """
+
+    authorization_token: str | None = None
+    """Authorization header to use when making requests to the MCP server.
+
+    Supported by:
+
+    * OpenAI Responses
+    * Anthropic
+    """
+
+    description: str | None = None
+    """A description of the MCP server.
+
+    Supported by:
+
+    * OpenAI Responses
+    """
+
+    allowed_tools: list[str] | None = None
+    """A list of tools that the MCP server can use.
+
+    Supported by:
+
+    * OpenAI Responses
+    * Anthropic
+    """
+
+    headers: dict[str, str] | None = None
+    """Optional HTTP headers to send to the MCP server.
+
+    Use for authentication or other purposes.
+
+    Supported by:
+
+    * OpenAI Responses
+    """
+
+    kind: str = 'mcp_server'
+
+
 def _tool_discriminator(tool_data: dict[str, Any] | AbstractBuiltinTool) -> str:
     if isinstance(tool_data, dict):
         return tool_data.get('kind', AbstractBuiltinTool.kind)