Neo4j MCP Setup With Relate for Claude Code and Codex: Run an Embedded Graph, Check the Agent's Cypher, Then Go Read-Only on a Server

Neo4j MCP setup for Claude Code and Codex: serve a Relate graph read-only, check the agent's Cypher against a known answer, then move to read-only Neo4j.

Hero for a Neo4j MCP setup guide: Claude Code and Codex chips feed a relate serve --mcp stdio --read-only box exposing get_schema and read_cypher but no write_cypher, next to a dependency graph where orders-db is down and five upstream services are highlighted.Hero for a Neo4j MCP setup guide: Claude Code and Codex chips feed a relate serve --mcp stdio --read-only box exposing get_schema and read_cypher but no write_cypher, next to a dependency graph where orders-db is down and five upstream services are highlighted.
Two hosts, one read-only Relate process, two read tools: check which services fail when orders-db is down before trusting the agent's Cypher. Pattern from Relate's Connect over MCP guide and Neo4j MCP docs, November 2026.

If you have asked a coding agent to remember how your services depend on each other, you have probably seen it write that knowledge to a JSON file and lose the connections the next time it reads the file. A Neo4j MCP setup fixes the storage half of that problem. The agent gets a graph it can query in Cypher, through MCP tools it already knows how to call. The harder half is trust. An agent that writes Cypher can return a confident answer from a query that walked one hop when the question needed four.

This tutorial builds the whole loop on one machine, with no database server. You’ll install Relate, Neo4j’s embedded graph database, and seed a twelve-node service dependency graph we call task:graph-deps-01. You’ll serve it read-only over MCP and register it in both Claude Code and Codex. Then you’ll answer one question by hand, ask the agent the same question and compare the rows. Once the comparison passes, you’ll point the same agent at a Neo4j server behind Neo4j’s official MCP server, with the write tools switched off.

Everything here follows the vendors’ published documentation as of November 2026. Commands and outputs marked illustrative were not run for this article. They show what the documentation and the seed data predict. Where the documentation stops, the guide says so.

What Relate adds, and why the server comes later

Neo4j announced Relate on November 11, 2026. It is an open-source (Apache 2.0), in-memory, in-process embedded database written in Rust, and it ships with an MCP server, a CLI, and Bolt and HTTP Query API v2 endpoints. The launch blog post names the gap it targets: developers fall back to Python dicts or JSON files that keep facts but lose how they connect, and relate serve turns a database into tools for reading the schema and running queries. Neo4j’s launch post on X describes it as having no server installation step and no account setup.

Neo4j press release page titled New In-Memory Database Purpose-Built for AI Agents, dated November 11, 2026.
Neo4j's November 11, 2026 press release announcing Relate. Source: neo4j.com. · Original source

Neo4j’s November 11, 2026 press release announcing Relate. Source: neo4j.com.

What matters for this guide is the architecture. The Relate README says one engine powers the CLI, the language libraries, and an optional single-process server that speaks Bolt, HTTP and MCP. A graph can be a single .rl file, a directory or pure memory. The same binary seeds the graph and serves it to the agent, so you don’t provision anything between having the data and letting the agent query it.

The README is just as direct about limits. By design, the working set fits in memory, each store holds one graph, and each process serves a single user or agent. Relate is not a multi-tenant server. Its serve mode speaks plaintext and binds to loopback by default. That is why this guide ends on a Neo4j server. Relate is the prototype and the scratch space. A graph that several people and agents share belongs on a server with real accounts.

If you have already given an agent a database, the pattern will look familiar from our guides to a Postgres MCP server behind a read-only role, SQL Server MCP on a dev copy, the MongoDB MCP server in read-only mode and Apollo’s GraphQL MCP server with gated mutations: open a read-only path, prove it works, then widen access on purpose. The query language is what changes. Cypher’s variable-length patterns are where an agent’s answer most easily looks right and is wrong, so Step 4 exists to catch that.

Before you start: what you need and what you’ll build

