Add docs for asgi integration

docs/deployment/asgi.mdx

@@ -0,0 +1,171 @@
+---
+title: Integrating FastMCP in ASGI Applications
+sidebarTitle: ASGI Integration
+description: Integrate FastMCP servers into existing Starlette, FastAPI, or other ASGI applications
+icon: plug
+---
+
+While FastMCP provides standalone server capabilities, you can also integrate your FastMCP server into existing web applications. This approach 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.
+
+The first step is to obtain a Starlette application instance from your FastMCP server using either the `streamable_http_app()` (preferred) or `sse_app()` (legacy) methods:
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("MyServer")
+
+@mcp.tool()
+def hello(name: str) -> str:
+    return f"Hello, {name}!"
+
+# Get a Starlette app instance for the preferred transport
+http_app = mcp.streamable_http_app()   # For Streamable HTTP transport
+sse_app = mcp.sse_app()                # For SSE transport
+```
+
+Both methods return a Starlette application that can be integrated with other ASGI-compatible web frameworks. 
+
+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 `streamable_http_app()` or `sse_app()` methods:
+
+```python
+http_app = mcp.streamable_http_app(path="/custom-mcp-path")
+sse_app = mcp.sse_app(path="/custom-sse-path")
+```
+
+### Running the Server
+
+To run the FastMCP server, you can use the `uvicorn` ASGI server:
+
+```python
+import uvicorn
+
+# (define the app here)
+
+if __name__ == "__main__":
+    uvicorn.run(http_app, host="0.0.0.0", port=8000)
+```
+
+Or, from the command line:
+
+```bash
+uvicorn path.to.your.app:http_app --host 0.0.0.0 --port 8000
+```
+
+
+
+## Starlette Integration
+
+You can mount your FastMCP server in another Starlette application using the `Mount` class.
+
+```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.
+mcp = FastMCP("MyServer")
+
+# Create the ASGI app
+mcp_app = mcp.streamable_http_app(path='/mcp')
+
+# Create a Starlette app and mount the MCP server
+app = Starlette(
+    routes=[
+        Mount("/mcp-server", app=mcp_app),
+        # Add other routes as needed
+    ],
+    lifespan=mcp_app.router.lifespan_context,
+)
+```
+
+The MCP endpoint will be available at `/mcp-server/mcp` of the resulting Starlette app.
+
+<Warning>
+For Streamable HTTP transport, you **must** pass the lifespan context from the FastMCP app to the resulting Starlette app, as nested lifespans are not recognized. Otherwise, the FastMCP server's session manager will not be properly initialized.
+</Warning>
+
+### Nested Mounts
+
+
+You can create complex routing structures by nesting mounts:
+
+```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.
+mcp = FastMCP("MyServer")
+
+# Create the ASGI app
+mcp_app = mcp.streamable_http_app(path='/mcp')
+
+# Create nested application structure
+inner_app = Starlette(routes=[Mount("/inner", app=mcp_app)])
+app = Starlette(
+    routes=[Mount("/outer", app=inner_app)],
+    lifespan=mcp_app.router.lifespan_context,
+)
+```
+
+In this setup, the MCP server is accessible at the `/outer/inner/mcp` path of the resulting Starlette app.
+
+<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
+
+FastAPI is built on Starlette, so you can mount your FastMCP server in a similar way:
+
+```python
+from fastmcp import FastMCP
+from fastapi import FastAPI
+from starlette.routing import Mount
+
+# Create your FastMCP server as well as any tools, resources, etc.
+mcp = FastMCP("MyServer")
+
+# Create the ASGI app
+mcp_app = mcp.streamable_http_app(path='/mcp')
+
+# Create a FastAPI app and mount the MCP server
+app = FastAPI(lifespan=mcp_app.router.lifespan_context)
+app.mount("/mcp-server", mcp_app)
+```
+
+The MCP endpoint will be available at `/mcp-server/mcp` of the resulting FastAPI app.
+
+<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>
+
+
+## Custom Routes
+
+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.
+
+```python
+from fastmcp import FastMCP
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+mcp = FastMCP("MyServer")
+
+@mcp.custom_route("/health", methods=["GET"])
+async def health_check(request: Request) -> JSONResponse:
+    return JSONResponse({"status": "healthy"})
+```
+
+These routes will be included in the FastMCP app when mounted in your web application. 

docs/deployment/running-server.mdx

@@ -189,4 +189,25 @@ if __name__ == "__main__":
 ```
 </CodeGroup>
 
-Your client only needs to know the host, port, and "main" path; the message path will be transmitted to it as part of the connection handshake.
+Your client only needs to know the host, port, and "main" path; the message path will be transmitted to it as part of the connection handshake.
+
+
+
+## Custom Routes
+
+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.
+
+```python
+from fastmcp import FastMCP
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+mcp = FastMCP("MyServer")
+
+@mcp.custom_route("/health", methods=["GET"])
+async def health_check(request: Request) -> JSONResponse:
+    return JSONResponse({"status": "healthy"})
+
+if __name__ == "__main__":
+    mcp.run()
+```

docs/docs.json

@@ -58,6 +58,7 @@
                 "group": "Deployment",
                 "pages": [
                     "deployment/running-server",
+                    "deployment/asgi",
                     "deployment/authentication"
                 ]
             },