Merge branch 'main' into main

Author: ajac-zero

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, Nebius, OVHcloud. 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/agents.md

@@ -736,7 +736,7 @@ try:
 except UnexpectedModelBehavior as e:
     print(e)  # (1)!
     """
-    Safety settings triggered, body:
+    Content filter 'SAFETY' triggered, body:
     <safety settings details>
     """
 ```

docs/api/providers.md

@@ -43,3 +43,5 @@
 ::: pydantic_ai.providers.litellm.LiteLLMProvider
 
 ::: pydantic_ai.providers.nebius.NebiusProvider
+
+::: pydantic_ai.providers.ovhcloud.OVHcloudProvider

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/durable_execution/prefect.md

@@ -255,20 +255,23 @@ from prefect import flow
 from pydantic_ai import Agent
 from pydantic_ai.durable_exec.prefect import PrefectAgent
 
-agent = Agent(
-    'openai:gpt-4o',
-    name='daily_report_agent',
-    instructions='Generate a daily summary report.',
-)
-
-prefect_agent = PrefectAgent(agent)
 
 @flow
 async def daily_report_flow(user_prompt: str):
     """Generate a daily report using the agent."""
+    agent = Agent(  # (1)!
+        'openai:gpt-4o',
+        name='daily_report_agent',
+        instructions='Generate a daily summary report.',
+    )
+
+    prefect_agent = PrefectAgent(agent)
+
     result = await prefect_agent.run(user_prompt)
     return result.output
 
+
+
 # Serve the flow with a daily schedule
 if __name__ == '__main__':
     daily_report_flow.serve(
@@ -279,6 +282,8 @@ if __name__ == '__main__':
     )
 ```
 
+1. Each flow run executes in an isolated process, and all inputs and dependencies must be serializable. Because Agent instances cannot be serialized, instantiate the agent inside the flow rather than at the module level.
+
 The `serve()` method accepts scheduling options:
 
 - **`cron`**: Cron schedule string (e.g., `'0 9 * * *'` for daily at 9am)