For agents
The A in GRANDstack stands for Agent: the GraphQL API that serves the web app is meant to serve coding agents and agentic apps too. This page is the short version for an agent, or for a person directing one.
What to read
| Fetch | For |
|---|---|
| /llms.txt | An index of the docs, with one-line descriptions and absolute links |
| /llms-full.txt | All the documentation in one text file |
| Agent guide | The mental model, where to change what, a verification checklist, gotchas |
AGENTS.md in each repository | How to run, test and change that repository (grandstack, server, web, auth, agents, federation) |
| Schema reference | Every type and field with its description |
Using the API
Two ways, both documented and tested in grandstack-agents:
- Directly. Send GraphQL to
http://localhost:4000/graphql. Direct GraphQL shows the loop an agent follows: introspect, build a query, read the error, correct it. The agent loop is a runnable example behind a small model adapter. - Through MCP. A small server with four generic tools (
get_schema,describe_type,run_query,run_mutation) over stdio or HTTP. It reads the schema by introspection, so it works with other GraphQL servers too.
claude mcp add --transport http grandstack http://localhost:4100/mcp
Be careful with writes
- MCP is read-only by default.
run_mutationdoes nothing until the server starts withALLOW_MUTATIONS=true(in the compose setup, setAGENTS_ALLOW_MUTATIONS=true; compose passes it on under that name). That flag guards the MCP path only; the server behind it is open. See guardrails. - Real control is auth. Adding auth shows the same tools using a token against the
grandstack-authgateway, so an agent gets exactly the permissions of its role.
Design the schema for the agent
Type definitions straight from introspection work, but a schema tailored to the questions you want answered works better: descriptions, stored answers to common questions, names for the task, and @cypher where the generated Cypher is slow or does not fit. Newer models do better too, and the schema is the part you control. See designing the type definitions for agents.
Federation
With the federation setup, the agent sees one combined API; describe cross-source fields well. How federation works.