You need one terminal and about half an hour. The graduation step needs more, and it’s optional.

  • [ ] A coding agent. Claude Code, the Codex CLI, or both, installed and signed in. If you haven’t registered an MCP server in Claude Code before, our guide to claude mcp add and scopes explains where each scope stores its entry.
  • [ ] A POSIX shell on macOS or Linux. The README also documents a PowerShell installer for Windows (irm https://relatedb.ai/install.ps1 | iex). The commands below assume bash or zsh.
  • [ ] An absolute path for throwaway graphs. This guide uses /home/dev/graphs/; replace it with your own path everywhere. Hosts start servers from directories you don’t control, and a relative path like ./deps.rl is the most common reason a first connection fails.
  • [ ] A telemetry decision. The README says the standalone relate CLI reports anonymous usage metrics by default: command shapes, feature flags and an install ID, but never query text, paths or data. relate telemetry off, DO_NOT_TRACK=1 or RELATE_TELEMETRY=0 turns it off.
  • [ ] Optional, for the graduation step: a Neo4j server reachable at bolt://localhost:7687, plus an account that can create a user and grant it read access.

By the end you’ll have these files and config entries. The rollback section removes each of them:

Artifact Where it lives Created in
deps.cypher, the seed script /home/dev/graphs/ Step 1
deps.rl, the single-file store /home/dev/graphs/ Step 1
expected.json, your hand-written answer /home/dev/graphs/ Step 4
relate server entry ~/.claude.json, Claude Code local scope Step 2
[mcp_servers.relate] table ~/.codex/config.toml Step 3
neo4j-mcp and neo4j entries (optional) Claude Code and Codex configs Graduation

Step 1: Install Relate and seed task:graph-deps-01

The seed is a small but realistic dependency graph: eight services, three datastores and one event bus, connected by DEPENDS_ON relationships. Each relationship has a mode property set to sync or async. That one property is the trap that makes the check in Step 4 worth doing.

  1. Install the binary, and read the script first. The README’s quick install is curl -sSfL https://relatedb.ai/install.sh | bash. It also points out that piping a script into a shell runs it before you have read it, and documents a download, inspect, run alternative. Use that one:
curl -sSfLo install.sh https://relatedb.ai/install.sh && less install.sh && bash install.sh
  1. Confirm the installer did what the README says. According to the README, it checks a signed SHA256SUMS manifest with the stock ssh-keygen, refuses to install if the signature is missing or invalid, and puts the binary in $HOME/.local/bin. Run relate --version. Relate’s documentation pages were recorded with relate 1.0.1, and the README’s example session shows v1.1.1. If any output below doesn’t match what you see, check your version first.
  2. Write the seed script. The heredoc is single-quoted so the shell leaves the Cypher alone:
mkdir -p /home/dev/graphs
cat > /home/dev/graphs/deps.cypher <<'EOF'
CREATE (web:Service {name: 'web', tier: 'edge', team: 'frontend'}),
       (gw:Service {name: 'api-gateway', tier: 'edge', team: 'platform'}),
       (auth:Service {name: 'auth', tier: 'core', team: 'identity'}),
       (checkout:Service {name: 'checkout', tier: 'core', team: 'commerce'}),
       (payments:Service {name: 'payments', tier: 'core', team: 'commerce'}),
       (inventory:Service {name: 'inventory', tier: 'core', team: 'commerce'}),
       (srch:Service {name: 'search', tier: 'core', team: 'discovery'}),
       (notify:Service {name: 'notifications', tier: 'support', team: 'platform'}),
       (ordersdb:Datastore {name: 'orders-db', engine: 'postgres'}),
       (usersdb:Datastore {name: 'users-db', engine: 'postgres'}),
       (idx:Datastore {name: 'search-index', engine: 'opensearch'}),
       (bus:Queue {name: 'events-bus'}),
       (web)-[:DEPENDS_ON {mode: 'sync'}]->(gw),
       (gw)-[:DEPENDS_ON {mode: 'sync'}]->(auth),
       (gw)-[:DEPENDS_ON {mode: 'sync'}]->(checkout),
       (gw)-[:DEPENDS_ON {mode: 'sync'}]->(srch),
       (auth)-[:DEPENDS_ON {mode: 'sync'}]->(usersdb),
       (checkout)-[:DEPENDS_ON {mode: 'sync'}]->(payments),
       (checkout)-[:DEPENDS_ON {mode: 'sync'}]->(inventory),
       (checkout)-[:DEPENDS_ON {mode: 'sync'}]->(ordersdb),
       (checkout)-[:DEPENDS_ON {mode: 'async'}]->(bus),
       (payments)-[:DEPENDS_ON {mode: 'sync'}]->(ordersdb),
       (inventory)-[:DEPENDS_ON {mode: 'sync'}]->(ordersdb),
       (srch)-[:DEPENDS_ON {mode: 'sync'}]->(idx),
       (notify)-[:DEPENDS_ON {mode: 'async'}]->(bus),
       (notify)-[:DEPENDS_ON {mode: 'async'}]->(checkout);
CREATE INDEX relate_Datastore__name FOR (n:Datastore) ON (n.name);
EOF
  1. Seed the store. Relate’s guide to driving it from an agent seeds a new single-file store by piping a script into relate query --database <file>.rl. Relate creates the .rl file if it doesn’t exist:
relate query --database /home/dev/graphs/deps.rl --mode envelope < /home/dev/graphs/deps.cypher
echo "exit=$?"

Expected observation (illustrative): one envelope line per statement, each with "rows":[] because neither statement has a RETURN, then exit=0. A nonzero exit means the script did not finish. Read the stderr message before you retry. Exit code 6 means a statement was rejected (a syntax, semantic or type error), and for a syntax error the error object includes column and source, which point at the failing token. If your version rejects the index statement inside a mixed script, run that line as its own command. 5. Check the counts with a read-only open. These two queries prove the graph is what you think it is, before any agent touches it:

relate --database /home/dev/graphs/deps.rl --read-only --mode envelope \
  'MATCH (n) RETURN labels(n)[0] AS label, count(*) AS nodes ORDER BY label'
relate --database /home/dev/graphs/deps.rl --read-only --mode envelope \
  'MATCH ()-[r:DEPENDS_ON]->() RETURN r.mode AS mode, count(*) AS edges ORDER BY mode'

Expected observation (illustrative): the first query returns three rows: Datastore 3, Queue 1 and Service 8. The second returns async 3 and sync 11. Both exit 0.

Why these choices? A single .rl file makes cleanup one rm, and it gives every host one absolute path to point at. The --read-only flag on the checks matters too. Per the drive-from-an-agent guide, a read-only open never writes, checkpoints or migrates the store, and any write attempted through it fails with exit code 6. Close every writer before Step 2, because a .rl file can only be opened while no writer holds it.

The last line of the seed adds an index on Datastore.name. When Relate’s MCP server answers a query that filters on an unindexed property, the documented reply includes a MissingIndex performance notification with a CREATE INDEX remedy. On a read-only store the agent can’t apply that remedy. Adding the index in the seed removes a notification that would otherwise tempt the agent to try to change a store it shouldn’t write to. The README’s relate skill install is optional and separate: it teaches agents the CLI, and you don’t need it for MCP.

Step 2: Serve the store read-only and register it in Claude Code

relate serve --mcp takes either the keyword stdio or a port number. Both serve the same tools. Relate’s Connect over MCP guide compares them, and the table below follows it:

Transport Who starts it Authentication Use it when
--mcp stdio The host, as a child process, until it closes stdin None; passing --auth with stdio is a usage error One agent host on your machine (this guide’s default)
--mcp <port> You, as a long-running process, until SIGINT or SIGTERM Basic auth from --auth or RELATE_AUTH, or a token it generates A host that only connects to URLs, or several clients sharing one server

With --read-only, the server lists exactly two tools, read_cypher and get_schema. write_cypher appears only when the store is writable. Work through these steps in order:

  1. Test the server from the shell before any host is involved. This sends three JSON-RPC messages the way a host would: initialize, then tools/list, then a write sent to read_cypher.
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"shell","version":"0"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"read_cypher","arguments":{"statement":"CREATE (:Service {name: $n})","parameters":{"n":"rogue"}}}}' \
  | relate serve --mcp stdio --database /home/dev/graphs/deps.rl --read-only 2>/dev/null

