Cleanup and addresing comments

Author: Artui

docs/builtin-tools.md

@@ -425,9 +425,8 @@ _(This example is complete, it can be run "as is")_
 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).
+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
 
@@ -456,8 +455,6 @@ agent = Agent(
         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'],
         )
     ]
 )
@@ -482,8 +479,6 @@ agent = Agent(
         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'],
         )
     ]
 )
@@ -509,11 +504,7 @@ agent = Agent(
     builtin_tools=[
         MCPServerTool(
             id='your-mcp-server',  # required field
-            url='https://api.githubcopilot.com/mcp/',  # optional field, use `url` or `provider_metadata`
-            authorization_token=os.getenv('GITHUB_ACCESS_TOKEN', 'mock-access-token'),  # optional field
-            allowed_tools=['search_repositories', 'list_commits'],  # optional field
-            description='Your MCP Server',  # optional field
-            headers={'X-CUSTOM-HEADER': 'custom-value'},  # optional field
+            url='https://api.githubcopilot.com/mcp/',  # required field
         )
     ]
 )
@@ -523,7 +514,7 @@ print(result.output)
 #> Here are some examples of my data: Pen, Paper, Pencil.
 ```
 
-For OpenAI Responses, you can use connector ID instead of URL:
+For OpenAI Responses, you can use a connector by specifying a special `x-openai-connector:` URL:
 
 _(This example is complete, it can be run "as is")_
 
@@ -536,12 +527,12 @@ agent = Agent(
     'openai-responses:gpt-4o',
     builtin_tools=[
         MCPServerTool(
-            id='your-mcp-server',  # required field
-            url='x-openai-connector:connector_googlecalendar',  # required field
-            authorization_token=os.getenv('GITHUB_ACCESS_TOKEN', 'mock-access-token'),  # optional field
-            allowed_tools=['search_repositories', 'list_commits'],  # optional field
-            description='Your MCP Server',  # optional field
-            headers={'X-CUSTOM-HEADER': 'custom-value'},  # optional field
+            id='your-mcp-server',
+            url='x-openai-connector:connector_googlecalendar',
+            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'},
         )
     ]
 )
@@ -555,11 +546,13 @@ _(This example is complete, it can be run "as is")_
 
 #### Provider Support
 
-| Parameter           | OpenAI | Anthropic | Notes                                                                                                               |
-|---------------------|--------|-----------|---------------------------------------------------------------------------------------------------------------------|
-| `url`               | ✅ | ✅ | For OpenAI Responses, it is possible to use `connector_id` by providing it as `x-openai-connector:<connector_id>`   |
-| `allowed_tools`     | ✅ | ✅ | -----------                                                                                                         |
-| `headers`           | ✅ | ❌ | -----------                                                                                                         |
+| Parameter             | OpenAI | Anthropic |
+|-----------------------|--------|-----------|
+| `url`                 | ✅ | ✅ |
+| `allowed_tools`       | ✅ | ✅ |
+| `authorization_token` | ✅ | ✅ |
+| `description`         | ✅ | ❌ |
+| `headers`             | ✅ | ❌ |
 
 ## API Reference
 

docs/mcp/overview.md

@@ -1,9 +1,10 @@
 # Model Context Protocol (MCP)
 
-Pydantic AI supports [Model Context Protocol (MCP)](https://modelcontextprotocol.io) in two ways:
+Pydantic AI supports [Model Context Protocol (MCP)](https://modelcontextprotocol.io) in three ways:
 
 1. [Agents](../agents.md) act as an MCP Client, connecting to MCP servers to use their tools, [learn more …](client.md)
 2. Agents can be used within MCP servers, [learn more …](server.md)
+3. Agents cab pass MCP Servers as built in tools into models, [learn more …](../builtin-tools.md)
 
 ## What is MCP?
 

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, Any, Literal
+from typing import TYPE_CHECKING, Literal
 
 from typing_extensions import TypedDict
 
@@ -253,15 +253,15 @@ class MCPServerTool(AbstractBuiltinTool):
     id: str
     """The id of the MCP server to use."""
 
-    authorization_token: str | None = None
-    """Authorization header to use when making requests to 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."""
+
     description: str | None = None
     """A description of the MCP server."""
 
@@ -284,14 +284,6 @@ class MCPServerTool(AbstractBuiltinTool):
     * OpenAI Responses
     """
 
-    provider_metadata: dict[str, Any] | None = None
-    """Extra data to send to the model.
-
-    Supported by:
-
-    * OpenAI Responses
-    """
-
     kind: str = 'mcp_server'
 
     LIST_TOOLS_KIND: Literal['mcp_server:mcp_list_tools'] = 'mcp_server:mcp_list_tools'

pydantic_ai_slim/pydantic_ai/models/anthropic.py

@@ -5,7 +5,7 @@
 from contextlib import asynccontextmanager
 from dataclasses import dataclass, field
 from datetime import datetime
-from typing import Any, Literal, TypeAlias, cast, overload
+from typing import Any, Literal, cast, overload
 
 from pydantic import TypeAdapter
 from typing_extensions import assert_never
@@ -890,11 +890,6 @@ def _map_mcp_server_use_block(item: BetaMCPToolUseBlock, provider_name: str) ->
     )
 
 
-BetaMCPToolResultBlockContent: TypeAlias = str | list[BetaTextBlock]
-
-mcp_server_result_content_ta: TypeAdapter[BetaMCPToolResultBlockContent] = TypeAdapter(BetaMCPToolResultBlockContent)
-
-
 def _map_mcp_server_result_block(item: BetaMCPToolResultBlock, provider_name: str) -> BuiltinToolReturnPart:
     return BuiltinToolReturnPart(
         provider_name=provider_name,

pydantic_ai_slim/pydantic_ai/models/openai.py

@@ -110,7 +110,7 @@
 allows this model to be used more easily with other model types (ie, Ollama, Deepseek).
 """
 
-OpenAIResponsesMCPConnectorIdPrefix: Literal['x-openai-connector'] = 'x-openai-connector'
+MCP_SERVER_TOOL_CONNECTOR_URI_SCHEME: Literal['x-openai-connector'] = 'x-openai-connector'
 """
 Prefix for OpenAI connector IDs. OpenAI supports either a URL or a connector ID when passing MCP configuration to a model,
 by using that prefix like `x-openai-connector:<connector-id>` in a URL, you can pass a connector ID to a model.
@@ -1265,16 +1265,11 @@ def _get_builtin_tools(self, model_request_parameters: ModelRequestParameters) -
                 if tool.headers:  # pragma: no branch
                     mcp_tool['headers'] = tool.headers  # pragma: no cover
 
-                url, connector_id = None, None
-                if tool.url.startswith(OpenAIResponsesMCPConnectorIdPrefix):  # pragma: no cover
+                if tool.url.startswith(MCP_SERVER_TOOL_CONNECTOR_URI_SCHEME + ':'):  # pragma: no cover
                     _, connector_id = tool.url.split(':', maxsplit=1)
+                    mcp_tool['connector_id'] = connector_id  # pyright: ignore[reportGeneralTypeIssues]
                 else:
-                    url = tool.url
-
-                if url:
                     mcp_tool['server_url'] = tool.url
-                elif connector_id:  # pragma: no cover
-                    mcp_tool['connector_id'] = connector_id  # pyright: ignore[reportGeneralTypeIssues]
 
                 tools.append(mcp_tool)
             elif isinstance(tool, ImageGenerationTool):  # pragma: no branch