# GRANDstack > GraphQL and Neo4j, for developers and agents. A Neo4j graph, a GraphQL API generated from one schema file (@neo4j/graphql v7 on GraphQL Yoga), a typed React app, and an MCP server so agents can use the same API. Small repositories you can clone and run in Docker. Opt-in layers: auth (Keycloak and a gateway), agents (MCP), federation (a Wikipedia subgraph). The default stack has no authentication: run it locally and do not expose it. Licensed Apache-2.0. Source: https://github.com/grand-stack. Everything below is a copy of the documentation in those repositories; the full text of all of it is at https://www.grandstack.ai/llms-full.txt. ## Start here - [Quickstart](https://www.grandstack.ai/quickstart/): clone the repos, start the stack, query the API, connect an agent - [For agents](https://www.grandstack.ai/agents/): what to read, how to connect, what to be careful about - [Examples](https://www.grandstack.ai/examples/): runnable queries, mutations, MCP and federation examples ## grandstack The umbrella: compose files for every setup, the overview, architecture, build-your-own-app tutorial and agent guide. - [Overview](https://www.grandstack.ai/docs/grandstack/): GraphQL on Neo4j for developers and agents. A Neo4j database, a GraphQL server generated from a schema file, and a typed React app, run together with Docker Compose.... - [Architecture](https://www.grandstack.ai/docs/grandstack/architecture/): GRANDstack is a way to build apps on a Neo4j graph with GraphQL: a Neo4j database, a GraphQL server generated from a schema file, and a React client with typed... - [Build your own app](https://www.grandstack.ai/docs/grandstack/build-your-own-app/): This guide takes the GRANDstack repos and turns them into an app for your own data. The worked example is a small library: Books, Authors and Genres, with a... - [Configuration](https://www.grandstack.ai/docs/grandstack/configuration/): How the stack is wired and every setting that matters, with pointers to the repo that owns each one. - [Agent guide](https://www.grandstack.ai/docs/grandstack/agents/): For coding agents (Claude Code or any other) and the people directing them. It says what the system is, where to change what, how to verify, and what goes wrong. It... - [AGENTS.md](https://www.grandstack.ai/docs/grandstack/agents-md/): Compose stack plus the overview docs for GRANDstack (GraphQL on Neo4j: grandstack-server, grandstack-web). Read docs/agents.md first; it covers the mental model,... - [Versioning and releases](https://www.grandstack.ai/docs/grandstack/versioning-and-releases/): Every repository uses semantic versions as git tags (v0.6.0). A change that adds behaviour bumps the minor version while we are below 1.0; a fix or a docs-only change... - [Releasing, CI and the website](https://www.grandstack.ai/docs/grandstack/releasing/): How code is checked, how a release is made, and how every release reaches grandstack.ai. All of it runs as GitHub Actions in the grand-stack organisation. The shared... ## grandstack-server The GraphQL server: Neo4j and a schema file in, a GraphQL API out. Seeding, mutations, federation switch. - [Overview](https://www.grandstack.ai/docs/grandstack-server/): A Docker image that serves GraphQL over Neo4j. You give it a Neo4j connection (environment variables), a GraphQL schema (a file) and optionally some seed data; it... - [How grandstack-server works](https://www.grandstack.ai/docs/grandstack-server/how-it-works/): grandstack-server is a small Node service that exposes a GraphQL API over a Neo4j database. You describe your data in a GraphQL schema file; @neo4j/graphql turns it... - [Schema guide](https://www.grandstack.ai/docs/grandstack-server/schema-guide/): The schema file, schema/schema.graphql, is the whole API. This page explains the pieces @neo4j/graphql v7 understands and the rules that tripped us up. For a list of... - [Mutations](https://www.grandstack.ai/docs/grandstack-server/mutations/): Scalar fields use set operators, not plain values: - [Seeding](https://www.grandstack.ai/docs/grandstack-server/seeding/): On startup the server can load sample data from a Cypher file. This page describes the file format, when the server loads it, and how to replace it with your own data. - [Recipes](https://www.grandstack.ai/docs/grandstack-server/recipes/): Step-by-step changes for the server. Each ends with how to check it worked. Run commands from the repo root of grandstack-server. These are written so a developer or... - [Configuration](https://www.grandstack.ai/docs/grandstack-server/configuration/): The server is configured only through environment variables (read once at startup by src/config.ts) and two mounted files: the schema and the seed. - [Schema reference](https://www.grandstack.ai/docs/grandstack-server/schema-reference/): Every type and field below comes from schema/schema.graphql. @neo4j/graphql also generates queries, mutations, filters and sort inputs for each @node type (for... - [Troubleshooting](https://www.grandstack.ai/docs/grandstack-server/troubleshooting/): Errors we actually hit while building this, with causes and fixes. - [AGENTS.md](https://www.grandstack.ai/docs/grandstack-server/agents-md/): GraphQL API over Neo4j using @neo4j/graphql v7 and GraphQL Yoga. Configured by environment variables and a schema file. Read docs/how-it-works.md first, then... ## grandstack-web The React app: faceted search, compare, graph views, people pages and full create, edit and delete, with typed operations. - [Overview](https://www.grandstack.ai/docs/grandstack-web/): A movie and people search app for grandstack-server (GraphQL over Neo4j), built to show what a GraphQL-on-Neo4j front end can look like, and to be adapted to your own... - [Architecture of grandstack-web](https://www.grandstack.ai/docs/grandstack-web/architecture/): grandstack-web is a single-page React app that talks to grandstack-server over GraphQL. It is a movie and people search, filter, compare and edit app, written to show... - [How the features work](https://www.grandstack.ai/docs/grandstack-web/features/): Each section says what the user sees, where the code is, and the one non-obvious thing. Facts here were checked against the running app. - [Customising the web app](https://www.grandstack.ai/docs/grandstack-web/customising/): What to change to make this look and behave like your own app, and what depends on the Movies model. - [Recipes](https://www.grandstack.ai/docs/grandstack-web/recipes/): Step-by-step changes to the web app. Run commands from the repo root of grandstack-web with the stack running (docker compose up in the grandstack repo) so codegen... - [Testing](https://www.grandstack.ai/docs/grandstack-web/testing/): Four layers, from fastest to most realistic. - [AGENTS.md](https://www.grandstack.ai/docs/grandstack-web/agents-md/): React + Vite client for grandstack-server: faceted movie and people search, compare, graph views, and create/edit/delete. urql with typed operations from GraphQL Code... ## grandstack-auth Opt-in auth: a gateway that validates tokens and enforces permissions, row-level rules, a Keycloak dev realm and a demo client. - [Overview](https://www.grandstack.ai/docs/grandstack-auth/): Authentication and authorization for GRANDstack: a gateway that validates Keycloak tokens and enforces permissions per mutation, row-level rules for the GraphQL... - [How authentication and authorization work](https://www.grandstack.ai/docs/grandstack-auth/how-it-works/): This repository adds login and access rules to GRANDstack without changing grandstack-web. It is opt-in: the default stack stays open, and compose.auth.yaml in the... - [Role and permission model](https://www.grandstack.ai/docs/grandstack-auth/role-and-scope-model/): The gateway answers "may this token call this mutation at all?" using permissions. The server answers "may this token change this row?" using roles and the token's sub. - [The Keycloak development realm](https://www.grandstack.ai/docs/grandstack-auth/keycloak/): Keycloak admin console: http://localhost:8081, user admin, password admin. - [The demo client](https://www.grandstack.ai/docs/grandstack-auth/client/): These are baked into the static files, so changing them means rebuilding the image. src/auth/config.ts throws a clear error at startup if the authority or client id... - [Using a different OpenID Connect provider](https://www.grandstack.ai/docs/grandstack-auth/swapping-providers/): Nothing in the gateway, server or demo client is specific to Keycloak: they use standard OpenID Connect and JWTs. To use another provider (Auth0, Okta, Entra ID,... - [Auth0 (written, not tested)](https://www.grandstack.ai/docs/grandstack-auth/auth0/): You need an Auth0 developer tenant. Everything below is configuration; no code changes. - [Recipes](https://www.grandstack.ai/docs/grandstack-auth/recipes/): Step-by-step changes. Commands run from the root of grandstack-auth with the auth stack up (docker compose -f compose.yaml -f compose.auth.yaml up --build in the... - [Exercise: add authentication to grandstack-web](https://www.grandstack.ai/docs/grandstack-auth/exercise-add-auth-to-grandstack-web/): A follow-up task for a developer, or a coding agent, to do in their own copy of grandstack-web. grandstack-web itself stays an open, unauthenticated app on purpose;... - [Testing](https://www.grandstack.ai/docs/grandstack-auth/testing/): Four layers. The first two need nothing running; the last two need the auth stack (docker compose -f compose.yaml -f compose.auth.yaml up --build in the grandstack repo). - [Troubleshooting](https://www.grandstack.ai/docs/grandstack-auth/troubleshooting/): Problems we actually hit, with causes and fixes. - [AGENTS.md](https://www.grandstack.ai/docs/grandstack-auth/agents-md/): Auth for GRANDstack: Hive Gateway (gateway/), Keycloak dev realm (keycloak/), row-level schema rules (schema/auth.graphql), demo client (client/), smoke and browser... ## grandstack-agents How agents work with GraphQL: a small MCP server that runs GraphQL statements, a direct agent loop, auth example code and guardrails. - [Overview](https://www.grandstack.ai/docs/grandstack-agents/): How agents work with GraphQL. Two ways, both against the open grandstack-server: - [How it works](https://www.grandstack.ai/docs/grandstack-agents/how-it-works/): Errors from the GraphQL server are returned the same way, with any partial data, so an agent can fix its statement. - [Designing the type definitions for agents](https://www.grandstack.ai/docs/grandstack-agents/schema-design-for-agents/): An agent works with the schema it is given. The tools in this repo read it by introspection, so what the agent sees is whatever the type definitions say. A schema... - [The MCP server](https://www.grandstack.ai/docs/grandstack-agents/mcp-server/): A small Model Context Protocol server that accepts GraphQL statements and runs them against any GraphQL endpoint. It knows nothing about movies: the schema is read by... - [Direct GraphQL](https://www.grandstack.ai/docs/grandstack-agents/direct-graphql/): An agent does not need MCP to use GraphQL. It needs the endpoint, a way to learn the schema, and the discipline to fix its own errors. This page shows the loop with... - [The agent loop](https://www.grandstack.ai/docs/grandstack-agents/agent-loop/): To use another model provider, write an adapter that turns messages and tools into that provider's request and its reply back into text and tooluse blocks. Nothing... - [Adding auth](https://www.grandstack.ai/docs/grandstack-agents/adding-auth/): This repo needs no login: it talks to the open grandstack-server. When you put grandstack-auth in front of the server, the same tools work with one change: they send... - [Guardrails](https://www.grandstack.ai/docs/grandstack-agents/guardrails/): What the tools check before anything reaches the GraphQL server, and what they do not. - [Recipes](https://www.grandstack.ai/docs/grandstack-agents/recipes/): Both recipes were run against the live stack before being written here. - [Testing](https://www.grandstack.ai/docs/grandstack-agents/testing/): They run against test/stub-server.ts, a real graphql-js server over HTTP, so they need no Docker. - [Troubleshooting](https://www.grandstack.ai/docs/grandstack-agents/troubleshooting/): Troubleshooting - [AGENTS.md](https://www.grandstack.ai/docs/grandstack-agents/agents-md/): How agents work with GraphQL: an MCP server that runs GraphQL statements, and a direct agent-loop example. It uses the open grandstack-server (no auth);... ## grandstack-federation Federation: the server as a subgraph, a Wikipedia subgraph, and a gateway that serves one combined API. - [Overview](https://www.grandstack.ai/docs/grandstack-federation/): GraphQL federation for GRANDstack. The Neo4j server becomes a subgraph, a small Wikipedia subgraph is added, and a gateway composes them, so one query returns movie... - [How it works](https://www.grandstack.ai/docs/grandstack-federation/how-it-works/): A page that does not exist is just null. If Wikipedia is slow, rate limiting or unreachable, the Wikipedia subgraph answers with a GraphQL error (code... - [The subgraphs](https://www.grandstack.ai/docs/grandstack-federation/subgraphs/): extend type Movie @key(fields: "wikipediaTitle") { wikipediaTitle: String wikidataId: String } - [What we tried](https://www.grandstack.ai/docs/grandstack-federation/prototype-findings/): The project's brief listed two open questions for this phase. These are the findings from the prototype, run on 2026-10-22, in the order we hit them. - [Linking films and people to Wikipedia](https://www.grandstack.ai/docs/grandstack-federation/linking/): Federation needs a key: for each film and person, the title of its English Wikipedia page. Looking titles up at request time is unreliable (we saw Heat, Alien,... - [Composition and the gateway](https://www.grandstack.ai/docs/grandstack-federation/composition/): With the stack up (the subgraphs must be reachable): - [Recipes](https://www.grandstack.ai/docs/grandstack-federation/recipes/): returns "American singer and songwriter (born 1958)". For a film use updateMovies(where: { title: { eq: "..." } }, ...). Use the page title exactly as Wikipedia shows... - [Exercise: show Wikipedia in grandstack-web](https://www.grandstack.ai/docs/grandstack-federation/exercise-show-wikipedia-in-grandstack-web/): A follow-up task for a developer or a coding agent. grandstack-web is deliberately unchanged by this repo; with the federation stack running it already talks to the... - [Testing](https://www.grandstack.ai/docs/grandstack-federation/testing/): Against the running stack: a film returns Neo4j fields and its Wikipedia summary in one query, with the Wikidata id; a person likewise; an unlinked person (Madonna)... - [Troubleshooting](https://www.grandstack.ai/docs/grandstack-federation/troubleshooting/): Troubleshooting - [AGENTS.md](https://www.grandstack.ai/docs/grandstack-federation/agents-md/): Federation for GRANDstack: the Neo4j subgraph (grandstack-server with FEDERATION=true), a Wikipedia subgraph (wikipedia/), and a Hive Gateway serving the composed...