Expected observation: three lines. The tools/list reply names read_cypher and get_schema, both annotated readOnlyHint: true, and doesn’t include write_cypher. The third reply should match what Relate’s guide records for a write sent to the read tool: "text":"Only MATCH queries are allowed for read-query" with "isError":true. The store is unchanged. 2. Register the server in Claude Code. Relate’s guide gives the command; only the path is different here:

claude mcp add relate -- relate serve --mcp stdio --database /home/dev/graphs/deps.rl --read-only

The -- separates Claude Code’s own options from the server’s command. The Claude Code MCP documentation explains that without it, Claude Code would try to parse the server’s flags as its own. The entry goes into local scope, stored in ~/.claude.json under the current project. Add --scope project only if you want the entry written to a committed .mcp.json. Claude Code then asks each person to approve the server before it’s used. 3. Check its health. Run claude mcp list. Claude Code documents three statuses here: ✔ Connected, ! Needs authentication and ✘ Failed to connect. If it fails, claude mcp get relate prints an Issue: line with the detail. 4. Check the tools inside a session. Start claude in the project and run /mcp. The relate server should show two tools. A tool’s full name follows Claude Code’s mcp__<server>__<tool> pattern, so when the agent calls one you’ll see mcp__relate__read_cypher in the transcript. Use that name in permission rules or hooks.

