Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

docs: show tests for MCP mounted in FastAPI (#5471)

Andrei Vinceda4bd5361f07
diff --git a/docs/integrations/fastapi.mdx b/docs/integrations/fastapi.mdx
index 83aa924f8..45172e91f 100644
--- a/docs/integrations/fastapi.mdx
+++ b/docs/integrations/fastapi.mdx
@@ -334,6 +334,58 @@ app.mount("/analytics", mcp_app)
# Now: API at /products/*, MCP at /analytics/mcp/
```
+### Testing a Mounted Server
+
+To test the mounted HTTP endpoint, connect the FastMCP client through `StreamingASGITransport`. This sends requests through your FastAPI application in the same process, including its middleware, routing, and authentication, without starting a separate HTTP server. Use `run_asgi_lifespan` to run the parent application's startup and shutdown.
+
+The following standalone test uses a test-only bearer token. Configure `pytest-asyncio` in `auto` mode as described in the [testing guide](/servers/testing):
+
+```python
+import httpx2
+from fastapi import FastAPI
+
+from fastmcp import Client, FastMCP
+from fastmcp.client.transports import StreamableHttpTransport
+from fastmcp.server.auth.providers.jwt import StaticTokenVerifier
+from fastmcp.utilities.asgi_transport import (
+ StreamingASGITransport,
+ run_asgi_lifespan,
+)
+
+
+async def test_mounted_mcp():
+ auth = StaticTokenVerifier(
+ tokens={"test-token": {"client_id": "test-client", "scopes": []}}
+ )
+ mcp = FastMCP("Test Tools", auth=auth)
+
+ @mcp.tool
+ def add(a: int, b: int) -> int:
+ return a + b
+
+ mcp_app = mcp.http_app(path="/mcp")
+ app = FastAPI(lifespan=mcp_app.lifespan)
+ app.mount("/analytics", mcp_app)
+
+ def http_client_factory(**kwargs):
+ return httpx2.AsyncClient(
+ transport=StreamingASGITransport(app),
+ **kwargs,
+ )
+
+ transport = StreamableHttpTransport(
+ url="http://testserver/analytics/mcp",
+ auth="test-token",
+ httpx_client_factory=http_client_factory,
+ )
+ async with run_asgi_lifespan(app):
+ async with Client(transport) as client:
+ result = await client.call_tool("add", {"a": 1, "b": 2})
+ assert result.data == 3
+```
+
+The client URL includes both the mount prefix (`/analytics`) and the MCP application's path (`/mcp`). `StreamingASGITransport` streams responses as they arrive; the standard `httpx2.ASGITransport` buffers responses and cannot complete a long-lived SSE response. Passing `**kwargs` through the HTTP client factory preserves the transport's headers, authentication, and timeout settings.
+
## Offering an LLM-Friendly API
A common pattern is to generate an MCP server from your FastAPI app and serve both interfaces from the same application. This provides an LLM-optimized interface alongside your regular API:
@@ -442,4 +494,4 @@ app.mount("/mcp", mcp_app) # MCP endpoint at /mcp
2. **Design purpose-built MCP tools** - Better than auto-converting complex APIs
3. **Keep tool parameters simple** - LLMs perform better with focused interfaces
-For more details on configuration options, see the [OpenAPI Integration guide](/integrations/openapi).
\ No newline at end of file
+For more details on configuration options, see the [OpenAPI Integration guide](/integrations/openapi).