Skip to main content

​
At a glance

  • Availability: Experimental (how to enable).
  • Authentication: Basic auth.
  • Connection: HTTP Basic auth with NEO4J_USERNAME as the username and NEO4J_PASSWORD as the password.
  • Provider documentation: Authentication reference.

​
Credentials

Set these per environment. See Connect an integration.

​
Setup

  1. Create a Neo4j Aura instance: Sign up at https://console.neo4j.io and create an AuraDB Free instance (no credit card required). Download or copy the generated password: it is shown only once. Self-hosted Neo4j 5.19+ also exposes the Query API.
  2. Find your host: From the Aura console, copy the instance’s connection URI (neo4j+s://xxxxxxxx.databases.neo4j.io). Store the host part (xxxxxxxx.databases.neo4j.io) as NEO4J_HOST in your .env. Every tool sends its requests to this host.
  3. Store credentials: Add NEO4J_USERNAME=neo4j and NEO4J_PASSWORD=… to your .env file. The Query API authenticates with HTTP Basic auth using these values.
  4. Verify access: Run the Run Cypher Query tool with statement ‘RETURN 1 AS ok’ against database ‘neo4j’. A 401 means wrong credentials; a connection error usually means the wrong host.

​
Provider notes

  • The Query API requires Neo4j 5.19+ (all Aura instances qualify); on self-managed instances below 5.25 it is disabled by default and must be enabled in the server configuration. Aura serves it over HTTPS on port 443
  • Self-hosted instances must expose HTTPS (port 7473 by default) for these tools, since tool URLs use https://. Include the port in NEO4J_HOST, e.g. my-server:7473
  • Always pass Cypher values via the parameters object ($placeholders) rather than string-concatenating them into the statement; this enables plan caching and prevents Cypher injection
  • Both tools run implicit (auto-commit) transactions; explicit multi-request transactions are not exposed
  • The Query API has no server-side read-only mode: Run Cypher Query is read-only by convention only, and write statements sent through it would execute. Connect with a read-only database user if you need a hard guarantee
Provider API reference.

​
Tools

​
Verify the connection

Call a read tool such as neo4j__run_cypher_query with arguments for your account. Confirm that the result comes from the intended account or workspace before enabling write tools.