relatedb.ai documentation page titled Connect over MCP, from the Relate agents guides.
Relate's Connect over MCP guide on relatedb.ai. The host configurations in this tutorial follow it. Source: relatedb.ai, captured November 2026. · Original source

Relate’s Connect over MCP guide on relatedb.ai. The host configurations in this tutorial follow it. Source: relatedb.ai, captured November 2026.

The HTTP variant, if you need a URL. Start the server yourself with a credential, then register the URL:

RELATE_AUTH=relate:choose-a-long-secret relate serve --mcp 8000 --database /home/dev/graphs/deps.rl --read-only
# in a second terminal
CRED=$(printf '%s' 'relate:choose-a-long-secret' | base64)
claude mcp add --transport http relate-http http://127.0.0.1:8000 --header "Authorization: Basic $CRED"

Relate’s guide says the port listener binds to 127.0.0.1 by default and speaks plaintext HTTP with no TLS. Without --auth or RELATE_AUTH, it generates a token for the user relate and saves it next to the store in an .auth-token file. Keep it on loopback. The README says that for encrypted connections you should put a TLS-terminating proxy in front of it.

Step 3: Register the same server in Codex

The Codex MCP documentation stores servers in ~/.codex/config.toml, or in .codex/config.toml inside a trusted project. The Codex CLI, the IDE extension and the ChatGPT desktop app all share this file. Each server is a [mcp_servers.<name>] table.

  1. Add the table. The command and args lines are Relate’s documented Codex block. The last three keys come from Codex’s own list of options:
[mcp_servers.relate]
command = "relate"
args = ["serve", "--mcp", "stdio", "--database", "/home/dev/graphs/deps.rl", "--read-only"]
startup_timeout_sec = 20
tool_timeout_sec = 60
default_tools_approval_mode = "writes"
  1. Know why each extra key is there. startup_timeout_sec defaults to 10 in Codex, and 20 gives a cold machine more room. tool_timeout_sec is shown at its documented default of 60 so you can find it later. default_tools_approval_mode = "writes" prompts only for tools that aren’t marked read-only. Relate marks both of its read-only tools with readOnlyHint: true, so get_schema and read_cypher run without a prompt. If someone later removes --read-only from args, the newly listed write_cypher will ask for approval. Our Codex approval modes guide covers how this setting interacts with the sandbox.
  2. Or add the entry from the CLI: codex mcp add relate -- relate serve --mcp stdio --database /home/dev/graphs/deps.rl --read-only. The CLI form doesn’t set the timeout or approval keys, so add them to the table afterwards.
  3. Check it. codex mcp list shows configured servers, and /mcp inside the codex TUI shows active servers. You should see relate with get_schema and read_cypher.
  4. The HTTP variant. Relate’s guide shows the URL form only for Claude Code. For a Streamable HTTP server, Codex documents the keys url, bearer_token_env_var, http_headers and env_http_headers, so the Basic credential can come from an environment variable instead of the file:
[mcp_servers.relate_http]
url = "http://127.0.0.1:8000"
env_http_headers = { "Authorization" = "RELATE_BASIC" }
default_tools_approval_mode = "writes"

Before starting Codex, export the credential in the same shell with export RELATE_BASIC="Basic $(printf '%s' 'relate:choose-a-long-secret' | base64)". Codex’s docs say that if no credential source resolves, Codex can connect without authentication. Relate then answers 401, which is the failure you want to see.

Step 4: Check the agent’s Cypher against your own answer

This is the step the rest of the guide sets up. The question for task:graph-deps-01 is concrete: which services stop working if orders-db goes down, following only synchronous dependencies? You’ll answer it twice, once by hand and once through the agent, and you’ll trust the agent’s statement only when the rows match.

