From f5dea2a17c4cd579260af0be24b7c80f08059aed Mon Sep 17 00:00:00 2001 From: Mukunda Rao Katta Date: Mon, 4 May 2026 09:22:17 -0700 Subject: [PATCH] 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 | 3 +- docs/integrations/pydantic-ai.mdx | 137 ++++++++++++++++++++++++++++++ 2 files changed, 139 insertions(+), 1 deletion(-) create mode 100644 docs/integrations/pydantic-ai.mdx diff --git a/docs/docs.json b/docs/docs.json index 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.mdx new file mode 100644 index 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/). + + +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. + + +## 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).