---
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
import random
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]:
    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#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/bearer) 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).