Diagram of the Cypher check loop for task:graph-deps-01: seed deps.rl, then your hand-written relate --read-only query and the agent's read_cypher query both feed a compare-rows step that branches to Match (save the statement as a fixture) or Mismatch (read the statement, fix the hint) with a dashed re-ask path back to the agent.Diagram of the Cypher check loop for task:graph-deps-01: seed deps.rl, then your hand-written relate --read-only query and the agent's read_cypher query both feed a compare-rows step that branches to Match (save the statement as a fixture) or Mismatch (read the statement, fix the hint) with a dashed re-ask path back to the agent.
Illustrative loop: trust the agent's Cypher only when its rows equal your hand-written answer of five services. Based on Relate's CLI and MCP documentation, November 2026.

The agent’s query is reusable only after its rows equal yours. Illustrative loop for task:graph-deps-01, based on Relate’s CLI and MCP documentation.

  1. Write the expected answer yourself. Run it with the CLI, read-only, and save the envelope:
cd /home/dev/graphs
relate --database /home/dev/graphs/deps.rl --read-only --mode envelope \
  --param 'store="orders-db"' \
  'MATCH p = (s:Service)-[:DEPENDS_ON*1..6]->(:Datastore {name: $store})
   WHERE all(r IN relationships(p) WHERE r.mode = "sync")
   RETURN DISTINCT s.name AS service ORDER BY service' > expected.json
echo "exit=$?"

The pattern follows DEPENDS_ON for one to six hops. The longest chain in the seed is four hops: web, api-gateway, checkout, payments, orders-db. The query keeps only paths where every relationship is sync and returns each service once. The parameter value is quoted as JSON because, per the drive-from-an-agent guide, --param parses its value as JSON. The single quotes around the statement stop the shell from expanding $store.

Expected observation (illustrative, worked out by hand from the seed): exit=0 and five rows: api-gateway, checkout, inventory, payments and web. notifications isn’t in the list because its only route to orders-db is the async edge into checkout. auth and search never reach orders-db at all. 2. Ask the agent. In Claude Code or Codex, paste:

Use only the relate MCP tools. Call get_schema first. Then answer: which Service
nodes stop working if the Datastore named orders-db is down? Follow DEPENDS_ON
in any number of hops, but only through relationships whose mode is 'sync'.
Return the names sorted alphabetically, and show the exact statement and
parameters you sent to read_cypher.
  1. Compare the rows, then read the statement. Line up the agent’s sorted names against the rows array in expected.json. Then open the tool call in the transcript. Per Relate’s guide, a read_cypher call carries statement and parameters, and the reply carries columns, rows, a plan and any notifications.
  2. Decide. If the agent returned the same five names, save its statement next to the store as a fixture and reuse it. If it returned anything else, its statement shows which mistake the model made. The table and paragraph below cover the common ones.

Here is the worked example end to end. Every expected result is illustrative, derived from the documentation and the seed; none of these were run for this article.

Input Action Expected result
task:graph-deps-01 seed: deps.cypher with 12 nodes and 14 DEPENDS_ON edges, written to /home/dev/graphs/deps.rl relate query --database /home/dev/graphs/deps.rl --mode envelope < deps.cypher, then both count queries with --read-only exit=0; labels Datastore 3, Queue 1, Service 8; modes async 3, sync 11
task:graph-deps-01 Claude Code entry named relate claude mcp add relate -- relate serve --mcp stdio --database /home/dev/graphs/deps.rl --read-only, then claude mcp list relate line shows ✔ Connected; /mcp lists two tools, get_schema and read_cypher
task:graph-deps-01 Codex table [mcp_servers.relate] with default_tools_approval_mode = "writes" codex mcp list, then /mcp in the Codex TUI relate listed with get_schema and read_cypher, no write_cypher, no approval prompt for either read tool
task:graph-deps-01 prompt line: Call get_schema first Agent calls get_schema on deps.rl Reply lists Service (count 8; name, team, tier), Datastore (count 3), Queue (count 1) and DEPENDS_ON with a mode property
task:graph-deps-01 question: services down when orders-db fails, sync edges only Agent calls read_cypher with a statement and parameters Five rows: api-gateway, checkout, inventory, payments, web; identical to expected.json
task:graph-deps-01 write probe: Create a Service named rogue Agent finds no write_cypher; if it sends CREATE to read_cypher anyway Tool error Only MATCH queries are allowed for read-query; a later Service count still returns 8
task:graph-deps-01 on a Neo4j server via neo4j-mcp with NEO4J_MCP_READ_ONLY=true Agent calls read-cypher with the same question Same five rows; the tool list shows only get-schema and read-cypher

