Project case study
graphql-agent-toolkit
graphql-agent-toolkit introspects a GraphQL endpoint, builds typed operations, and exposes them to agents through MCP or framework-native adapters.
Problem
A GraphQL schema contains the information needed to call an API, but an agent still needs discoverable tool definitions, valid operations and variables, pagination handling, and responses sized for its context window.
Building that bridge separately for every endpoint repeats the same schema, execution, and framework integration work.
Why existing approaches fall short
Giving an agent a raw schema leaves it to search a potentially broad type graph and construct correct nested operations on every call.
Handwritten wrappers duplicate endpoint-specific plumbing, while returning full paginated responses can consume context that should remain available for the task.
Approach and architecture
Derive tools from the schema
The toolkit fetches and parses introspection, generates operations with variable definitions and bounded selection depth, and creates one MCP tool for each query and mutation plus an explore_schema tool.
Keep discovery and results agent-sized
A TF-IDF schema navigator finds relevant types and fields. Pagination helpers recognize Relay and offset styles, while summarization limits arrays, depth, and string length before formatting results for an LLM.
Separate the core from frameworks
The same parsed schema and executor feed MCP, LangChain, CrewAI, and Vercel AI SDK adapters without requiring those frameworks in the core package. Deterministic mock generation supports local testing.
Proof
- Runnable endpoint workflow
- The public README documents npx commands that introspect an endpoint with init and serve the generated MCP surface with serve. Quick start.
- Schema-derived MCP surface
- Each query is exposed as query_<fieldName>, each mutation as mutate_<fieldName>, and explore_schema gives agents a way to browse types and fields. MCP server example.
- Documented integration surface
- The published API covers introspection, operation building, semantic navigation, Relay and offset pagination, response summarization, LangChain, CrewAI, Vercel AI SDK, and deterministic mocks. API reference.
Key tradeoffs
- Generated selection sets use a configurable depth rather than inferring the ideal business-specific shape for every task.
- Response summarization intentionally truncates data to protect the context window, so callers must choose limits that fit their task.
- The package requires Node.js 22 or newer and graphql 16 or newer. The public README does not publish performance or adoption benchmarks.
Lessons
- GraphQL introspection is most useful to an agent when it becomes a searchable, constrained tool surface instead of a schema dump.
- A framework-neutral core keeps transport and agent-framework choices from leaking into operation generation.
- Context management belongs near execution because even a valid API response can be too large to be useful to an agent.