Feature: MCP client Resources support

docs/mcp/client.md

@@ -311,6 +311,67 @@ agent = Agent('openai:gpt-5', toolsets=[weather_server, calculator_server])
 
 MCP tools can include metadata that provides additional information about the tool's characteristics, which can be useful when [filtering tools][pydantic_ai.toolsets.FilteredToolset]. The `meta`, `annotations`, and `output_schema` fields can be found on the `metadata` dict on the [`ToolDefinition`][pydantic_ai.tools.ToolDefinition] object that's passed to filter functions.
 
+## Resources
+
+MCP servers can provide [resources](https://modelcontextprotocol.io/docs/concepts/resources) - files, data, or content that can be accessed by the client. Resources in MCP are application-driven, with host applications determining how to incorporate context manually, based on their needs. This means they will _not_ be exposed to the LLM automatically (unless a tool returns a `ResourceLink` or `EmbeddedResource`).
+
+Pydantic AI provides methods to discover and read resources from MCP servers:
+
+- [`list_resources()`][pydantic_ai.mcp.MCPServer.list_resources] - List all available resources on the server
+- [`list_resource_templates()`][pydantic_ai.mcp.MCPServer.list_resource_templates] - List resource templates with parameter placeholders
+- [`read_resource(uri)`][pydantic_ai.mcp.MCPServer.read_resource] - Read the contents of a specific resource by URI
+
+Resources are automatically converted: text content is returned as `str`, and binary content is returned as [`BinaryContent`][pydantic_ai.messages.BinaryContent].
+
+Before consuming resources, we need to run a server that exposes some:
+
+```python {title="mcp_resource_server.py"}
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP('Pydantic AI MCP Server')
+log_level = 'unset'
+
+
+@mcp.resource('resource://user_name.txt', mime_type='text/plain')
+async def user_name_resource() -> str:
+    return 'Alice'
+
+
+if __name__ == '__main__':
+    mcp.run()
+```
+
+Then we can create the client:
+
+```python {title="mcp_resources.py", requires="mcp_resource_server.py"}
+import asyncio
+
+from pydantic_ai.mcp import MCPServerStdio
+
+
+async def main():
+    server = MCPServerStdio('python', args=['-m', 'mcp_resource_server'])
+
+    async with server:
+        # List all available resources
+        resources = await server.list_resources()
+        for resource in resources:
+            print(f' - {resource.name}: {resource.uri} ({resource.mime_type})')
+            #>  - user_name_resource: resource://user_name.txt (text/plain)
+
+        # Read a text resource
+        user_name = await server.read_resource('resource://user_name.txt')
+        print(f'Text content: {user_name}')
+        #> Text content: Alice
+
+
+if __name__ == '__main__':
+    asyncio.run(main())
+```
+
+_(This example is complete, it can be run "as is")_
+
+
 ## Custom TLS / SSL configuration
 
 In some environments you need to tweak how HTTPS connections are established –

pydantic_ai_slim/pydantic_ai/_mcp.py

@@ -1,6 +1,8 @@
+from __future__ import annotations
+
 import base64
 from collections.abc import Sequence
-from typing import Literal
+from typing import TYPE_CHECKING, Literal
 
 from . import exceptions, messages
 
@@ -12,6 +14,9 @@
         'you can use the `mcp` optional group — `pip install "pydantic-ai-slim[mcp]"`'
     ) from _import_error
 
+if TYPE_CHECKING:
+    from .mcp import Resource, ResourceTemplate, ServerCapabilities
+
 
 def map_from_mcp_params(params: mcp_types.CreateMessageRequestParams) -> list[messages.ModelMessage]:
     """Convert from MCP create message request parameters to pydantic-ai messages."""
@@ -121,3 +126,56 @@ def map_from_sampling_content(
         return messages.TextPart(content=content.text)
     else:
         raise NotImplementedError('Image and Audio responses in sampling are not yet supported')
+
+
+def map_from_mcp_resource(mcp_resource: mcp_types.Resource) -> Resource:
+    """Convert from MCP Resource to native Pydantic AI Resource."""
+    from .mcp import Resource, ResourceAnnotations
+
+    return Resource(
+        uri=str(mcp_resource.uri),
+        name=mcp_resource.name,
+        title=mcp_resource.title,
+        description=mcp_resource.description,
+        mime_type=mcp_resource.mimeType,
+        size=mcp_resource.size,
+        annotations=(
+            ResourceAnnotations(audience=mcp_resource.annotations.audience, priority=mcp_resource.annotations.priority)
+            if mcp_resource.annotations
+            else None
+        ),
+        metadata=mcp_resource.meta,
+    )
+
+
+def map_from_mcp_resource_template(mcp_template: mcp_types.ResourceTemplate) -> ResourceTemplate:
+    """Convert from MCP ResourceTemplate to native Pydantic AI ResourceTemplate."""
+    from .mcp import ResourceAnnotations, ResourceTemplate
+
+    return ResourceTemplate(
+        uri_template=mcp_template.uriTemplate,
+        name=mcp_template.name,
+        title=mcp_template.title,
+        description=mcp_template.description,
+        mime_type=mcp_template.mimeType,
+        annotations=(
+            ResourceAnnotations(audience=mcp_template.annotations.audience, priority=mcp_template.annotations.priority)
+            if mcp_template.annotations
+            else None
+        ),
+        metadata=mcp_template.meta,
+    )
+
+
+def map_from_mcp_server_capabilities(mcp_capabilities: mcp_types.ServerCapabilities) -> ServerCapabilities:
+    """Convert from MCP ServerCapabilities to native Pydantic AI ServerCapabilities."""
+    from .mcp import ServerCapabilities
+
+    return ServerCapabilities(
+        experimental=list(mcp_capabilities.experimental.keys()) if mcp_capabilities.experimental else None,
+        logging=mcp_capabilities.logging is not None,
+        prompts=mcp_capabilities.prompts is not None,
+        resources=mcp_capabilities.resources is not None,
+        tools=mcp_capabilities.tools is not None,
+        completions=mcp_capabilities.completions is not None,
+    )