How to read a mismatch. Three rows (checkout, inventory, payments) mean the agent matched a single hop, (s)-[:DEPENDS_ON]->(d), and missed the chain through api-gateway and web. Six rows that include notifications mean it followed any number of hops but dropped the mode = 'sync' filter. A result with no rows usually means it skipped get_schema and guessed a label, such as :Database. In that case Relate returns an empty result with its columns intact, and the agent may report that nothing depends on orders-db. Each case has a one-sentence fix in the prompt: name the hop count, name the property filter, or insist on get_schema first.

Two habits make the check cheap to repeat. First, keep expected.json next to deps.cypher, so any change to the seed forces you to regenerate the answer. Second, if the agent runs the CLI from its shell instead of using MCP, remember the row cap in the drive-from-an-agent guide. Under a detected agent harness, the CLI prints at most 100 rows per statement and reports the cut in-band with "truncated": true and a rowCap object, while the exit code stays 0. Compare row counts before you compare names.

When it breaks: symptoms, causes and fixes

Most failures show up as a status in claude mcp list or Codex’s /mcp, or as a line in the host’s server log. The CLI uses fixed exit codes: 1 for a runtime failure, 2 for a usage error, 5 for a conflict or a locked store, 6 for a rejected statement and 7 for a timeout. Match your symptom here:

Symptom Likely cause Fix
Host log shows Error: Failed to open Relate: storage error: database not found: <path> A read-only open never creates a store, and a relative path resolved against an unexpected directory Use the absolute path in the entry, and seed the store first (Step 1)
The host cannot start relate at all The host’s PATH doesn’t include ~/.local/bin, which is common for desktop apps Put the binary’s absolute path in command
Failed to open Relate: storage locked: <path>, exit code 5 Another process holds the .rl store, often your seeding shell Exit the writer. A .rl file can’t be opened read-only while a writer holds it; a directory store can
relate serve exits 2 with an error beginning Error: serve --mcp stdio skips auth --auth passed to a stdio server Remove --auth; it only applies to port listeners
HTTP 401 Unauthorized with WWW-Authenticate: Basic realm="relate" The credential is missing or wrong Recompute the base64 of user:password, and check RELATE_AUTH on the server side
HTTP 415 Unsupported Media Type A POST with no Content-Type, or a browser-simple one Send Content-Type: application/json in hand-written curl tests
✘ Failed to connect on a slow first start Startup took longer than the host’s timeout Claude Code: MCP_TIMEOUT=10000 claude. Codex: raise startup_timeout_sec (default 10)
The port listener won’t start The port is probably already in use; Relate’s docs don’t quote the message Pick another port, for example --mcp 8001, and update the registered URL
Claude Code reports MCP server "relate-http" has a "url" but no "type" A JSON entry was copied without a type Add "type": "http" to the entry
The agent reports Only MATCH queries are allowed for read-query or unknown tool 'write_cypher' Read-only working as configured Not a bug. For writes, open a separate writable session deliberately
The agent’s CLI run exits 6 with ParameterMissing The statement uses $name and nothing binds it, or double quotes let the shell eat $name Pass --param name=value and single-quote the statement
Neo4j MCP ignores read-only or rejects credentials Variable names copied from an older configuration Use the NEO4J_MCP_-prefixed names on Neo4j’s current client-configuration page

Graduate to a read-only Neo4j server with the official Neo4j MCP server

Relate let you prove the agent can query your graph correctly. When the graph needs to be shared, or outgrows memory, move the agent to a Neo4j server behind Neo4j’s own MCP server. The Neo4j MCP tools page lists four tools: get-schema, read-cypher, write-cypher and list-gds-procedures. Setting NEO4J_MCP_READ_ONLY=true stops the server from exposing write tools. read-cypher rejects writes, schema and admin operations, and PROFILE queries, and it makes an extra round-trip to the database to classify each query. NEO4J_MCP_TOOLS narrows the list further, and the docs say read-only takes precedence: a write tool named in NEO4J_MCP_TOOLS stays disabled.

