KLR-Pattern/fastapi-mcp-neo

Transform your FastAPI routes to agent-friendly, context-efficient MCP

Summary

fastapi-mcp-neo is a Python library that turns an existing FastAPI app into a Model Context Protocol (MCP) server by deriving a GraphQL schema from its routes. Instead of exposing one MCP tool per endpoint, it exposes a constant set of 2-6 tools (mainly graphql_query) so agents can compose several routes into a single call with field-level selection. No decorators or model changes are required on the FastAPI side.

What it is useful for

This library is useful when a team already runs a FastAPI service and wants to expose it to MCP clients such as Claude Code or Cursor. Where one-tool-per-endpoint bridges grow their tool catalog linearly with route count, fastapi-mcp-neo keeps the catalog roughly constant: the README reports ~15,400 tokens for a 100-route OpenAPI bridge versus ~2,480 tokens in simple mode or ~1,510 with progressive disclosure.

Engineers can also use it to let agents combine multiple routes in one query, fetch only the fields they need, and pass per-caller credentials (via passthrough_headers) so existing Depends and middleware authorize each call as the underlying user. Routes tagged ["shop:catalog"] become accessible at shop { catalog { … } }, with endpoint function names serving as field names — so an async def list_products route is invoked as list_products(...) from the agent.

How engineers can use it

Per the README, the project requires Python 3.10 or newer. Installation is uv add 'fastapi-mcp-neo[mcp]'; the [mcp] extra pulls in fastmcp for the server.

The minimal setup, copied from the README, is:

from fastapi import FastAPI
from fastapi_mcp_neo import FastAPIMCP

app = FastAPI()
# ... existing routes ...
mcp = FastAPIMCP(app, name="my-app")
mcp.run()  # streamable HTTP MCP server

Routes can be scoped with include/exclude path globs and include_tags/exclude_tags, and allow_mutation=True must be set explicitly to expose writes. mount_to(app, "/mcp") serves the MCP endpoint on the app's own port. Above progressive_threshold routes (default 25), the toolset switches to a 5-step discovery walk.

Documented limitations to be aware of: Form()/File() routes, required header/cookie parameters, and raw Response/bytes returns are skipped (logged with reasons). Untyped responses, unions, and unmappable model fields fall back to a raw JSON field rather than being field-selectable. Recursive data unrolls up to sys.getrecursionlimit() // 16 levels (~62 under defaults). The library is FastAPI-only and serves streamable HTTP transport. readiness() exposes skips and degradations so they can be asserted in CI.