fastapi-gql-mcp — a context-efficient, agent-friendly MCP server for your FastAPI app
Hey folks,
Credit where due: tadata-org/fastapi_mcp inspired this one. For most API scenarios it's honestly the right call — least setup, least friction. This post is about a tradeoff that started biting me once my API grew past a certain size.
What I kept running into: one tool per endpoint means the tool catalog grows with your API. A 100-route app is ~10,950 tokens of tool definitions before anyone says a word. That's the context tax this sub talks about a lot — but there's a second half that gets a lot less airtime: what the tools return.
My list endpoints return 1-2 MB. One call and the session is toast. I'm not the only one — a Supabase MCP user measured a single ~10k-token response eating 40% of their window, and there's a whole thread on "your MCP tools are wasting 40% of Claude's context". The standard fix so far is truncation — a ~25k cap, which a bunch of MCP servers now build in. Truncation works, but the server decides what gets dropped. The agent never gets to say "I only need id and name" — with one tool per endpoint, there's no place to say it.
So I built the other shape: derive a GraphQL schema from the FastAPI app itself (no decorators, no model changes), and expose a tiny constant MCP toolset over it — get_schema + graphql_query, or a 4-layer drill-down (list_domains → list_queries → get_query_schema → graphql_query) for bigger apps. GraphQL is the contract; the MCP surface stays at 2-6 tools no matter how big the API gets.
What that buys you on both fronts (numbers from the benchmark app in the repo):
- Tool catalog: ~2,480 tokens simple / ~1,480 progressive vs ~10,950 — and it stops growing
- The agent picks its fields: { id name } on the benchmark app is 610 B where the full payload is 2,875 B. On a 1-2 MB endpoint, three fields is the difference between a dead session and a three-line answer
- The schema shows every field up front, so "what subset do I actually need" is a decision the model can make before it spends anything
- When projection isn't enough there's still a hard-cap recipe (fastmcp ships a response-limiting middleware — config in the README), plus guardrails on by default: depth limit, bounded fan-out, per-call timeout, and a document cache for repeat queries (1.52ms → 0.69ms here)
- Auth stays boring and real: queries go through the actual ASGI app in-process, so Depends, middleware and JWT behave exactly like over HTTP, with per-caller credential passthrough
Every number above comes from the benchmark app in the repo, with methodology and a reproduce script. Nothing picked to flatter.
pip install fastapi-gql-mcp
KLR-Pattern/fastapi-gql-mcp
full comparison: comparison/README.md
Ask me anything.
Any suggestions are welcome.
1 point · 3 comments
Mentions
fastapi-gql-mcp — a context-efficient, agent-friendly MCP server for your FastAPI app Hey folks, Credit where due: tadata-org/fastapi_mcp inspired this one. For most API scenarios it's honestly the right call — least setup, least friction. This post is about a tradeoff that started biting me once my API grew past a certain size. What I kept running into: one tool per endpoint means the tool catalog grows with your API. A 100-route app is ~10,950 tokens of tool definitions before anyone says a word. That's the context tax this sub talks about a lot — but there's a second half that gets a lot less airtime: what the tools return. My list endpoints return 1-2 MB. One call and the session is toast. I'm not the only one — a Supabase MCP user measured a single ~10k-token response eating 40% of their window, and there's a whole thread on "your MCP tools are wasting 40% of Claude's context". The standard fix so far is truncation — a ~25k cap, which a bunch of MCP servers now build in. Truncation works, but the server decides what gets dropped. The agent never gets to say "I only need id and name" — with one tool per endpoint, there's no place to say it. So I built the other shape: derive a GraphQL schema from the FastAPI app itself (no decorators, no model changes), and expose a tiny constant MCP toolset over it — get_schema + graphql_query, or a 4-layer drill-down (list_domains → list_queries → get_query_schema → graphql_query) for bigger apps. GraphQL is the contract; the MCP surface stays at 2-6 tools no matter how big the API gets. What that buys you on both fronts (numbers from the benchmark app in the repo): - Tool catalog: ~2,480 tokens simple / ~1,480 progressive vs ~10,950 — and it stops growing - The agent picks its fields: { id name } on the benchmark app is 610 B where the full payload is 2,875 B. On a 1-2 MB endpoint, three fields is the difference between a dead session and a three-line answer - The schema shows every field up front, so "what subset do I actually need" is a decision the model can make before it spends anything - When projection isn't enough there's still a hard-cap recipe (fastmcp ships a response-limiting middleware — config in the README), plus guardrails on by default: depth limit, bounded fan-out, per-call timeout, and a document cache for repeat queries (1.52ms → 0.69ms here) - Auth stays boring and real: queries go through the actual ASGI app in-process, so Depends, middleware and JWT behave exactly like over HTTP, with per-caller credential passthrough Every number above comes from the benchmark app in the repo, with methodology and a reproduce script. Nothing picked to flatter. pip install fastapi-gql-mcp KLR-Pattern/fastapi-gql-mcp full comparison: comparison/README.md Ask me anything. Any suggestions are welcome.