Merge pull request #1103 from jlowin/docs

.gitignore

@@ -60,3 +60,6 @@ dmypy.json
 *.sqlite
 *.db
 *.ddb
+
+# Claude worktree management
+.claude-wt/worktrees

docs/clients/transports.mdx

@@ -1,7 +1,7 @@
 ---
 title: Client Transports
 sidebarTitle: Transports
-description: Understand the different ways FastMCP Clients can connect to servers.
+description: Configure how FastMCP Clients connect to and communicate with servers.
 icon: link
 ---
 
@@ -9,441 +9,302 @@ import { VersionBadge } from "/snippets/version-badge.mdx"
 
 <VersionBadge version="2.0.0" />
 
-The FastMCP `Client` relies on a `ClientTransport` object to handle the specifics of connecting to and communicating with an MCP server. FastMCP provides several built-in transport implementations for common connection methods.
+The FastMCP `Client` communicates with MCP servers through transport objects that handle the underlying connection mechanics. While the client can automatically select a transport based on what you pass to it, instantiating transports explicitly gives you full control over configuration—environment variables, authentication, session management, and more.
 
-While the `Client` often infers the correct transport automatically (see [Client Overview](/clients/client#transport-inference)), you can also instantiate transports explicitly for more control.
+Think of transports as configurable adapters between your client code and MCP servers. Each transport type handles a different communication pattern: subprocesses with pipes, HTTP connections, or direct in-memory calls.
 
-<Tip>
-Clients are lightweight objects, so don't hesitate to create new ones as needed. However, be mindful of the context management - each time you open a client context (`async with client:`), a new connection or process starts. For best performance, keep client contexts open while performing multiple operations rather than repeatedly opening and closing them.
-</Tip>
+## Choosing the Right Transport
 
-## Choosing a Transport
+- **Use [STDIO Transport](#stdio-transport)** when you need to run local MCP servers with full control over their environment and lifecycle
+- **Use [Remote Transports](#remote-transports)** when connecting to production services or shared MCP servers running independently  
+- **Use [In-Memory Transport](#in-memory-transport)** for testing FastMCP servers without subprocess or network overhead
+- **Use [MCP JSON Configuration](#mcp-json-configuration-transport)** when you need to connect to multiple servers defined in configuration files
 
-Choose the transport that best fits your use case:
+## STDIO Transport
 
-- **Connecting to Remote/Persistent Servers:** Use `StreamableHttpTransport` (recommended, default for HTTP URLs) or `SSETransport` (legacy option) for web-based deployments.
+STDIO (Standard Input/Output) transport communicates with MCP servers through subprocess pipes. This is the standard mechanism used by desktop clients like Claude Desktop and is the primary way to run local MCP servers.
 
-- **Local Development/Testing:** Use `FastMCPTransport` for in-memory, same-process testing of your FastMCP servers.
+### The Client Runs the Server
 
-- **Running Local Servers:** Use `UvxStdioTransport` (Python/uv) or `NpxStdioTransport` (Node/npm) if you need to run MCP servers as packaged tools.
-
-## Network Transports
-
-These transports connect to servers running over a network, typically long-running services accessible via URLs.
-
-### Streamable HTTP
+<Warning>
+**Critical Concept**: When using STDIO transport, your client actually launches and manages the server process. This is fundamentally different from network transports where you connect to an already-running server. Understanding this relationship is key to using STDIO effectively.
+</Warning>
 
-<VersionBadge version="2.3.0" />
+With STDIO transport, your client:
+- Starts the server as a subprocess when you connect
+- Manages the server's lifecycle (start, stop, restart)
+- Controls the server's environment and configuration
+- Communicates through stdin/stdout pipes
 
-Streamable HTTP is the recommended transport for web-based deployments, providing efficient bidirectional communication over HTTP.
+This architecture enables powerful local integrations but requires understanding environment isolation and process management.
 
-#### Overview
+### Environment Isolation
 
-- **Class:** `fastmcp.client.transports.StreamableHttpTransport`
-- **Inferred From:** URLs starting with `http://` or `https://` (default for HTTP URLs since v2.3.0) that do not contain `/sse/` in the path
-- **Server Compatibility:** Works with FastMCP servers running in `http` mode
+STDIO servers run in isolated environments by default. This is a security feature enforced by the MCP protocol to prevent accidental exposure of sensitive data.
 
-#### Basic Usage
+When your client launches an MCP server:
+- The server does NOT inherit your shell's environment variables
+- API keys, paths, and other configuration must be explicitly passed
+- The working directory and system paths may differ from your shell
 
-The simplest way to use Streamable HTTP is to let the transport be inferred from a URL:
+To pass environment variables to your server, use the `env` parameter:
 
 ```python
 from fastmcp import Client
-import asyncio
-
-# The Client automatically uses StreamableHttpTransport for HTTP URLs
-client = Client("https://example.com/mcp")
-
-async def main():
-    async with client:
-        tools = await client.list_tools()
-        print(f"Available tools: {tools}")
-
-asyncio.run(main())
-```
-
-You can also explicitly instantiate the transport:
 
-```python
-from fastmcp.client.transports import StreamableHttpTransport
+# If your server needs environment variables (like API keys),
+# you must explicitly pass them:
+client = Client(
+    "my_server.py",
+    env={"API_KEY": "secret", "DEBUG": "true"}
+)
 
-transport = StreamableHttpTransport(url="https://example.com/mcp")
-client = Client(transport)
+# This won't work - the server runs in isolation:
+# export API_KEY="secret"  # in your shell
+# client = Client("my_server.py")  # server can't see API_KEY
 ```
 
-#### Authentication with Headers
+### Basic Usage
 
-For servers requiring authentication:
+To use STDIO transport, you create a transport instance with the command and arguments needed to run your server:
 
 ```python
-from fastmcp import Client
-from fastmcp.client.transports import StreamableHttpTransport
+from fastmcp.client.transports import StdioTransport
 
-# Create transport with authentication headers
-transport = StreamableHttpTransport(
-    url="https://example.com/mcp",
-    headers={"Authorization": "Bearer your-token-here"}
+transport = StdioTransport(
+    command="python",
+    args=["my_server.py"]
 )
-
 client = Client(transport)
 ```
 
-This can be written more concisely using the `BearerAuth` helper function:
+You can configure additional settings like environment variables, working directory, or command arguments:
 
 ```python
-from fastmcp import Client
-from fastmcp.client.auth import BearerAuth
-
-client = Client(
-    "https://example.com/mcp",
-    auth=BearerAuth("your-token-here"),
+transport = StdioTransport(
+    command="python",
+    args=["my_server.py", "--verbose"],
+    env={"LOG_LEVEL": "DEBUG"},
+    cwd="/path/to/server"
 )
+client = Client(transport)
 ```
 
-### SSE (Server-Sent Events)
-
-<VersionBadge version="2.0.0" />
-
-Server-Sent Events (SSE) is a transport that allows servers to push data to clients over HTTP connections. While still supported, Streamable HTTP is now the recommended transport for new web-based deployments.
-
-#### Overview
-
-- **Class:** `fastmcp.client.transports.SSETransport`
-- **Inferred From:** HTTP URLs containing `/sse/` in the path
-- **Server Compatibility:** Works with FastMCP servers running in `sse` mode
-
-#### Basic Usage
-
-The simplest way to use SSE is to let the transport be inferred from a URL with `/sse/` in the path:
+For convenience, the client can also infer STDIO transport from file paths, but this doesn't allow configuration:
 
 ```python
 from fastmcp import Client
-import asyncio
 
-# The Client automatically uses SSETransport for URLs containing /sse/ in the path
-client = Client("https://example.com/sse")
+client = Client("my_server.py")  # Limited - no configuration options
+```
 
-async def main():
-    async with client:
-        tools = await client.list_tools()
-        print(f"Available tools: {tools}")
+### Environment Variables
 
-asyncio.run(main())
-```
+Since STDIO servers don't inherit your environment, you need strategies for passing configuration. Here are two common approaches:
 
-You can also explicitly instantiate the transport for URLs that do not contain `/sse/` in the path or for more control: 
+**Selective forwarding** passes only the variables your server actually needs:
 
 ```python
-from fastmcp.client.transports import SSETransport
+import os
+from fastmcp.client.transports import StdioTransport
+
+required_vars = ["API_KEY", "DATABASE_URL", "REDIS_HOST"]
+env = {
+    var: os.environ[var] 
+    for var in required_vars 
+    if var in os.environ
+}
 
-transport = SSETransport(url="https://example.com/sse")
+transport = StdioTransport(
+    command="python",
+    args=["server.py"],
+    env=env
+)
 client = Client(transport)
 ```
 
-#### Authentication with Headers
-
-SSE transport also supports custom headers for authentication:
+**Loading from .env files** keeps configuration separate from code:
 
 ```python
-from fastmcp import Client
-from fastmcp.client.transports import SSETransport
-
-# Create SSE transport with authentication headers
-transport = SSETransport(
-    url="https://example.com/sse",
-    headers={"Authorization": "Bearer your-token-here"}
+from dotenv import dotenv_values
+from fastmcp.client.transports import StdioTransport
+
+env = dotenv_values(".env")
+transport = StdioTransport(
+    command="python",
+    args=["server.py"],
+    env=env
 )
-
 client = Client(transport)
 ```
 
-#### When to Use SSE vs. Streamable HTTP
-
-- **Use Streamable HTTP when:**
-  - Setting up new deployments (recommended default)
-  - You need bidirectional streaming
-  - You're connecting to FastMCP servers running in `http` mode
-
-- **Use SSE when:**
-  - Connecting to legacy FastMCP servers running in `sse` mode
-  - Working with infrastructure optimized for Server-Sent Events
-
-## Local Transports
+### Session Persistence
 
-These transports manage an MCP server running as a subprocess, communicating with it via standard input (stdin) and standard output (stdout). This is the standard mechanism used by clients like Claude Desktop.
+STDIO transports maintain sessions across multiple client contexts by default (`keep_alive=True`). This improves performance by reusing the same subprocess for multiple connections, but can be controlled when you need isolation.
 
-### Session Management
-
-All stdio transports support a `keep_alive` parameter (default: `True`) that controls session persistence across multiple client context managers:
-
-- **`keep_alive=True` (default)**: The subprocess and session are maintained between client context exits and re-entries. This improves performance when making multiple separate connections to the same server.
-- **`keep_alive=False`**: A new subprocess is started for each client context, ensuring complete isolation between sessions.
-
-When `keep_alive=True`, you can manually close the session using `await client.close()` if needed. This will terminate the subprocess and require a new one to be started on the next connection.
-
-<CodeGroup>
-```python keep_alive=True
-from fastmcp import Client
-
-# Client with keep_alive=True (default)
-client = Client("my_mcp_server.py")
-
-async def example():
-    # First session
-    async with client:
-        await client.ping()
-
-    # Second session - uses the same subprocess
-    async with client:
-        await client.ping()
-
-    # Manually close the session
-    await client.close()
-
-    # Third session - will start a new subprocess
-    async with client:
-        await client.ping()
+By default, the subprocess persists between connections:
 
-asyncio.run(example())
-```
-```python keep_alive=False
-from fastmcp import Client
+```python
+from fastmcp.client.transports import StdioTransport
 
-# Client with keep_alive=False
-client = Client("my_mcp_server.py", keep_alive=False)
+transport = StdioTransport(
+    command="python",
+    args=["server.py"]
+)
+client = Client(transport)
 
-async def example():
-    # First session
+async def efficient_multiple_operations():
     async with client:
         await client.ping()
     
-    # Second session - will start a new subprocess
-    async with client:
-        await client.ping()
+    async with client:  # Reuses the same subprocess
+        await client.call_tool("process_data", {"file": "data.csv"})
+```
 
-    # Third session - will start a new subprocess
-    async with client:
-        await client.ping()
+For complete isolation between connections, disable session persistence:
 
-asyncio.run(example())
+```python
+transport = StdioTransport(
+    command="python",
+    args=["server.py"],
+    keep_alive=False
+)
+client = Client(transport)
 ```
-</CodeGroup>
-
-### Python Stdio
 
-- **Class:** `fastmcp.client.transports.PythonStdioTransport`
-- **Inferred From:** Paths to `.py` files
-- **Use Case:** Running a Python-based MCP server script in a subprocess
+Use `keep_alive=False` when you need complete isolation (e.g., in test suites) or when server state could cause issues between connections.
 
-This is the most common way to interact with local FastMCP servers during development or when integrating with tools that expect to launch a server script.
+### Specialized STDIO Transports
 
-```python
-from fastmcp import Client
-from fastmcp.client.transports import PythonStdioTransport
+FastMCP provides convenience transports that are thin wrappers around `StdioTransport` with pre-configured commands:
 
-server_script = "my_mcp_server.py" # Path to your server script
+- **`PythonStdioTransport`** - Uses `python` command for `.py` files
+- **`NodeStdioTransport`** - Uses `node` command for `.js` files  
+- **`UvxStdioTransport`** - Uses `uvx` for Python packages (uses `env_vars` parameter)
+- **`NpxStdioTransport`** - Uses `npx` for Node packages (uses `env_vars` parameter)
 
-# Option 1: Inferred transport
-client = Client(server_script)
+For most use cases, instantiate `StdioTransport` directly with your desired command. These specialized transports are primarily useful for client inference shortcuts.
 
-# Option 2: Explicit transport with custom configuration
-transport = PythonStdioTransport(
-    script_path=server_script,
-    python_cmd="/usr/bin/python3.11", # Optional: specify Python interpreter
-    # args=["--some-server-arg"],      # Optional: pass arguments to the script
-    # env={"MY_VAR": "value"},         # Optional: set environment variables
-)
-client = Client(transport)
+## Remote Transports
 
-async def main():
-    async with client:
-        tools = await client.list_tools()
-        print(f"Connected via Python Stdio, found tools: {tools}")
+Remote transports connect to MCP servers running as web services. This is a fundamentally different model from STDIO transports—instead of your client launching and managing a server process, you connect to an already-running service that manages its own environment and lifecycle.
 
-asyncio.run(main())
-```
+### Streamable HTTP Transport
 
-<Warning>
-The server script must include logic to start the MCP server and listen on stdio, typically via `mcp.run()` or `fastmcp.server.run()`. The Client only launches the script; it doesn't inject the server logic.
-</Warning>
+<VersionBadge version="2.3.0" />
 
-### Node.js Stdio
+Streamable HTTP is the recommended transport for production deployments, providing efficient bidirectional streaming over HTTP connections.
 
-- **Class:** `fastmcp.client.transports.NodeStdioTransport`
-- **Inferred From:** Paths to `.js` files
-- **Use Case:** Running a Node.js-based MCP server script in a subprocess
+- **Class:** `StreamableHttpTransport`
+- **Server compatibility:** FastMCP servers running with `mcp run --transport http`
 
-Similar to the Python transport, but for JavaScript servers.
+The transport requires a URL and optionally supports custom headers for authentication and configuration:
 
 ```python
-from fastmcp import Client
-from fastmcp.client.transports import NodeStdioTransport
-
-node_server_script = "my_mcp_server.js" # Path to your Node.js server script
+from fastmcp.client.transports import StreamableHttpTransport
 
-# Option 1: Inferred transport
-client = Client(node_server_script)
+# Basic connection
+transport = StreamableHttpTransport(url="https://api.example.com/mcp")
+client = Client(transport)
 
-# Option 2: Explicit transport
-transport = NodeStdioTransport(
-    script_path=node_server_script,
-    node_cmd="node", # Optional: specify path to Node executable
+# With custom headers for authentication
+transport = StreamableHttpTransport(
+    url="https://api.example.com/mcp",
+    headers={
+        "Authorization": "Bearer your-token-here",
+        "X-Custom-Header": "value"
+    }
 )
 client = Client(transport)
-
-async def main():
-    async with client:
-        tools = await client.list_tools()
-        print(f"Connected via Node.js Stdio, found tools: {tools}")
-
-asyncio.run(main())
 ```
 
-### UVX Stdio (Experimental)
-
-- **Class:** `fastmcp.client.transports.UvxStdioTransport`
-- **Inferred From:** Not automatically inferred
-- **Use Case:** Running an MCP server packaged as a Python tool using [`uvx`](https://docs.astral.sh/uv/reference/cli/#uvx)
-
-This is useful for executing MCP servers distributed as command-line tools or packages without installing them into your environment.
+For convenience, FastMCP also provides authentication helpers:
 
 ```python
-from fastmcp import Client
-from fastmcp.client.transports import UvxStdioTransport
+from fastmcp.client.auth import BearerAuth
 
-# Run a hypothetical 'cloud-analyzer-mcp' tool via uvx
-transport = UvxStdioTransport(
-    tool_name="cloud-analyzer-mcp",
-    # from_package="cloud-analyzer-cli", # Optional: specify package if tool name differs
-    # with_packages=["boto3", "requests"] # Optional: add dependencies
+client = Client(
+    "https://api.example.com/mcp",
+    auth=BearerAuth("your-token-here")
 )
-client = Client(transport)
-
-async def main():
-    async with client:
-        result = await client.call_tool("analyze_bucket", {"name": "my-data"})
-        print(f"Analysis result: {result}")
-
-asyncio.run(main())
 ```
 
-### NPX Stdio (Experimental)
+### SSE Transport (Legacy)
+
+Server-Sent Events transport is maintained for backward compatibility but is superseded by Streamable HTTP for new deployments.
 
-- **Class:** `fastmcp.client.transports.NpxStdioTransport`
-- **Inferred From:** Not automatically inferred
-- **Use Case:** Running an MCP server packaged as an NPM package using `npx`
+- **Class:** `SSETransport`  
+- **Server compatibility:** FastMCP servers running with `mcp run --transport sse`
 
-Similar to `UvxStdioTransport`, but for the Node.js ecosystem.
+SSE transport supports the same configuration options as Streamable HTTP:
 
 ```python
-from fastmcp import Client
-from fastmcp.client.transports import NpxStdioTransport
+from fastmcp.client.transports import SSETransport
 
-# Run an MCP server from an NPM package
-transport = NpxStdioTransport(
-    package="mcp-server-package",
-    # args=["--port", "stdio"] # Optional: pass arguments to the package
+transport = SSETransport(
+    url="https://api.example.com/sse",
+    headers={"Authorization": "Bearer token"}
 )
 client = Client(transport)
-
-async def main():
-    async with client:
-        result = await client.call_tool("get_npm_data", {})
-        print(f"Result: {result}")
-
-asyncio.run(main())
 ```
 
-## In-Memory Transports
+Use Streamable HTTP for new deployments unless you have specific infrastructure requirements for SSE.
 
-### FastMCP Transport
+## In-Memory Transport
 
-- **Class:** `fastmcp.client.transports.FastMCPTransport`
-- **Inferred From:** An instance of `fastmcp.server.FastMCP` or a **FastMCP 1.0 server** (`mcp.server.fastmcp.FastMCP`)
-- **Use Case:** Connecting directly to a FastMCP server instance in the same Python process
+In-memory transport connects directly to a FastMCP server instance within the same Python process. This eliminates both subprocess management and network overhead, making it ideal for testing and development.
 
-This is extremely useful for testing your FastMCP servers.
+- **Class:** `FastMCPTransport`
+
+<Note>
+Unlike STDIO transports, in-memory servers have full access to your Python process's environment. They share the same memory space and environment variables as your client code—no isolation or explicit environment passing required.
+</Note>
 
 ```python
 from fastmcp import FastMCP, Client
-import asyncio
-
-# 1. Create your FastMCP server instance
-server = FastMCP(name="InMemoryServer")
+import os
 
-@server.tool
-def ping(): 
-    return "pong"
+mcp = FastMCP("TestServer")
 
-# 2. Create a client pointing directly to the server instance
-client = Client(server)  # Transport is automatically inferred
+@mcp.tool
+def greet(name: str) -> str:
+    prefix = os.environ.get("GREETING_PREFIX", "Hello")
+    return f"{prefix}, {name}!"
 
-async def main():
-    async with client:
-        result = await client.call_tool("ping")
-        print(f"In-memory call result: {result}")
+client = Client(mcp)
 
-asyncio.run(main())
+async with client:
+    result = await client.call_tool("greet", {"name": "World"})
 ```
 
-Communication happens through efficient in-memory queues, making it very fast and ideal for unit testing. 
-
-## Configuration-Based Transports
-
-### MCPConfig Transport
+## MCP JSON Configuration Transport
 
 <VersionBadge version="2.4.0" />
 
-- **Class:** `fastmcp.client.transports.MCPConfigTransport`
-- **Inferred From:** An instance of `MCPConfig` or a dictionary matching the MCPConfig schema
-- **Use Case:** Connecting to one or more MCP servers defined in a configuration object
+This transport supports the emerging MCP JSON configuration standard for defining multiple servers:
 
-MCPConfig follows an emerging standard for MCP server configuration but is subject to change as the specification evolves. The standard supports both local servers (running via stdio) and remote servers (accessed via HTTP).
+- **Class:** `MCPConfigTransport`
 
 ```python
-from fastmcp import Client
-
-# Configuration for multiple MCP servers (both local and remote)
 config = {
     "mcpServers": {
-        # Remote HTTP server
         "weather": {
-            "url": "https://weather-api.example.com/mcp",
+            "url": "https://weather.example.com/mcp",
             "transport": "http"
         },
-        # Local stdio server
         "assistant": {
             "command": "python",
-            "args": ["./assistant_server.py"],
-            "env": {"DEBUG": "true"}
-        },
-        # Another remote server
-        "calendar": {
-            "url": "https://calendar-api.example.com/mcp",
-            "transport": "http"
+            "args": ["./assistant.py"],
+            "env": {"LOG_LEVEL": "INFO"}
         }
     }
 }
 
-# Create a transport from the config (happens automatically with Client)
 client = Client(config)
 
-async def main():
-    async with client:
-        # Tools are accessible with server name prefixes
-        weather = await client.call_tool("weather_get_forecast", {"city": "London"})
-        answer = await client.call_tool("assistant_answer_question", {"query": "What is MCP?"})
-        events = await client.call_tool("calendar_list_events", {"date": "2023-06-01"})
-        
-        # Resources use prefixed URI paths
-        icons = await client.read_resource("weather://weather/icons/sunny")
-        docs = await client.read_resource("resource://assistant/docs/mcp")
-
-asyncio.run(main())
+async with client:
+    # Tools are namespaced by server
+    weather = await client.call_tool("weather_get_forecast", {"city": "NYC"})
+    answer = await client.call_tool("assistant_ask", {"question": "What?"})
 ```
 
-If your configuration has only a single server, the client will connect directly to that server without any prefixing. This makes it convenient to switch between single and multi-server configurations without changing your client code.
-
-<Note>
-The MCPConfig format is an emerging standard for MCP server configuration and may change as the MCP ecosystem evolves. While FastMCP aims to maintain compatibility with future versions, be aware that field names or structure might change.
-</Note>

docs/docs.json

@@ -62,7 +62,11 @@
               {
                 "group": "Servers",
                 "pages": [
-                  "servers/server",
+                  {
+                    "group": "Essentials",
+                    "icon": "cube",
+                    "pages": ["servers/server", "deployment/running-server"]
+                  },
                   {
                     "group": "Core Components",
                     "icon": "toolbox",
@@ -80,29 +84,27 @@
                       "servers/elicitation",
                       "servers/logging",
                       "servers/progress",
-                      "servers/sampling"
+                      "servers/sampling",
+                      "servers/middleware",
+                      "servers/composition",
+                      "servers/proxy"
                     ]
                   },
                   {
                     "group": "Authentication",
                     "icon": "shield-check",
                     "pages": ["servers/auth/bearer"]
-                  },
-                  "servers/middleware",
-                  "servers/openapi",
-                  "servers/proxy",
-                  "servers/composition",
-                  {
-                    "group": "Deployment",
-                    "icon": "upload",
-                    "pages": ["deployment/running-server", "deployment/asgi"]
                   }
                 ]
               },
               {
                 "group": "Clients",
                 "pages": [
-                  "clients/client",
+                  {
+                    "group": "Essentials",
+                    "icon": "cube",
+                    "pages": ["clients/client", "clients/transports"]
+                  },
                   {
                     "group": "Core Operations",
                     "icon": "handshake",
@@ -124,7 +126,6 @@
                       "clients/roots"
                     ]
                   },
-                  "clients/transports",
                   {
                     "group": "Authentication",
                     "icon": "user-shield",
@@ -141,9 +142,12 @@
                   "integrations/claude-desktop",
                   "integrations/cursor",
                   "integrations/eunomia-authorization",
+                  "integrations/fastapi",
                   "integrations/gemini",
                   "integrations/mcp-json-configuration",
-                  "integrations/openai"
+                  "integrations/openai",
+                  "integrations/openapi",
+                  "integrations/starlette"
                 ]
               },
               {

docs/integrations/fastapi.mdx

@@ -0,0 +1,229 @@
+---
+title: FastAPI 🤝 FastMCP
+sidebarTitle: FastAPI
+description: Integrate FastMCP with FastAPI applications
+icon: bolt
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+FastMCP provides two powerful ways to integrate with FastAPI applications, both of which are documented below.
+
+1. You can [generate an MCP server FROM your FastAPI app](#generating-an-mcp-server) by converting existing API endpoints into MCP tools. This is useful for bootstrapping and quickly attaching LLMs to your API.
+2. You can [mount an MCP server INTO your FastAPI app](#mounting-an-mcp-server) by adding MCP functionality to your web application. This is useful for exposing your MCP tools alongside regular API endpoints.
+
+You can even combine both approaches to create a single FastAPI app that serves both regular API endpoints and MCP tools!
+
+<Tip>
+Generating MCP servers from FastAPI apps 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 FastAPI servers. This is especially true for complex APIs with many endpoints and parameters.
+</Tip>
+
+<Note>
+FastMCP does *not* include FastAPI as a dependency; you must install it separately to use this integration.
+</Note>
+
+## Generating an MCP Server
+
+<VersionBadge version="2.0.0" />
+
+FastMCP can directly convert your existing FastAPI applications into MCP servers, allowing AI models to interact with your API endpoints through the MCP protocol.
+
+
+<Tip>
+Under the hood, the FastAPI integration is built on top of FastMCP's OpenAPI integration. See the [OpenAPI docs](/integrations/openapi) for more details.
+</Tip>
+
+### Create a Server
+
+The simplest way to convert a FastAPI app is using the `FastMCP.from_fastapi()` method:
+
+```python server.py
+from fastapi import FastAPI
+from fastmcp import FastMCP
+
+# Your existing FastAPI app
+app = FastAPI(title="My API", version="1.0.0")
+
+@app.get("/items", tags=["items"], operation_id="list_items")
+def list_items():
+    return [{"id": 1, "name": "Item 1"}, {"id": 2, "name": "Item 2"}]
+
+@app.get("/items/{item_id}", tags=["items", "detail"], operation_id="get_item")
+def get_item(item_id: int):
+    return {"id": item_id, "name": f"Item {item_id}"}
+
+@app.post("/items", tags=["items", "create"], operation_id="create_item")
+def create_item(name: str):
+    return {"id": 3, "name": name}
+
+# Convert FastAPI app to MCP server
+mcp = FastMCP.from_fastapi(app=app)
+
+if __name__ == "__main__":
+    mcp.run()  # Run as MCP server
+```
+
+### Component Mapping
+
+By default, FastMCP converts **every endpoint** in your FastAPI app into an MCP **Tool**. This provides maximum compatibility with LLM clients that primarily support MCP tools.
+
+You can customize this behavior using route maps to control which endpoints become tools, resources, or resource templates:
+
+```python
+from fastmcp.server.openapi import RouteMap, MCPType
+
+# Custom route mapping
+mcp = FastMCP.from_fastapi(
+    app=app,
+    route_maps=[
+        # GET requests with path parameters become ResourceTemplates
+        RouteMap(methods=["GET"], pattern=r".*\{.*\}.*", mcp_type=MCPType.RESOURCE_TEMPLATE),
+        # All other GET requests become Resources
+        RouteMap(methods=["GET"], pattern=r".*", mcp_type=MCPType.RESOURCE),
+        # POST/PUT/DELETE become Tools (handled by default rule)
+    ],
+)
+```
+
+The `FastMCP.from_fastapi()` method accepts all the same configuration options as `FastMCP.from_openapi()`, including route maps, custom tags, component naming, timeouts, and component customization functions. For comprehensive configuration details, see the [OpenAPI Integration guide](/integrations/openapi).
+
+### Key Considerations
+
+#### Operation IDs
+
+FastMCP uses your FastAPI operation IDs to name MCP components. Ensure your endpoints have meaningful operation IDs:
+
+```python
+@app.get("/users/{user_id}", operation_id="get_user_detail")  # ✅ Good
+@app.get("/users/{user_id}")  # ❌ Auto-generated name might be unclear
+```
+
+#### Pydantic Models
+
+Your Pydantic models are automatically converted to JSON schema for MCP tool parameters:
+
+```python
+from pydantic import BaseModel
+
+class CreateItemRequest(BaseModel):
+    name: str
+    description: str | None = None
+    price: float
+
+@app.post("/items")
+def create_item(item: CreateItemRequest):
+    return {"id": 123, **item.dict()}
+```
+
+The MCP tool will have properly typed parameters matching your Pydantic model.
+
+#### Error Handling
+
+FastAPI error handling carries over to the MCP server. HTTPExceptions are automatically converted to appropriate MCP errors.
+
+Since FastAPI integration is built on OpenAPI, all the same configuration options are available including authentication setup, timeout configuration, and request parameter handling. For detailed information on these features, see the [OpenAPI Integration guide](/integrations/openapi).
+
+## Mounting an MCP Server
+
+<VersionBadge version="2.3.1" />
+
+You can also mount an existing FastMCP server into your FastAPI application, adding MCP functionality to your web application. This is useful for exposing your MCP tools alongside regular API endpoints.
+
+### Basic Integration
+
+```python
+from fastmcp import FastMCP
+from fastapi import FastAPI
+from starlette.routing import Mount
+
+# Create your FastMCP server
+mcp = FastMCP("MyServer")
+
+@mcp.tool
+def analyze_data(query: str) -> dict:
+    """Analyze data based on the query."""
+    return {"result": f"Analysis for: {query}"}
+
+# Create the ASGI app from your MCP server
+mcp_app = mcp.http_app(path='/mcp')
+
+# Create a FastAPI app and mount the MCP server
+app = FastAPI(lifespan=mcp_app.lifespan)
+app.mount("/mcp-server", mcp_app)
+
+# Add regular FastAPI routes
+@app.get("/health")
+def health_check():
+    return {"status": "healthy"}
+```
+
+The MCP endpoint will be available at `/mcp-server/mcp/` of your FastAPI application.
+
+<Warning>
+For Streamable HTTP transport, you **must** pass the lifespan context from the FastMCP app to the FastAPI app. Otherwise, the FastMCP server's session manager will not be properly initialized.
+</Warning>
+
+### Advanced Integration
+
+You can combine both approaches - generate an MCP server from your FastAPI app AND mount additional MCP servers:
+
+```python
+from fastmcp import FastMCP
+from fastapi import FastAPI
+
+# Your existing FastAPI app
+app = FastAPI()
+
+@app.get("/items")
+def list_items():
+    return [{"id": 1, "name": "Item 1"}]
+
+# Generate MCP server from FastAPI app
+api_mcp = FastMCP.from_fastapi(app=app, name="API Server")
+
+# Create additional purpose-built MCP server
+tools_mcp = FastMCP("Tools Server")
+
+@tools_mcp.tool
+def advanced_analysis(data: dict) -> dict:
+    """Perform advanced analysis not available via API."""
+    return {"analysis": "complex results"}
+
+# Mount the tools server into the same FastAPI app
+tools_app = tools_mcp.http_app(path='/mcp')
+app.mount("/tools", tools_app, lifespan=tools_app.lifespan)
+```
+
+Now you have:
+- API endpoints converted to MCP tools (via `api_mcp`)
+- Additional MCP tools available at `/tools/mcp/`
+- Regular FastAPI endpoints at their original paths
+
+### Authentication and Middleware
+
+When mounting MCP servers into FastAPI, you can leverage FastAPI's authentication and middleware:
+
+```python
+from fastapi import FastAPI, Depends, HTTPException
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+
+security = HTTPBearer()
+
+def verify_token(credentials: HTTPAuthorizationCredentials = Depends(security)):
+    if credentials.credentials != "secret-token":
+        raise HTTPException(status_code=401, detail="Invalid token")
+    return credentials
+
+app = FastAPI()
+
+# Mount MCP server with authentication
+@app.get("/secure")
+def secure_endpoint(auth=Depends(verify_token)):
+    return {"message": "Authenticated"}
+
+# The mounted MCP server inherits the app's security
+mcp_app = mcp.http_app()
+app.mount("/mcp", mcp_app, lifespan=mcp_app.lifespan)
+```
+
+For more advanced ASGI integration patterns, see the [ASGI Integration guide](/integrations/asgi).

docs/{servers → integrations}/openapi.mdx

@@ -1,21 +1,25 @@
 ---
-title: OpenAPI Integration
-sidebarTitle: OpenAPI Integration
-description: Generate MCP servers from OpenAPI specs and FastAPI apps
-icon: code-branch
+title: OpenAPI 🤝 FastMCP
+sidebarTitle: OpenAPI
+description: Generate MCP servers from any OpenAPI specification
+icon: list-tree
 ---
+
 import { VersionBadge } from '/snippets/version-badge.mdx'
 
 <VersionBadge version="2.0.0" />
 
-FastMCP can automatically generate an MCP server from an OpenAPI specification or FastAPI app. Instead of manually creating tools and resources, you provide an OpenAPI spec and FastMCP intelligently converts your API endpoints into the appropriate MCP components.
+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.
+
+<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.
+</Tip>
 
-## Quick Start
+## Create a Server
 
-To convert an OpenAPI specification to an MCP server, you can use the `FastMCP.from_openapi` class method. This method takes an OpenAPI specification and an async HTTPX client that can be used to make requests to the API, and returns an MCP server.
+To convert an OpenAPI specification to an MCP server, use the `FastMCP.from_openapi()` class method:
 
-Here's an example:
-```python {11-15}
+```python server.py
 import httpx
 from fastmcp import FastMCP
 
@@ -36,8 +40,27 @@ if __name__ == "__main__":
     mcp.run()
 ```
 
-That's it! Your entire API is now available as an MCP server. Clients can discover and interact with your API endpoints through the MCP protocol, with full schema validation and type safety.
+### Authentication
+
+If your API requires authentication, configure it on the HTTP client:
+
+```python
+import httpx
+from fastmcp import FastMCP
+
+# Bearer token authentication
+api_client = httpx.AsyncClient(
+    base_url="https://api.example.com",
+    headers={"Authorization": "Bearer YOUR_TOKEN"}
+)
 
+# Create MCP server with authenticated client
+mcp = FastMCP.from_openapi(
+    openapi_spec=spec, 
+    client=api_client,
+    timeout=30.0  # 30 second timeout for all requests
+)
+```
 
 ## Route Mapping
 
@@ -51,7 +74,7 @@ Each `RouteMap` specifies a combination of methods, patterns, and tags, as well
 - **Pattern**: Regex pattern to match the route path (e.g. `r"^/users/.*"` or `r".*"` for all)
 - **Tags**: A set of OpenAPI tags that must all be present. An empty set (`{}`) means no tag filtering, so the route matches regardless of its tags.
 - **MCP type**: What MCP component type to create (`TOOL`, `RESOURCE`, `RESOURCE_TEMPLATE`, or `EXCLUDE`)
-- **MCP tags** A set of custom tags to add to components created from matching routes
+- **MCP tags**: A set of custom tags to add to components created from matching routes
 
 Here is FastMCP's default rule:
 
@@ -70,7 +93,7 @@ When creating your FastMCP server, you can customize routing behavior by providi
 
 For example, prior to FastMCP 2.8.0, GET requests were automatically mapped to `Resource` and `ResourceTemplate` components based on whether they had path parameters. (This was changed solely for client compatibility reasons.) You can restore this behavior by providing custom route maps:
 
-```python {2, 5-10}
+```python
 from fastmcp import FastMCP
 from fastmcp.server.openapi import RouteMap, MCPType
 
@@ -83,7 +106,8 @@ semantic_maps = [
 ]
 
 mcp = FastMCP.from_openapi(
-    ...,
+    openapi_spec=spec,
+    client=client,
     route_maps=semantic_maps,
 )
 ```
@@ -97,9 +121,9 @@ from fastmcp import FastMCP
 from fastmcp.server.openapi import RouteMap, MCPType
 
 mcp = FastMCP.from_openapi(
-    ...,
+    openapi_spec=spec,
+    client=client,
     route_maps=[
-
         # Analytics `GET` endpoints are tools
         RouteMap(
             methods=["GET"], 
@@ -132,12 +156,13 @@ To exclude routes from the MCP server, use a route map to assign them to `MCPTyp
 
 You can use this to remove sensitive or internal routes by targeting them specifically:
 
-```python {7,8}
+```python
 from fastmcp import FastMCP
 from fastmcp.server.openapi import RouteMap, MCPType
 
 mcp = FastMCP.from_openapi(
-    ...,
+    openapi_spec=spec,
+    client=client,
     route_maps=[
         RouteMap(pattern=r"^/admin/.*", mcp_type=MCPType.EXCLUDE),
         RouteMap(tags={"internal"}, mcp_type=MCPType.EXCLUDE),
@@ -146,15 +171,17 @@ mcp = FastMCP.from_openapi(
 ```
 
 Or you can use a catch-all rule to exclude everything that your maps don't handle explicitly:
-```python {10}
+
+```python
 from fastmcp import FastMCP
 from fastmcp.server.openapi import RouteMap, MCPType
 
 mcp = FastMCP.from_openapi(
-    ...,
+    openapi_spec=spec,
+    client=client,
     route_maps=[
         # custom mapping logic goes here
-        ...,
+        # ... your specific route maps ...
         # exclude all remaining routes
         RouteMap(mcp_type=MCPType.EXCLUDE),
     ],
@@ -165,7 +192,6 @@ mcp = FastMCP.from_openapi(
 Using a catch-all exclusion rule will prevent the default route mappings from being applied, since it will match every remaining route. This is useful if you want to explicitly allow-list certain routes.
 </Tip>
 
-
 ### Advanced Route Mapping
 
 <VersionBadge version="2.5.0" />
@@ -178,7 +204,6 @@ In addition to more precise targeting of methods, patterns, and tags, this funct
 The `route_map_fn` **is** called on routes that matched `MCPType.EXCLUDE` in your custom maps, giving you an opportunity to override the exclusion.
 </Tip>
 
-
 ```python
 from fastmcp import FastMCP
 from fastmcp.server.openapi import RouteMap, MCPType, HTTPRoute
@@ -200,12 +225,40 @@ def custom_route_mapper(route: HTTPRoute, mcp_type: MCPType) -> MCPType | None:
     return None
 
 mcp = FastMCP.from_openapi(
-    ...,
+    openapi_spec=spec,
+    client=client,
     route_map_fn=custom_route_mapper,
 )
 ```
 
-## Customizing MCP Components
+## Customization
+
+### Component Names
+
+<VersionBadge version="2.5.0" />
+
+FastMCP automatically generates names for MCP components based on the OpenAPI specification. By default, it uses the `operationId` from your OpenAPI spec, up to the first double underscore (`__`).
+
+All component names are automatically:
+- **Slugified**: Spaces and special characters are converted to underscores or removed
+- **Truncated**: Limited to 56 characters maximum to ensure compatibility
+- **Unique**: If multiple components have the same name, a number is automatically appended to make them unique
+
+For more control over component names, you can provide an `mcp_names` dictionary that maps `operationId` values to your desired names. The `operationId` must be exactly as it appears in the OpenAPI spec. The provided name will always be slugified and truncated.
+
+```python
+mcp = FastMCP.from_openapi(
+    openapi_spec=spec,
+    client=client,
+    mcp_names={
+        "list_users__with_pagination": "user_list",
+        "create_user__admin_required": "create_user", 
+        "get_user_details__admin_required": "user_detail",
+    }
+)
+```
+
+Any `operationId` not found in `mcp_names` will use the default strategy (operationId up to the first `__`).
 
 ### Tags
 
@@ -217,12 +270,12 @@ FastMCP provides several ways to add tags to your MCP components, allowing you t
 
 You can add custom tags to components created from specific routes using the `mcp_tags` parameter in `RouteMap`. These tags will be applied to all components created from routes that match that particular route map.
 
-```python {12, 20, 28}
-from fastmcp import FastMCP
+```python
 from fastmcp.server.openapi import RouteMap, MCPType
 
 mcp = FastMCP.from_openapi(
-    ...,
+    openapi_spec=spec,
+    client=client,
     route_maps=[
         # Add custom tags to all POST endpoints
         RouteMap(
@@ -253,59 +306,18 @@ mcp = FastMCP.from_openapi(
 
 #### Global Tags
 
-You can add tags to **all** components by providing a `tags` parameter when creating your FastMCP server with `from_openapi` or `from_fastapi`. These global tags will be applied to every component created from your OpenAPI specification.
-
-<CodeGroup>
-```python {6} from_openapi()
-from fastmcp import FastMCP
+You can add tags to **all** components by providing a `tags` parameter when creating your MCP server. These global tags will be applied to every component created from your OpenAPI specification.
 
+```python
 mcp = FastMCP.from_openapi(
     openapi_spec=spec,
     client=client,
     tags={"api-v2", "production", "external"}
 )
 ```
-```python {5} from_fastapi()
-from fastmcp import FastMCP
-
-mcp = FastMCP.from_fastapi(
-    app=app,
-    tags={"internal-api", "microservice"}
-)
-```
-</CodeGroup>
-
-
-### Names
-
-<VersionBadge version="2.5.0" />
-
-FastMCP automatically generates names for MCP components based on the OpenAPI specification. By default, it uses the `operationId` from your OpenAPI spec, up to the first double underscore (`__`).
-
-All component names are automatically:
-- **Slugified**: Spaces and special characters are converted to underscores or removed
-- **Truncated**: Limited to 56 characters maximum to ensure compatibility
-- **Unique**: If multiple components have the same name, a number is automatically appended to make them unique
-
-For more control over component names, you can provide an `mcp_names` dictionary that maps `operationId` values to your desired names. The `operationId` must be exactly as it appears in the OpenAPI spec. The provided name will always be slugified and truncated.
-
-```python {5-9}
-from fastmcp import FastMCP
-
-mcp = FastMCP.from_openapi(
-    ...
-    mcp_names={
-        "list_users__with_pagination": "user_list",
-        "create_user__admin_required": "create_user", 
-        "get_user_details__admin_required": "user_detail",
-    }
-)
-```
-
-Any `operationId` not found in `mcp_names` will use the default strategy (operationId up to the first `__`).
-
 
 ### Advanced Customization
+
 <VersionBadge version="2.5.0" />
 
 By default, FastMCP creates MCP components using a variety of metadata from the OpenAPI spec, such as incorporating the OpenAPI description into the MCP component description.
@@ -316,8 +328,7 @@ At times you may want to modify those MCP components in a variety of ways, such
 Your `mcp_component_fn` is expected to modify the component in-place, not to return a new component. The result of the function is ignored.
 </Tip>
 
-```python {27}
-from fastmcp import FastMCP
+```python
 from fastmcp.server.openapi import (
     HTTPRoute, 
     OpenAPITool, 
@@ -329,7 +340,6 @@ def customize_components(
     route: HTTPRoute, 
     component: OpenAPITool | OpenAPIResource | OpenAPIResourceTemplate,
 ) -> None:
-    
     # Add custom tags to all components
     component.tags.add("openapi")
     
@@ -342,10 +352,12 @@ def customize_components(
         component.tags.add("data")
 
 mcp = FastMCP.from_openapi(
-    ...,
+    openapi_spec=spec,
+    client=client,
     mcp_component_fn=customize_components,
 )
 ```
+
 ## Request Parameter Handling
 
 FastMCP intelligently handles different types of parameters in OpenAPI requests:
@@ -401,118 +413,4 @@ FastMCP handles array parameters according to OpenAPI specifications:
 
 ### Headers
 
-Header parameters are automatically converted to strings and included in the HTTP request.
-
-## Auth
-
-If your API requires authentication, configure it on the HTTP client before creating the MCP server:
-
-```python
-import httpx
-from fastmcp import FastMCP
-
-# Bearer token authentication
-api_client = httpx.AsyncClient(
-    base_url="https://api.example.com",
-    headers={"Authorization": "Bearer YOUR_TOKEN"}
-)
-
-# Create MCP server with authenticated client
-mcp = FastMCP.from_openapi(..., client=api_client)
-```
-## Timeouts
-
-Set a timeout for all API requests:
-
-```python
-mcp = FastMCP.from_openapi(
-    openapi_spec=spec, 
-    client=api_client,
-    timeout=30.0  # 30 second timeout for all requests
-)
-```
-
-
-## FastAPI Integration
-
-<VersionBadge version="2.0.0" />
-
-FastMCP can directly convert FastAPI applications into MCP servers by extracting their OpenAPI specifications:
-
-<Tip>
-FastMCP does *not* include FastAPI as a dependency; you must install it separately to use this integration.
-</Tip>
-
-```python
-from fastapi import FastAPI
-from fastmcp import FastMCP
-
-# Your FastAPI app
-app = FastAPI(title="My API", version="1.0.0")
-
-@app.get("/items", tags=["items"], operation_id="list_items")
-def list_items():
-    return [{"id": 1, "name": "Item 1"}, {"id": 2, "name": "Item 2"}]
-
-@app.get("/items/{item_id}", tags=["items", "detail"], operation_id="get_item")
-def get_item(item_id: int):
-    return {"id": item_id, "name": f"Item {item_id}"}
-
-@app.post("/items", tags=["items", "create"], operation_id="create_item")
-def create_item(name: str):
-    return {"id": 3, "name": name}
-
-# Convert FastAPI app to MCP server
-mcp = FastMCP.from_fastapi(app=app)
-
-if __name__ == "__main__":
-    mcp.run()  # Run as MCP server
-```
-
-Note that operation ids are optional, but are used to create component names. You can also provide custom names, just like with OpenAPI specs.
-
-<Warning>
-FastMCP servers are not FastAPI apps, even when created from one. To learn how to deploy them as an ASGI app, see the [ASGI Integration](/deployment/asgi) documentation.
-</Warning>
-
-
-
-### FastAPI Configuration
-
-All OpenAPI integration features work with FastAPI apps:
-
-```python
-from fastmcp.server.openapi import RouteMap, MCPType
-
-# Custom route mapping with FastAPI
-mcp = FastMCP.from_fastapi(
-    app=app,
-    name="My Custom Server",
-    timeout=5.0,
-    tags={"api-v1", "fastapi"},  # Global tags for all components
-    mcp_names={"operationId": "friendly_name"},  # Custom component names
-    route_maps=[
-        # Admin endpoints become tools with custom tags
-        RouteMap(
-            methods="*", 
-            pattern=r"^/admin/.*", 
-            mcp_type=MCPType.TOOL,
-            mcp_tags={"admin", "privileged"}
-        ),
-        # Internal endpoints are excluded
-        RouteMap(methods="*", pattern=r".*", mcp_type=MCPType.EXCLUDE, tags={"internal"}),
-    ],
-    route_map_fn=my_route_mapper,
-    mcp_component_fn=my_component_customizer,
-    mcp_names={
-        "get_user_details_users__user_id__get": "get_user_details",
-    }
-)
-```
-
-### FastAPI Benefits
-
-- **Zero code duplication**: Reuse existing FastAPI endpoints
-- **Schema inheritance**: Pydantic models and validation are preserved  
-- **ASGI transport**: Direct in-memory communication (no HTTP overhead)
-- **Full FastAPI features**: Dependencies, middleware, authentication all work
+Header parameters are automatically converted to strings and included in the HTTP request.

docs/{deployment/asgi.mdx → integrations/starlette.mdx}

@@ -1,27 +1,24 @@
 ---
-title: Integrating FastMCP in ASGI Applications
-sidebarTitle: ASGI Integration
-description: Integrate FastMCP servers into existing Starlette, FastAPI, or other ASGI applications
-icon: plug
+title: Starlette / ASGI 🤝 FastMCP
+sidebarTitle: Starlette / ASGI
+description: Integrate FastMCP servers into ASGI applications
+icon: server
 ---
 
 import { VersionBadge } from '/snippets/version-badge.mdx'
 
+<VersionBadge version="2.3.1" />
 
-While FastMCP provides standalone server capabilities, you can also integrate your FastMCP server into existing web applications. This approach is useful for:
+FastMCP servers can be integrated into existing ASGI applications, allowing you to add MCP functionality to your web applications. This is useful for:
 
 - Adding MCP functionality to an existing website or API
 - Mounting MCP servers under specific URL paths
 - Combining multiple services in a single application
 - Leveraging existing authentication and middleware
 
-Please note that all FastMCP servers have a `run()` method that can be used to start the server. This guide focuses on integration with broader ASGI frameworks.
-
-## ASGI Server
-
-FastMCP servers can be created as [Starlette](https://www.starlette.io/) ASGI apps for straightforward hosting or integration into existing applications.
+## Basic Usage
 
-The first step is to obtain a Starlette application instance from your FastMCP server using the `http_app()` method:
+To integrate a FastMCP server into an ASGI application, use the `http_app()` method to obtain a Starlette application instance:
 
 <Tip>
 The `http_app()` method is new in FastMCP 2.3.2. In older versions, use `sse_app()` for SSE transport or `streamable_http_app()` for Streamable HTTP transport.
@@ -43,87 +40,74 @@ http_app = mcp.http_app()
 sse_app = mcp.http_app(transport="sse")
 ```
 
-Both approaches return a Starlette application that can be integrated with other ASGI-compatible web frameworks.
+The returned Starlette application can be integrated with other ASGI-compatible web frameworks. The MCP server's endpoint is mounted at `/mcp/` for Streamable HTTP transport and `/sse/` for SSE transport.
 
-The returned app stores the `FastMCP` instance on `app.state.fastmcp_server`, so you
-can access it from custom middleware or routes via `request.app.state.fastmcp_server`.
+### Configuration Options
 
-The MCP server's endpoint is mounted at the root path `/mcp/` for Streamable HTTP transport, and `/sse/` for SSE transport, though you can change these paths by passing a `path` argument to the `http_app()` method:
+You can customize the endpoint path and access the FastMCP server instance:
 
 ```python
-# For Streamable HTTP transport
+# Custom endpoint path
 http_app = mcp.http_app(path="/custom-mcp-path")
 
-# For SSE transport (deprecated)
-sse_app = mcp.http_app(path="/custom-sse-path", transport="sse")
+# Access the FastMCP server from middleware/routes
+# The server is available at: request.app.state.fastmcp_server
 ```
 
-### Running the Server
+### Adding Custom Routes
 
-To run the FastMCP server, you can use the `uvicorn` ASGI server:
+You can add custom web routes directly to your FastMCP server using the `@custom_route` decorator:
 
 ```python
 from fastmcp import FastMCP
-import uvicorn
+from starlette.requests import Request
+from starlette.responses import JSONResponse
 
 mcp = FastMCP("MyServer")
 
-http_app = mcp.http_app()
-
-if __name__ == "__main__":
-    uvicorn.run(http_app, host="0.0.0.0", port=8000)
-```
+@mcp.custom_route("/api/status", methods=["GET"])
+async def get_status(request: Request):
+    return JSONResponse({"server": "running"})
 
-Or, from the command line:
-
-```bash
-uvicorn path.to.your.app:http_app --host 0.0.0.0 --port 8000
+http_app = mcp.http_app()
 ```
 
-### Custom Middleware
-
-<VersionBadge version="2.3.2" />
+#### Health Check Endpoints
 
-You can add custom Starlette middleware to your FastMCP ASGI apps by passing a list of middleware instances to the app creation methods:
+Health checks are commonly needed for monitoring and load balancing:
 
 ```python
 from fastmcp import FastMCP
-from starlette.middleware import Middleware
-from starlette.middleware.cors import CORSMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse
 
-# Create your FastMCP server
 mcp = FastMCP("MyServer")
 
-# Define custom middleware
-custom_middleware = [
-    Middleware(
-        CORSMiddleware,
-        allow_origins=["https://example.com", "https://app.example.com"],
-        allow_credentials=True,
-        allow_methods=["GET", "POST", "OPTIONS"],
-        allow_headers=["Content-Type", "Authorization"],
-    ),
-]
+@mcp.custom_route("/health", methods=["GET"])
+async def health_check(request: Request):
+    return JSONResponse({"status": "healthy"})
 
-# Create ASGI app with custom middleware
-http_app = mcp.http_app(middleware=custom_middleware)
+http_app = mcp.http_app()
 ```
 
+The health endpoint will be available at `/health` alongside your MCP endpoint at `/mcp/`.
 
 ## Starlette Integration
 
-<VersionBadge version="2.3.1" />
-
-You can mount your FastMCP server in another Starlette application:
+Mount your FastMCP server in another Starlette application:
 
 ```python
 from fastmcp import FastMCP
 from starlette.applications import Starlette
 from starlette.routing import Mount
 
-# Create your FastMCP server as well as any tools, resources, etc.
+# Create your FastMCP server
 mcp = FastMCP("MyServer")
 
+@mcp.tool
+def analyze(data: str) -> dict:
+    return {"result": f"Analyzed: {data}"}
+
 # Create the ASGI app
 mcp_app = mcp.http_app(path='/mcp')
 
@@ -145,7 +129,6 @@ For Streamable HTTP transport, you **must** pass the lifespan context from the F
 
 ### Nested Mounts
 
-
 You can create complex routing structures by nesting mounts:
 
 ```python
@@ -153,7 +136,7 @@ from fastmcp import FastMCP
 from starlette.applications import Starlette
 from starlette.routing import Mount
 
-# Create your FastMCP server as well as any tools, resources, etc.
+# Create your FastMCP server
 mcp = FastMCP("MyServer")
 
 # Create the ASGI app
@@ -167,54 +150,64 @@ app = Starlette(
 )
 ```
 
-In this setup, the MCP server is accessible at the `/outer/inner/mcp/` path of the resulting Starlette app.
+In this setup, the MCP server is accessible at the `/outer/inner/mcp/` path.
 
-<Warning>
-For Streamable HTTP transport, you **must** pass the lifespan context from the FastMCP app to the *outer* Starlette app, as nested lifespans are not recognized. Otherwise, the FastMCP server's session manager will not be properly initialized.
-</Warning>
-## FastAPI Integration
+## Custom Middleware
 
-<VersionBadge version="2.3.1" />
+<VersionBadge version="2.3.2" />
 
-FastAPI is built on Starlette, so you can mount your FastMCP server in a similar way:
+Add custom Starlette middleware to your FastMCP ASGI apps by passing a list of middleware instances:
 
 ```python
 from fastmcp import FastMCP
-from fastapi import FastAPI
-from starlette.routing import Mount
+from starlette.middleware import Middleware
+from starlette.middleware.cors import CORSMiddleware
 
-# Create your FastMCP server as well as any tools, resources, etc.
+# Create your FastMCP server
 mcp = FastMCP("MyServer")
 
-# Create the ASGI app
-mcp_app = mcp.http_app(path='/mcp')
+# Define custom middleware
+custom_middleware = [
+    Middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+]
 
-# Create a FastAPI app and mount the MCP server
-app = FastAPI(lifespan=mcp_app.lifespan)
-app.mount("/mcp-server", mcp_app)
+# Create ASGI app with middleware
+http_app = mcp.http_app(custom_middleware=custom_middleware)
 ```
 
-The MCP endpoint will be available at `/mcp-server/mcp/` of the resulting FastAPI app.
+## Running the Server
 
-<Warning>
-For Streamable HTTP transport, you **must** pass the lifespan context from the FastMCP app to the resulting FastAPI app, as nested lifespans are not recognized. Otherwise, the FastMCP server's session manager will not be properly initialized.
-</Warning>
+To run your ASGI application, use an ASGI server like `uvicorn`:
 
+```python
+import uvicorn
 
-## Custom Routes
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+```
 
-In addition to adding your FastMCP server to an existing ASGI app, you can also add custom web routes to your FastMCP server, which will be exposed alongside the MCP endpoint. To do so, use the `@custom_route` decorator. Note that this is less flexible than using a full ASGI framework, but can be useful for adding simple endpoints like health checks to your standalone server.
+Or from the command line:
 
-```python
-from fastmcp import FastMCP
-from starlette.requests import Request
-from starlette.responses import PlainTextResponse
+```bash
+uvicorn path.to.your.app:app --host 0.0.0.0 --port 8000
+```
 
-mcp = FastMCP("MyServer")
+## Framework-Specific Integration
 
-@mcp.custom_route("/health", methods=["GET"])
-async def health_check(request: Request) -> PlainTextResponse:
-    return PlainTextResponse("OK")
-```
+### FastAPI
+
+For FastAPI-specific integration patterns including both mounting MCP servers into FastAPI apps and generating MCP servers from FastAPI apps, see the [FastAPI Integration guide](/integrations/fastapi).
+
+### Other ASGI Frameworks
+
+The patterns shown here work with any ASGI-compatible framework. The key requirements are:
+
+1. Mount the FastMCP ASGI app at your desired path
+2. Pass the lifespan context to your root application
+3. Configure any necessary middleware or authentication
 
-These routes will be included in the FastMCP app when mounted in your web application.

docs/servers/server.mdx

@@ -232,6 +232,28 @@ proxy = FastMCP.as_proxy(backend, name="ProxyServer")
 # Now use the proxy like any FastMCP server
 ```
 
+## OpenAPI Integration
+
+<VersionBadge version="2.0.0" />
+
+FastMCP can automatically generate servers from OpenAPI specifications or existing FastAPI applications using `FastMCP.from_openapi()` and `FastMCP.from_fastapi()`. This allows you to instantly convert existing APIs into MCP servers without manual tool creation.
+
+See the [FastAPI Integration](/integrations/fastapi) and [OpenAPI Integration](/integrations/openapi) guides for detailed examples and configuration options.
+
+```python
+import httpx
+from fastmcp import FastMCP
+
+# From OpenAPI spec
+spec = httpx.get("https://api.example.com/openapi.json").json()
+mcp = FastMCP.from_openapi(openapi_spec=spec, client=httpx.AsyncClient())
+
+# From FastAPI app
+from fastapi import FastAPI
+app = FastAPI()
+mcp = FastMCP.from_fastapi(app=app)
+```
+
 ## Server Configuration
 
 Servers can be configured using a combination of initialization arguments, global settings, and transport-specific settings.
@@ -322,12 +344,12 @@ await mcp.run_async(
 )
 ```
 
-### Environment Variables
+### Setting Global Configuration
 
-Settings can be configured via environment variables:
+Global FastMCP settings can be configured via environment variables (prefixed with `FASTMCP_`):
 
 ```bash
-# Global settings
+# Configure global FastMCP behavior
 export FASTMCP_LOG_LEVEL=DEBUG
 export FASTMCP_MASK_ERROR_DETAILS=True
 export FASTMCP_RESOURCE_PREFIX_FORMAT=protocol