Matrix chart titled Read-only mode drops the write tool on both servers: five rows (Relate serve writable, Relate serve --read-only, neo4j-mcp defaults, neo4j-mcp with NEO4J_MCP_READ_ONLY=true, neo4j-mcp read-only plus NEO4J_MCP_TOOLS) against schema, read query, write query and GDS list columns.Matrix chart titled Read-only mode drops the write tool on both servers: five rows (Relate serve writable, Relate serve --read-only, neo4j-mcp defaults, neo4j-mcp with NEO4J_MCP_READ_ONLY=true, neo4j-mcp read-only plus NEO4J_MCP_TOOLS) against schema, read query, write query and GDS list columns.
Both servers stop listing their write tool in read-only mode; the NEO4J_MCP_TOOLS filter also removes list-gds-procedures. Sources: relatedb.ai Connect over MCP and Neo4j MCP Tools pages, fetched November 17, 2026.

Both servers hide their write tool once read-only mode is on; the NEO4J_MCP_TOOLS filter also drops list-gds-procedures. Sources: relatedb.ai Connect over MCP and Neo4j MCP Tools documentation, fetched November 17, 2026.

  1. Load the same data. The seed is plain Cypher, so you can run deps.cypher against the server with whatever admin client you already use. Relate also has relate pull and relate push, which mirror a subgraph between Relate and a Neo4j or Aura instance over Query API v2. Their flags are in Relate’s push reference, which this guide did not review.
  2. Create a dedicated, low-privilege database user, called agent_reader below, that can read this database and nothing else. The commands vary by Neo4j edition and are documented in the Neo4j Operations Manual, which is outside this guide’s evidence. Follow that manual. Don’t reuse the admin account that appears in the examples on Neo4j’s configuration page.
  3. Install the server. Neo4j’s client configuration page lists two routes: the neo4j-mcp executable, installed with Homebrew or manually, or uvx, which downloads the server from PyPI without a separate install step.
  4. Register it in Claude Code with read-only on and the tool filter set. The command adds one variable to the documented example:
claude mcp add neo4j-mcp \
  --env NEO4J_MCP_URI=bolt://localhost:7687 \
  --env NEO4J_MCP_USERNAME=agent_reader \
  --env NEO4J_MCP_PASSWORD="$AGENT_READER_PASSWORD" \
  --env NEO4J_MCP_DATABASE=neo4j \
  --env NEO4J_MCP_READ_ONLY=true \
  --env NEO4J_MCP_TOOLS=get-schema,read-cypher \
  -- neo4j-mcp

Keep this entry in local scope. The shell expands the password when you add the server, so it ends up in ~/.claude.json. A project-scoped .mcp.json would put it in version control. 5. Register it in Codex. Codex’s env_vars key forwards a variable from your shell, so the password never goes into the file:

[mcp_servers.neo4j]
command = "neo4j-mcp"
env_vars = ["NEO4J_MCP_PASSWORD"]
startup_timeout_sec = 20

[mcp_servers.neo4j.env]
NEO4J_MCP_URI = "bolt://localhost:7687"
NEO4J_MCP_USERNAME = "agent_reader"
NEO4J_MCP_DATABASE = "neo4j"
NEO4J_MCP_READ_ONLY = "true"
NEO4J_MCP_TOOLS = "get-schema,read-cypher"
NEO4J_MCP_TELEMETRY = "false"
  1. Verify. In /mcp in either host, the server should list only get-schema and read-cypher. Rerun the Step 4 prompt, swapping in the Neo4j tool names, and compare the result against the same five names. Then ask the agent to create a Service named rogue. It has no write tool to call, and if it sends the write through read-cypher, the server rejects it. The Neo4j pages don’t quote the exact refusal text, so judge by the outcome: a follow-up count of Service nodes still returns 8.

The low-privilege user is the backstop. Read-only mode is enforced by the MCP server’s configuration, and that configuration can be edited. A database account that can’t write stays read-only even if someone later removes NEO4J_MCP_READ_ONLY from a config file.

Relate, Neo4j server or Aura: a decision table

Use the graph’s audience and size to decide where it should live, not which tool is newest. Read across each row:

