π The fast, Pythonic way to build MCP servers and clients.
docs(integrations): add Pydantic AI FastMCP toolset guide (#4070)
Mukunda Rao Kattaf5dea2a17c4c
diff --git a/docs/docs.json b/docs/docs.jsonindex b2c60ad20..924d0d6f6 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -322,7 +322,8 @@"pages": ["integrations/anthropic","integrations/gemini",- "integrations/openai"+ "integrations/openai",+ "integrations/pydantic-ai"]},"integrations/mcp-json-configuration"diff --git a/docs/integrations/pydantic-ai.mdx b/docs/integrations/pydantic-ai.mdxnew file mode 100644index 000000000..811a055b1--- /dev/null+++ b/docs/integrations/pydantic-ai.mdx@@ -0,0 +1,137 @@+---+title: Pydantic AI π€ FastMCP+sidebarTitle: Pydantic AI+description: Connect FastMCP servers to Pydantic AI agents using the FastMCPToolset+icon: message-code+---++[Pydantic AI](https://ai.pydantic.dev/) ships a [`FastMCPToolset`](https://ai.pydantic.dev/mcp/fastmcp-client/) that lets a Pydantic AI agent call tools exposed by any MCP server through the [FastMCP Client](/clients/client). Because the toolset is built on the FastMCP Client, it works with FastMCP servers as well as any other MCP server, and supports the full range of [transports](/clients/transports): in-memory, STDIO, Streamable HTTP, and SSE.++This page shows how to point `FastMCPToolset` at a FastMCP server, with examples for each transport. For the toolset's full API, see the [Pydantic AI documentation](https://ai.pydantic.dev/mcp/fastmcp-client/).++<Tip>+The `FastMCPToolset` currently exposes **tools** to the agent. Other MCP features such as elicitation and sampling are not yet supported through this toolset; use Pydantic AI's standard [`MCPServer`](https://ai.pydantic.dev/mcp/client/) client if you need them.+</Tip>++## Install++`FastMCPToolset` lives in `pydantic-ai-slim` behind the `fastmcp` optional group:++```bash+pip install "pydantic-ai-slim[fastmcp]"+```++## Create a Server++Create a FastMCP server with the tools you want to expose. We'll use a single dice-rolling tool throughout this guide.++```python server.py+import random+from fastmcp import FastMCP++mcp = FastMCP(name="Dice Roller")++def roll_dice(n_dice: int) -> list[int]:+ """Roll `n_dice` 6-sided dice and return the results."""+ return [random.randint(1, 6) for _ in range(n_dice)]++if __name__ == "__main__":+ mcp.run(transport="http", port=8000)+```++## In-Memory++If your FastMCP server lives in the same process as your agent, pass the `FastMCP` instance directly. The toolset reuses an [in-memory transport](/clients/transports#in-memory-transport), which avoids a network round trip and is the fastest option for tests and embedded use.++```python+import asyncio+from fastmcp import FastMCP+from pydantic_ai import Agent+from pydantic_ai.toolsets.fastmcp import FastMCPToolset++mcp = FastMCP(name="Dice Roller")++def roll_dice(n_dice: int) -> list[int]:+ import random+ return [random.randint(1, 6) for _ in range(n_dice)]++toolset = FastMCPToolset(mcp)+agent = Agent("openai:gpt-4.1", toolsets=[toolset])++async def main():+ result = await agent.run("Roll 3 dice!")+ print(result.output)++if __name__ == "__main__":+ asyncio.run(main())+```++## Streamable HTTP++For a remote FastMCP server reachable over HTTP, pass the URL as a string. The toolset infers the [Streamable HTTP transport](/clients/transports#streamable-http-transport) from the URL.++```python+from pydantic_ai import Agent+from pydantic_ai.toolsets.fastmcp import FastMCPToolset++toolset = FastMCPToolset("https://your-server-url.com/mcp")+agent = Agent("openai:gpt-4.1", toolsets=[toolset])+```++For [SSE](/clients/transports#sse-transport), use a `/sse` URL instead.++## STDIO++To launch a FastMCP server as a subprocess, pass a script path and the toolset will use the [STDIO transport](/clients/transports#stdio-transport).++```python+from pydantic_ai import Agent+from pydantic_ai.toolsets.fastmcp import FastMCPToolset++toolset = FastMCPToolset("server.py")+agent = Agent("openai:gpt-4.1", toolsets=[toolset])+```++You can also pass a [`StdioTransport`](/clients/transports#stdio-transport) directly when you need control over the command, args, or environment.++## MCP Configuration++To wire up multiple servers at once, pass an [MCP configuration](/integrations/mcp-json-configuration) dictionary. The toolset opens one client per server and exposes all of their tools to the agent.++```python+from pydantic_ai import Agent+from pydantic_ai.toolsets.fastmcp import FastMCPToolset++mcp_config = {+ "mcpServers": {+ "dice": {"command": "python", "args": ["server.py"]},+ "weather": {"url": "https://weather.example.com/mcp"},+ }+}++toolset = FastMCPToolset(mcp_config)+agent = Agent("openai:gpt-4.1", toolsets=[toolset])+```++## Authentication++Because `FastMCPToolset` wraps a [FastMCP `Client`](/clients/client), it inherits the client's full [authentication](/clients/auth) story. To pass credentials such as a bearer token to a remote server, build a `Client` (or `StreamableHttpTransport`) yourself and hand it to the toolset.++```python+from fastmcp import Client+from fastmcp.client.transports import StreamableHttpTransport+from pydantic_ai import Agent+from pydantic_ai.toolsets.fastmcp import FastMCPToolset++transport = StreamableHttpTransport(+ url="https://your-server-url.com/mcp",+ headers={"Authorization": "Bearer your-access-token"},+)++toolset = FastMCPToolset(Client(transport))+agent = Agent("openai:gpt-4.1", toolsets=[toolset])+```++For OAuth flows, use FastMCP's [`OAuth` helper](/clients/auth/oauth) when constructing the `Client`. For server-side token verification, see [Token Verification](/servers/auth/token-verification).