Skip to content

Reorganize docs around provider architecture #2723

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jlowin merged 3 commits into from
Dec 25, 2025
Merged

Reorganize docs around provider architecture #2723

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
36d4f82
Reorganize docs around provider architecture
jlowin Dec 25, 2025
53ff5c6
Update integration section name
jlowin Dec 25, 2025
f685570
Address CodeRabbit review feedback
jlowin Dec 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions docs/development/upgrade-guide.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,31 @@ This guide provides migration instructions for breaking changes and major update

## v3.0.0

### Provider Architecture

FastMCP v3 introduces a unified provider architecture for sourcing components. All tools, resources, and prompts now flow through providers:

- **LocalProvider** stores decorator-registered components (`@mcp.tool`, etc.)
- **FastMCPProvider** wraps another FastMCP server for composition
- **ProxyProvider** connects to remote MCP servers
- **TransformingProvider** adds namespacing and renaming

See [Providers](/servers/providers/overview) for the complete documentation.

### Mount Namespace Parameter

The `prefix` parameter for `mount()` has been renamed to `namespace`:

<CodeGroup>
```python Before
main.mount(subserver, prefix="api")
```

```python After
main.mount(subserver, namespace="api")
```
</CodeGroup>

### Component Enable/Disable

The `enabled` field and `enable()`/`disable()` methods have been removed from component objects. Use server or provider methods instead:
Expand Down
63 changes: 35 additions & 28 deletions docs/docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,10 +20,7 @@
"primary": "#2d00f7"
},
"contextual": {
"options": [
"copy",
"view"
]
"options": ["copy", "view"]
},
"description": "The fast, Pythonic way to build MCP servers and clients.",
"errors": {
Expand Down Expand Up @@ -95,7 +92,7 @@
"pages": [
"servers/server",
{
"group": "Core Components",
"group": "Components",
"icon": "toolbox",
"pages": [
"servers/tools",
Expand All @@ -104,20 +101,30 @@
]
},
{
"group": "Advanced Features",
"group": "Providers",
"icon": "layer-group",
"pages": [
"servers/providers/overview",
"servers/providers/local",
"servers/providers/mounting",
"servers/providers/namespacing",
"servers/providers/proxy",
"servers/providers/custom"
]
},
{
"group": "Features",
"icon": "stars",
"pages": [
"servers/composition",
"servers/tasks",
"servers/context",
"servers/elicitation",
"servers/icons",
"servers/logging",
"servers/middleware",
"servers/progress",
"servers/proxy",
"servers/sampling",
"servers/storage-backends",
"servers/tasks"
"servers/storage-backends"
]
},
{
Expand Down Expand Up @@ -150,10 +157,7 @@
{
"group": "Essentials",
"icon": "cube",
"pages": [
"clients/client",
"clients/transports"
]
"pages": ["clients/client", "clients/transports"]
},
{
"group": "Core Operations",
Expand All @@ -180,16 +184,18 @@
{
"group": "Authentication",
"icon": "user-shield",
"pages": [
"clients/auth/oauth",
"clients/auth/bearer"
]
"pages": ["clients/auth/oauth", "clients/auth/bearer"]
}
]
},
{
"group": "Integrations",
"pages": [
{
"group": "Providers",
"icon": "globe",
"pages": ["integrations/fastapi", "integrations/openapi"]
},
{
"group": "Authentication",
"icon": "key",
Expand Down Expand Up @@ -236,14 +242,6 @@
"integrations/gemini",
"integrations/openai"
]
},
{
"group": "API Integration",
"icon": "globe",
"pages": [
"integrations/fastapi",
"integrations/openapi"
]
}
]
},
Expand Down Expand Up @@ -476,6 +474,7 @@
"group": "fastmcp.utilities",
"pages": [
"python-sdk/fastmcp-utilities-__init__",
"python-sdk/fastmcp-utilities-async_utils",
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Dec 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Verify the new async_utils documentation file exists
fd -t f "fastmcp-utilities-async_utils" --extension mdx

Repository: jlowin/fastmcp

Length of output: 40

🏁 Script executed:

#!/bin/bash
# Broader search for async_utils files
echo "=== Searching for any async_utils files ==="
fd "async_utils" 

# Check the directory structure for python-sdk docs
echo -e "\n=== Python SDK documentation files ==="
fd -t f "python-sdk" | head -20

# Look at examples from docs.json to see naming pattern
echo -e "\n=== Sample python-sdk entries from docs.json ==="
grep -o '"python-sdk/[^"]*"' docs/docs.json | head -10

Repository: jlowin/fastmcp

Length of output: 618

🏁 Script executed:

#!/bin/bash
# Find all .mdx files in the docs directory
echo "=== MDX files in docs directory ==="
fd -t f "\.mdx" docs/ | head -20

# Check if there's a generated directory or specific SDK docs location
echo -e "\n=== Documentation directory structure ==="
ls -la docs/ 2>/dev/null | head -20

# Look for files matching the pattern of entries in docs.json
echo -e "\n=== Checking for fastmcp-utilities related docs ==="
find docs -type f \( -name "*utilities*" -o -name "*async*" \) 2>/dev/null

Repository: jlowin/fastmcp

Length of output: 3664

🏁 Script executed:

#!/bin/bash
# Get complete list of python-sdk files
echo "=== All files in docs/python-sdk ==="
ls -1 docs/python-sdk/ | grep "^fastmcp-utilities"

# Check if async_utils file exists
echo -e "\n=== Checking for async_utils specifically ==="
ls -1 docs/python-sdk/fastmcp-utilities-async_utils* 2>&1 || echo "File not found"

# Count total utilities files
echo -e "\n=== Total utilities files ==="
ls -1 docs/python-sdk/ | grep "^fastmcp-utilities" | wc -l

Repository: jlowin/fastmcp

Length of output: 1549

Create the missing documentation file for the async_utils SDK reference page.

The navigation entry python-sdk/fastmcp-utilities-async_utils was added to docs.json at line 477, but the corresponding documentation file docs/python-sdk/fastmcp-utilities-async_utils.mdx does not exist. This creates a broken navigation link. The source module exists at src/fastmcp/utilities/async_utils.py, so generate the documentation file to match the other 31 SDK reference pages in the utilities module.

"python-sdk/fastmcp-utilities-auth",
"python-sdk/fastmcp-utilities-cli",
"python-sdk/fastmcp-utilities-components",
Expand Down Expand Up @@ -543,12 +542,20 @@
},
"redirects": [
{
"destination": "/servers/proxy",
"destination": "/servers/providers/proxy",
"source": "/patterns/proxy"
},
{
"destination": "/servers/composition",
"destination": "/servers/providers/mounting",
"source": "/patterns/composition"
},
{
"destination": "/servers/providers/proxy",
"source": "/servers/proxy"
},
{
"destination": "/servers/providers/mounting",
"source": "/servers/composition"
}
],
"search": {
Expand Down
4 changes: 4 additions & 0 deletions docs/integrations/fastapi.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,10 @@ FastMCP provides two powerful ways to integrate with FastAPI applications:
1. **[Generate an MCP server FROM your FastAPI app](#generating-an-mcp-server)** - Convert existing API endpoints into MCP tools
2. **[Mount an MCP server INTO your FastAPI app](#mounting-an-mcp-server)** - Add MCP functionality to your web application

<Note>
When generating an MCP server from FastAPI, FastMCP uses OpenAPIProvider (v3.0.0+) under the hood to source tools from your FastAPI app's OpenAPI spec. See [Providers](/servers/providers/overview) to understand how FastMCP sources components.
</Note>


<Tip>
Generating MCP servers from OpenAPI is a great way to get started with FastMCP, but in practice LLMs achieve **significantly better performance** with well-designed and curated MCP servers than with auto-converted OpenAPI servers. This is especially true for complex APIs with many endpoints and parameters.
Expand Down
4 changes: 4 additions & 0 deletions docs/integrations/openapi.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,10 @@ import { VersionBadge } from '/snippets/version-badge.mdx'

FastMCP can automatically generate an MCP server from any OpenAPI specification, allowing AI models to interact with existing APIs through the MCP protocol. Instead of manually creating tools and resources, you provide an OpenAPI spec and FastMCP intelligently converts API endpoints into the appropriate MCP components.

<Note>
Under the hood, OpenAPI integration uses OpenAPIProvider (v3.0.0+) to source tools from the specification. See [Providers](/servers/providers/overview) to understand how FastMCP sources components.
</Note>

<Tip>
Generating MCP servers from OpenAPI is a great way to get started with FastMCP, but in practice LLMs achieve **significantly better performance** with well-designed and curated MCP servers than with auto-converted OpenAPI servers. This is especially true for complex APIs with many endpoints and parameters.

Expand Down
2 changes: 1 addition & 1 deletion docs/patterns/tool-transformation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -698,7 +698,7 @@ This pattern provides several benefits:
- **Scalable**: Easily add new tools by wrapping additional client methods

### Adapting Remote or Generated Tools
This is one of the most common reasons to use tool transformation. Tools from remote MCP servers (via a [proxy](/servers/proxy)) or generated from an [OpenAPI spec](/integrations/openapi) are often too generic for direct use by an LLM. You can use transformation to create a simpler, more intuitive version for your specific needs.
This is one of the most common reasons to use tool transformation. Tools from remote MCP servers (via a [proxy](/servers/providers/proxy)) or generated from an [OpenAPI spec](/integrations/openapi) are often too generic for direct use by an LLM. You can use transformation to create a simpler, more intuitive version for your specific needs.

### Chaining Transformations
You can chain transformations by using an already transformed tool as the parent for a new transformation. This lets you build up complex behaviors in layers, for example, first renaming arguments, and then adding validation logic to the renamed tool.
Expand Down
Loading
Loading