Question Relate, embedded Neo4j server with neo4j-mcp Aura with Neo4j’s hosted MCP
Where does the graph live? A .rl file, a directory or memory on your machine Your own Neo4j server Neo4j’s managed cloud service
How many users at once? One user or agent per process, per the README Many, each with their own database account Many, through Aura’s own account management
How does the agent connect? The host starts relate serve --mcp stdio The host starts neo4j-mcp with a Bolt URI and credentials claude mcp add --transport http neo4j-mcp https://<instance-id>.mcp-instances.neo4j.io
What is the read-only switch? --read-only on serve; write_cypher is not listed NEO4J_MCP_READ_ONLY=true or --read-only true, plus NEO4J_MCP_TOOLS Not covered by the pages this guide used; check Neo4j’s MCP for Aura page
What limits size? The working set must fit in memory Your server’s capacity Your Aura plan
Pick it when Prototyping, per-task scratch graphs, or memory for one project’s agent A team graph that several agents read, with accounts you control You want hosted Neo4j and don’t want to run servers

You can also mix them. The launch blog describes pulling a slice of a larger Aura or Neo4j graph into a local Relate sandbox. The README shows the shape: relate pull --from neo4j.env --query "MATCH (o:Organization)-[r]-() RETURN o, r LIMIT 500" --database ./mirror. The agent then experiments on the mirror, and the shared graph stays behind its read-only MCP server.

Roll back cleanly

Everything this guide created is a config entry or a file. Remove them in this order, so no host is left pointing at a store that no longer exists:

  1. Remove the Claude Code entries: claude mcp remove relate, plus claude mcp remove relate-http and claude mcp remove neo4j-mcp if you added them. If you used project scope, add --scope project.
  2. Remove or disable the Codex tables. Delete [mcp_servers.relate], [mcp_servers.relate_http] and [mcp_servers.neo4j], or set enabled = false in a table to keep it without connecting. Confirm with codex mcp list.
  3. Stop any port listener with Ctrl-C. Relate’s serve process runs until SIGINT or SIGTERM.
  4. Delete the throwaway store and its artifacts: deps.rl, plus any .auth-token file Relate saved next to it, and deps.cypher and expected.json if you no longer need the fixture.
  5. Remove the optional pieces. If you installed the agent skill, run relate skill remove, which is safe to run more than once. To remove Relate entirely, delete the binary from $HOME/.local/bin. The README doesn’t document an uninstall command.
  6. On Neo4j, after removing the MCP entries, disable or drop agent_reader as described in the Operations Manual.

What the documentation does not settle

A few gaps are worth knowing before you rely on this setup. Relate’s guides don’t quote the error printed when an MCP port is already in use. They describe the 100-row agent cap for the CLI, but don’t say whether MCP replies are capped the same way, so check row counts in read_cypher replies on large graphs. Neo4j’s tools page explains which queries read-cypher rejects but doesn’t quote the rejection message. Creating the read-only database user and setting read-only behavior for Aura’s hosted MCP endpoint are both documented on pages this guide didn’t use. Neo4j’s docs also list a page on migrating neo4j-mcp from v1 to v2. If your existing configuration predates the NEO4J_MCP_ variable names, read that page before you graduate.

If this graph becomes one of several data sources your agents use, treat each MCP server as a component you operate, with an owner, a read-only default and a rollback. Our AgentOps guide covers running agents and their tools as a fleet.

Sources

  1. Neo4j, New In-Memory Database Purpose-Built for AI Agents (Relate press release), November 11, 2026.
  2. Neo4j, Meet Relate by Neo4j: An Embedded Database for AI Agents, November 11, 2026.
  3. relatedb, relate repository README, fetched November 17, 2026.
  4. Relate documentation, Connect over MCP, fetched November 17, 2026.
  5. Relate documentation, Drive relate from an agent, fetched November 17, 2026.
  6. Neo4j MCP documentation, Client configuration, fetched November 17, 2026.
  7. Neo4j MCP documentation, Tools, fetched November 17, 2026.
  8. Anthropic, Connect Claude Code to tools via MCP, fetched November 17, 2026.
  9. OpenAI, Codex: Model Context Protocol, fetched November 17, 2026.
  10. Neo4j on X, launch post for Relate, November 11, 2026.
YOU'RE THROUGH THIS ONE.

Keep connecting the dots.

Back to the library

Many assistants.
One place to remember.

Bring your AI sessions, context, and usage together with Automater.

Meet Automater