docs(integrations): add Pydantic AI FastMCP toolset guide (#4070)

* docs(integrations): add Pydantic AI FastMCP toolset guide

* docs(integrations): add Pydantic AI to AI SDKs nav

docs/docs.json

@@ -322,7 +322,8 @@
                     "pages": [
                       "integrations/anthropic",
                       "integrations/gemini",
-                      "integrations/openai"
+                      "integrations/openai",
+                      "integrations/pydantic-ai"
                     ]
                   },
                   "integrations/mcp-json-configuration"

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")
+
+@mcp.tool
+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")
+
+@mcp.tool
+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).