feature: Native MCP support

Author: Artui

README.md

@@ -39,7 +39,7 @@ We built Pydantic AI with one simple aim: to bring that FastAPI feeling to GenAI
 [Pydantic Validation](https://docs.pydantic.dev/latest/) is the validation layer of the OpenAI SDK, the Google ADK, the Anthropic SDK, LangChain, LlamaIndex, AutoGPT, Transformers, CrewAI, Instructor and many more. _Why use the derivative when you can go straight to the source?_ :smiley:
 
 2. **Model-agnostic**:
-Supports virtually every [model](https://ai.pydantic.dev/models/overview) and provider: OpenAI, Anthropic, Gemini, DeepSeek, Grok, Cohere, Mistral, and Perplexity; Azure AI Foundry, Amazon Bedrock, Google Vertex AI, Ollama, LiteLLM, Groq, OpenRouter, Together AI, Fireworks AI, Cerebras, Hugging Face, GitHub, Heroku, Vercel, Nebius. If your favorite model or provider is not listed, you can easily implement a [custom model](https://ai.pydantic.dev/models/overview#custom-models).
+Supports virtually every [model](https://ai.pydantic.dev/models/overview) and provider: OpenAI, Anthropic, Gemini, DeepSeek, Grok, Cohere, Mistral, and Perplexity; Azure AI Foundry, Amazon Bedrock, Google Vertex AI, Ollama, LiteLLM, Groq, OpenRouter, Together AI, Fireworks AI, Cerebras, Hugging Face, GitHub, Heroku, Vercel. If your favorite model or provider is not listed, you can easily implement a [custom model](https://ai.pydantic.dev/models/overview#custom-models).
 
 3. **Seamless Observability**:
 Tightly [integrates](https://ai.pydantic.dev/logfire) with [Pydantic Logfire](https://pydantic.dev/logfire), our general-purpose OpenTelemetry observability platform, for real-time debugging, evals-based performance monitoring, and behavior, tracing, and cost tracking. If you already have an observability platform that supports OTel, you can [use that too](https://ai.pydantic.dev/logfire#alternative-observability-backends).

docs/api/providers.md

@@ -41,5 +41,3 @@
 ::: pydantic_ai.providers.ollama.OllamaProvider
 
 ::: pydantic_ai.providers.litellm.LiteLLMProvider
-
-::: pydantic_ai.providers.nebius.NebiusProvider

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 pass MCP server configuration in context
 
 These tools are passed to the agent via the `builtin_tools` parameter and are executed by the model provider's infrastructure.
 
@@ -419,6 +420,121 @@ 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 pass MCP configurations in context,
+so that the agent can offload MCP calls and parsing to the provider.
+
+This tool is useful for models that support passing MCP servers as tools in parameters, so the model handles calls to remote servers by itself.
+
+However, a vast majority of models do not support this feature, in which case can use Pydantic AI's agent-side [MCP support](mcp/client.md).
+
+### Provider Support
+
+| Provider | Supported | Notes                 |
+|----------|-----------|-----------------------|
+| OpenAI Responses | ✅ | Full feature support  |
+| 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"}
+import os
+
+from pydantic_ai import Agent, MCPServerTool
+
+agent = Agent(
+    'anthropic:claude-sonnet-4-0',
+    builtin_tools=[
+        MCPServerTool(
+            id='your-mcp-server',
+            url='https://api.githubcopilot.com/mcp/',
+            authorization_token=os.getenv('GITHUB_ACCESS_TOKEN', 'mock-access-token'),
+            allowed_tools=['search_repositories', 'list_commits'],
+        )
+    ]
+)
+
+result = agent.run_sync('Give me some examples of my products.')
+print(result.output)
+#> Here are some examples of my data: Pen, Paper, Pencil.
+```
+
+_(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"}
+import os
+
+from pydantic_ai import Agent, MCPServerTool
+
+agent = Agent(
+    'openai-responses:gpt-4o',
+    builtin_tools=[
+        MCPServerTool(
+            id='your-mcp-server',
+            url='https://api.githubcopilot.com/mcp/',
+            authorization_token=os.getenv('GITHUB_ACCESS_TOKEN', 'mock-access-token'),
+            allowed_tools=['search_repositories', 'list_commits'],
+        )
+    ]
+)
+
+result = agent.run_sync('Give me some examples of my products.')
+print(result.output)
+#> Here are some examples of my data: Pen, Paper, Pencil.
+```
+
+_(This example is complete, it can be run "as is")_
+
+### Configuration Options
+
+The `MCPServerTool` supports several configuration parameters:
+
+```py {title="mcp_server_configured.py"}
+import os
+
+from pydantic_ai import Agent, MCPServerTool
+
+agent = Agent(
+    'openai-responses:gpt-4o',
+    builtin_tools=[
+        MCPServerTool(
+            id='your-mcp-server',
+            url='https://api.githubcopilot.com/mcp/',
+            authorization_token=os.getenv('GITHUB_ACCESS_TOKEN', 'mock-access-token'),
+            allowed_tools=['search_repositories', 'list_commits'],
+            description='Your MCP Server',
+            headers={'X-CUSTOM-HEADER': 'custom-value'},
+            provider_metadata={'connector_id': 'connector_googlecalendar'},
+        )
+    ]
+)
+
+result = agent.run_sync('Give me some examples of my products.')
+print(result.output)
+#> Here are some examples of my data: Pen, Paper, Pencil.
+```
+
+_(This example is complete, it can be run "as is")_
+
+#### Provider Support
+
+| Parameter           | OpenAI | Anthropic | Notes                                                                                                       |
+|---------------------|--------|-----------|-------------------------------------------------------------------------------------------------------------|
+| `url`               | ✅ | ✅ | Optional for OpenAI (can use either `url` or `provider_metadata.connector_id`). Required for Anthropic)     |
+| `allowed_tools`     | ✅ | ✅ | -----------                                                                                                 |
+| `provider_metadata` | ✅ | ❌ | Optional for OpenAI (can use either `url` or `provider_metadata.connector_id`, not supported for Anthropic) |
+| `headers`           | ✅ | ❌ | -----------                                                                                                 |
+
 ## API Reference
 
 For complete API documentation, see the [API Reference](api/builtin_tools.md).

docs/index.md

@@ -14,7 +14,7 @@ We built Pydantic AI with one simple aim: to bring that FastAPI feeling to GenAI
 [Pydantic Validation](https://docs.pydantic.dev/latest/) is the validation layer of the OpenAI SDK, the Google ADK, the Anthropic SDK, LangChain, LlamaIndex, AutoGPT, Transformers, CrewAI, Instructor and many more. _Why use the derivative when you can go straight to the source?_ :smiley:
 
 2. **Model-agnostic**:
-Supports virtually every [model](models/overview.md) and provider: OpenAI, Anthropic, Gemini, DeepSeek, Grok, Cohere, Mistral, and Perplexity; Azure AI Foundry, Amazon Bedrock, Google Vertex AI, Ollama, LiteLLM, Groq, OpenRouter, Together AI, Fireworks AI, Cerebras, Hugging Face, GitHub, Heroku, Vercel, Nebius. If your favorite model or provider is not listed, you can easily implement a [custom model](models/overview.md#custom-models).
+Supports virtually every [model](models/overview.md) and provider: OpenAI, Anthropic, Gemini, DeepSeek, Grok, Cohere, Mistral, and Perplexity; Azure AI Foundry, Amazon Bedrock, Google Vertex AI, Ollama, LiteLLM, Groq, OpenRouter, Together AI, Fireworks AI, Cerebras, Hugging Face, GitHub, Heroku, Vercel. If your favorite model or provider is not listed, you can easily implement a [custom model](models/overview.md#custom-models).
 
 3. **Seamless Observability**:
 Tightly [integrates](logfire.md) with [Pydantic Logfire](https://pydantic.dev/logfire), our general-purpose OpenTelemetry observability platform, for real-time debugging, evals-based performance monitoring, and behavior, tracing, and cost tracking. If you already have an observability platform that supports OTel, you can [use that too](logfire.md#alternative-observability-backends).

docs/models/openai.md

@@ -608,35 +608,3 @@ print(result.output)
 #> The capital of France is Paris.
 ...
 ```
-
-### Nebius AI Studio
-
-Go to [Nebius AI Studio](https://studio.nebius.com/) and create an API key.
-
-Once you've set the `NEBIUS_API_KEY` environment variable, you can run the following:
-
-```python
-from pydantic_ai import Agent
-
-agent = Agent('nebius:Qwen/Qwen3-32B-fast')
-result = agent.run_sync('What is the capital of France?')
-print(result.output)
-#> The capital of France is Paris.
-```
-
-If you need to configure the provider, you can use the [`NebiusProvider`][pydantic_ai.providers.nebius.NebiusProvider] class:
-
-```python
-from pydantic_ai import Agent
-from pydantic_ai.models.openai import OpenAIChatModel
-from pydantic_ai.providers.nebius import NebiusProvider
-
-model = OpenAIChatModel(
-    'Qwen/Qwen3-32B-fast',
-    provider=NebiusProvider(api_key='your-nebius-api-key'),
-)
-agent = Agent(model)
-result = agent.run_sync('What is the capital of France?')
-print(result.output)
-#> The capital of France is Paris.
-```

docs/models/overview.md

@@ -28,7 +28,6 @@ In addition, many providers are compatible with the OpenAI API, and can be used
 - [GitHub Models](openai.md#github-models)
 - [Cerebras](openai.md#cerebras)
 - [LiteLLM](openai.md#litellm)
-- [Nebius AI Studio](openai.md#nebius-ai-studio)
 
 Pydantic AI also comes with [`TestModel`](../api/models/test.md) and [`FunctionModel`](../api/models/function.md)
 for testing and development.

pydantic_ai_slim/pydantic_ai/__init__.py

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

pydantic_ai_slim/pydantic_ai/_parts_manager.py

@@ -312,7 +312,6 @@ def handle_tool_call_part(
         tool_name: str,
         args: str | dict[str, Any] | None,
         tool_call_id: str | None = None,
-        id: str | None = None,
     ) -> ModelResponseStreamEvent:
         """Immediately create or fully-overwrite a ToolCallPart with the given information.
 
@@ -324,7 +323,6 @@ def handle_tool_call_part(
             tool_name: The name of the tool being invoked.
             args: The arguments for the tool call, either as a string, a dictionary, or None.
             tool_call_id: An optional string identifier for this tool call.
-            id: An optional identifier for this tool call part.
 
         Returns:
             ModelResponseStreamEvent: A `PartStartEvent` indicating that a new tool call part
@@ -334,7 +332,6 @@ def handle_tool_call_part(
             tool_name=tool_name,
             args=args,
             tool_call_id=tool_call_id or _generate_tool_call_id(),
-            id=id,
         )
         if vendor_part_id is None:
             # vendor_part_id is None, so we unconditionally append a new ToolCallPart to the end of the list

pydantic_ai_slim/pydantic_ai/builtin_tools.py

@@ -2,7 +2,7 @@
 
 from abc import ABC
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Literal
+from typing import TYPE_CHECKING, Any, Literal, Dict
 
 from typing_extensions import TypedDict
 
@@ -17,6 +17,7 @@
     'UrlContextTool',
     'ImageGenerationTool',
     'MemoryTool',
+    'MCPServerTool',
 )
 
 
@@ -237,3 +238,63 @@ class MemoryTool(AbstractBuiltinTool):
 
     kind: str = 'memory'
     """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
+    """
+
+    LIST_TOOLS_KIND: str = 'mcp_list_tools'
+    CALL_KIND: str = 'mcp_call'
+
+    kind: str = 'mcp_server'
+
+    id: str
+    """The id of the MCP server to use."""
+
+    authorization_token: str
+    """Authorization header to use when making requests to the MCP server."""
+
+    url: str | None = None
+    """The URL of the MCP server to use.
+
+    For OpenAI Responses, one of `url` or `connector_id` must be provided.
+    """
+
+    description: str | None = None
+    """A description of the MCP server."""
+
+    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
+    """
+
+    provider_metadata: dict[str, Any] | None = None
+    """Extra data to send to the model.
+
+    Supported by:
+
+    Supported by:
+
+    * OpenAI Responses
+    """

pydantic_ai_slim/pydantic_ai/messages.py

@@ -1052,13 +1052,6 @@ class BaseToolCallPart:
     In case the tool call id is not provided by the model, Pydantic AI will generate a random one.
     """
 
-    _: KW_ONLY
-
-    id: str | None = None
-    """An optional identifier of the tool call part, separate from the tool call ID.
-
-    This is used by some APIs like OpenAI Responses."""
-
     def args_as_dict(self) -> dict[str, Any]:
         """Return the arguments as a Python dictionary.