Add Docs for Pydantic AI FastMCP Toolset

[strawgate]

Enhancement

Under Integrations we should consider starting an AI Agents section where we cover how to use FastMCP servers/tools in AI Agent frameworks like OpenAI, Google AI Framework, Pydantic AI, etc.

For Pydantic AI we can link to the docs on their site when their site gets updated

[marvin-context-protocol]

Claude finished @strawgate's task —— View job

---

Investigation Complete ✓

Recommendation

Create a new "AI Agent Frameworks" subsection under the existing "AI SDKs" group in the Integrations documentation. The documentation structure already has an "AI SDKs" section (containing Anthropic, Gemini, and OpenAI integrations), which is the perfect home for agent framework integrations.

For Pydantic AI specifically, the FastMCP Toolset integration has already been contributed to Pydantic AI (merged in PR #2784). The documentation should link to Pydantic AI's official docs once they're updated, and provide a brief example showing how FastMCP servers work with Pydantic AI agents.

Findings

Current Documentation Structure

FastMCP's documentation already has a well-organized integrations section with:

• AI Assistants group (ChatGPT, Claude Desktop, Claude Code, Cursor, Gemini CLI)
• AI SDKs group (Anthropic API, Gemini SDK, OpenAI API)
• Authentication, Authorization, and API Integration groups

The "AI SDKs" group (lines 218-224 in docs.json) is specifically for programmatic AI integrations, making it the natural location for agent framework docs.

Pydantic AI Integration Status

FastMCP + Pydantic AI Background

Research into the Pydantic AI repository reveals:

• Issue Tracking: Contribute FastMCP Toolset to Pydantic AI #1370: William Easton (@strawgate, a FastMCP collaborator) tracked the work to contribute FastMCP Toolsets to Pydantic AI
• PR #2784: "Add FastMCPToolset" was merged into Pydantic AI on September 3, 2025
• The integration allows Pydantic AI agents to use FastMCP servers as toolsets directly
• Example usage pattern:

  from pydantic_ai.mcp import FastMCPToolset
  
  toolset = FastMCPToolset.from_mcp_server(name="github", mcp_server=github_mcp_server)
  # or
  toolset = FastMCPToolset.from_mcp_config(mcp_config=mcp_config)

Multiple open issues in Pydantic AI reference FastMCP integration (#1748, #2288, #2401, #2818, #3231), demonstrating active usage.

Existing SDK Integration Patterns

The current AI SDK docs (Anthropic, Gemini, OpenAI) follow a consistent pattern:

1. Brief intro explaining the integration
2. "Create a Server" section with example FastMCP server
3. "Deploy the Server" (if needed for remote access)
4. "Call the Server" section showing SDK-specific client code

This pattern should be adapted for agent framework integrations.

Detailed Action Plan

1. Update docs.json Structure

Rename the "AI SDKs" group to "AI Agents & SDKs" or create a separate "AI Agent Frameworks" group within Integrations:

{
  "group": "AI Agent Frameworks",
  "icon": "brain-circuit",
  "pages": [
    "integrations/pydantic-ai"
  ]
}

Alternative: Add to existing "AI SDKs" group:

{
  "group": "AI SDKs",
  "icon": "code",
  "pages": [
    "integrations/anthropic",
    "integrations/gemini",
    "integrations/openai",
    "integrations/pydantic-ai"
  ]
}

2. Create Pydantic AI Integration Doc

Create docs/integrations/pydantic-ai.mdx following this structure:

---
title: Pydantic AI 🤝 FastMCP
sidebarTitle: Pydantic AI
description: Use FastMCP servers as toolsets in Pydantic AI agents
icon: message-code
---

## Overview

[Pydantic AI](https://ai.pydantic.dev/) is a Python agent framework that supports MCP servers as toolsets through the `FastMCPToolset` integration. This allows you to connect FastMCP servers directly to Pydantic AI agents.

<Note>
The FastMCPToolset integration leverages FastMCP's capabilities including middleware, OAuth authentication, tool transformation, and more.
</Note>

## Create a Server

[Example FastMCP server code]

## Using with Pydantic AI

Install Pydantic AI:
```bash
pip install pydantic-ai

Connect your FastMCP server to a Pydantic AI agent:

from pydantic_ai import Agent
from pydantic_ai.mcp import FastMCPToolset
from fastmcp import FastMCP

# Your FastMCP server
mcp = FastMCP("MyServer")

@mcp.tool
def example_tool(query: str) -> str:
    return f"Result for: {query}"

# Create agent with FastMCP toolset
agent = Agent(
    "openai:gpt-4",
    toolsets=[FastMCPToolset(fastmcp=mcp)]
)

# Use the agent
result = await agent.run("Use the example tool")
print(result.data)

Advanced Configuration

From MCP Config

toolset = FastMCPToolset.from_mcp_config(mcp_config=mcp_config)

From MCP Server Dictionary

toolset = FastMCPToolset.from_mcp_server(
    name="server_name",
    mcp_server=server_dict
)

Learn More

For complete documentation on using MCP with Pydantic AI, visit:

• Pydantic AI MCP Documentation
• Pydantic AI Toolsets Guide

### 3. Future Agent Framework Additions

When adding other frameworks (OpenAI Swarm, LangGraph, AutoGen, etc.), follow the same pattern:
- Create `docs/integrations/{framework-name}.mdx`
- Add to the "AI Agent Frameworks" group in docs.json
- Show both FastMCP server setup and framework-specific integration code
- Link to official framework documentation

### 4. Cross-Reference Updates

Consider adding a brief mention in:
- `docs/clients/client.mdx` - note that AI agent frameworks can consume FastMCP servers
- `docs/getting-started/welcome.mdx` - mention agent framework support in the intro

## Related Items

<details>
<summary>Related Issues and Pull Requests</summary>

| Repository | Issue/PR | Relevance |
| --- | --- | --- |
| jlowin/fastmcp | [#2003: Documentation for using FastMCP as an MCP Client](https://github.com/jlowin/fastmcp/issues/2003) | Related request for client usage docs with AI frameworks |
| jlowin/fastmcp | [#1370: Tracking: Contribute FastMCP Toolset to Pydantic AI](https://github.com/jlowin/fastmcp/issues/1370) | Original tracking issue for the Pydantic AI integration (closed, completed) |
| jlowin/fastmcp | [#2014: Support for OpenAI Apps SDK](https://github.com/jlowin/fastmcp/issues/2014) | Tracks OpenAI Apps SDK support, another agent framework integration |
| pydantic/pydantic-ai | [#2784: Add FastMCPToolset](https://github.com/pydantic/pydantic-ai/pull/2784) | Merged PR adding FastMCP support to Pydantic AI |
| pydantic/pydantic-ai | [#2406: Contributing FastMCP Toolset](https://github.com/pydantic/pydantic-ai/issues/2406) | Original feature request for FastMCP integration |

</details>

<details>
<summary>Related Files</summary>

| Repository | File | Relevance | Sections |
| --- | --- | --- | --- |
| jlowin/fastmcp | [docs/docs.json](https://github.com/jlowin/fastmcp/blob/main/docs/docs.json) | Documentation structure configuration | Lines 218-224: Current "AI SDKs" group |
| jlowin/fastmcp | [docs/integrations/openai.mdx](https://github.com/jlowin/fastmcp/blob/main/docs/integrations/openai.mdx) | Template for SDK integration docs | Lines 1-100: Structure to follow |
| jlowin/fastmcp | [docs/integrations/gemini.mdx](https://github.com/jlowin/fastmcp/blob/main/docs/integrations/gemini.mdx) | Another SDK integration example | Lines 1-100: Similar structure |
| jlowin/fastmcp | [docs/integrations/anthropic.mdx](https://github.com/jlowin/fastmcp/blob/main/docs/integrations/anthropic.mdx) | Third SDK integration reference | Lines 1-100: Consistent patterns |

</details>

<details>
<summary>Related Webpages</summary>

| Name | URL | Relevance |
| --- | --- | --- |
| Pydantic AI MCP Documentation | https://ai.pydantic.dev/api/mcp/ | Official Pydantic AI docs for MCP integration (target for linking) |
| Pydantic AI Toolsets Guide | https://ai.pydantic.dev/tools/ | Context for how toolsets work in Pydantic AI |
| FastMCP Integrations | https://gofastmcp.com/integrations/anthropic | Current integration documentation examples |

</details>

---

[strawgate]

/marvin Please review pydantic/pydantic-ai#2784 to see how the FastMCPToolset actually works and see if you can find docs online for any other agent frameworks with fastmcp

[marvin-context-protocol]

Claude finished @strawgate's task —— View job

---

Research: Pydantic AI Integration & Other Agent Frameworks

---

Key Findings

1. Pydantic AI Integration

PR #2784 Status: Merged October 24, 2025

How It Works:

• Pydantic AI uses MCPServerStdio, MCPServerSSE, and MCPServerStreamableHTTP classes to connect to MCP servers
• Each MCP server instance becomes a toolset that can be registered with a Pydantic AI agent
• Supports runtime validation via Pydantic schemas for type-safe tool calls
• Allows in-memory FastMCP servers, stdio servers, remote MCP servers, and tool transformation

Current Documentation:

• Official docs at https://ai.pydantic.dev/api/mcp/ cover MCP server classes
• Shows examples of using FastMCP to create MCP servers that work with Pydantic AI agents
• The previous investigation's proposed documentation structure remains valid

2. Other Agent Frameworks with MCP Support

Research identified 11 additional frameworks that support MCP servers (12 total including Pydantic AI):

Framework	MCP Integration	Documentation Priority
OpenAI Agents SDK	Native MCPServerStdio with streaming	HIGH - Major platform, already partially covered
LangChain	load_mcp_tools() function	HIGH - Massive ecosystem
LlamaIndex	BasicMCPClient + McpToolSpec	MEDIUM - RAG-focused
CrewAI	MCPServerAdapter wrapper	MEDIUM - Popular multi-agent
DSPy	dspy.Tool.from_mcp_tool()	MEDIUM - Prompt optimization
Claude Agent SDK	ClaudeAgentOptions with allowlist	LOW - Anthropic-specific
Microsoft Agent Framework	MCPStdioTool for ChatAgent	LOW - Azure ecosystem
Google Agent Dev Kit	MCPToolset with params	LOW - Google-specific
Agno	MCPTools context manager	LOW - Niche framework
Upsonic	Custom MCP wrappers	LOW - Financial sector
mcp-agent	Declarative MCPServerSettings	LOW - Smaller framework

Sources:

• ClickHouse MCP Framework Comparison
• Medium: FastMCP + OpenAI Tools
• OpenAI Agents SDK official documentation

3. Current FastMCP Documentation Status

Already Documented:

• ✅ OpenAI Responses API (docs/integrations/openai.mdx) - comprehensive coverage with auth examples
• ✅ Anthropic API (docs/integrations/anthropic.mdx)
• ✅ Gemini SDK (docs/integrations/gemini.mdx)

Documentation Structure:
Current "AI SDKs" group exists at lines 218-224 of docs/docs.json

---

Updated Recommendations

1. Documentation Organization

Option A (Recommended): Expand existing "AI SDKs" group to include agent frameworks:

{
  "group": "AI SDKs & Agent Frameworks",
  "icon": "code",
  "pages": [
    "integrations/anthropic",
    "integrations/gemini",
    "integrations/openai",
    "integrations/pydantic-ai",
    "integrations/langchain",
    "integrations/llamaindex"
  ]
}

Option B: Create separate "Agent Frameworks" subsection:

{
  "group": "AI SDKs",
  "icon": "code",
  "pages": ["integrations/anthropic", "integrations/gemini", "integrations/openai"]
},
{
  "group": "Agent Frameworks",
  "icon": "brain-circuit",
  "pages": [
    "integrations/pydantic-ai",
    "integrations/langchain",
    "integrations/llamaindex"
  ]
}

2. Priority Documentation Pages

Phase 1 (High Priority):

1. Pydantic AI (docs/integrations/pydantic-ai.mdx) - Requested in this issue
2. OpenAI Agents SDK - Expand existing OpenAI doc or create separate page for Agents SDK (distinct from Responses API)
3. LangChain (docs/integrations/langchain.mdx) - Major ecosystem

Phase 2 (Medium Priority):
4. LlamaIndex (docs/integrations/llamaindex.mdx) - RAG use cases
5. CrewAI (docs/integrations/crewai.mdx) - Multi-agent workflows

3. Documentation Pattern

Each framework doc should follow this structure (consistent with existing SDK docs):

---
title: [Framework] 🤝 FastMCP
sidebarTitle: [Framework]
description: Use FastMCP servers with [Framework]
icon: message-code
---

## Overview
[Brief intro about the framework and its MCP support]

## Create a Server
[Example FastMCP server code]

## Using with [Framework]
[Framework-specific integration code showing how to connect]

## Advanced Features
[Optional: Auth, remote servers, tool transformation]

## Learn More
[Links to official framework documentation]

4. Key Differentiators

When documenting agent frameworks vs. SDKs, emphasize:

• SDKs (Anthropic, OpenAI, Gemini): Direct API access, typically for remote/deployed servers
• Agent Frameworks: In-memory servers, stdio transport, orchestration capabilities, type safety, prompt optimization

5. Next Steps for This Issue

To implement docs for Pydantic AI specifically:

1. Create docs/integrations/pydantic-ai.mdx based on the structure above
2. Update docs/docs.json to include the new page (choose Option A or B)
3. Include code examples showing:
   • Creating a FastMCP server
   • Using MCPServerStdio for in-memory servers
   • Type-safe tool calls with Pydantic validation
4. Link to official Pydantic AI MCP documentation once available

---