Skip to main content
The Neo4j MCP server implements the Model Context Protocol, bridging AI assistants and your Neo4j database. It exposes tools for schema inspection and Cypher query execution — both read and write. Register it on the TrueFoundry MCP Gateway when you want agents to query Neo4j graph databases through governed, observable access. Unlike TrueFoundry Managed or official remote MCP servers, the Neo4j MCP server is one you host yourself. You deploy the mcp/neo4j-cypher image in HTTP transport mode, then register its public endpoint as a remote MCP server in TrueFoundry.

​
How TrueFoundry Manages the MCP Server

TrueFoundry’s MCP Gateway acts as a reverse proxy between your agents and MCP servers like Neo4j. When you register your deployed Neo4j server, TrueFoundry handles:
  • Authentication — Agents authenticate once to the TrueFoundry MCP Gateway. The gateway attaches the outbound Basic Auth header to every request reaching your Neo4j MCP server, so individual users never handle the database credentials.
  • Tool-level access control — You can selectively enable or disable individual tools (for example, disable write_neo4j_cypher) per team from the TrueFoundry UI.
  • Audit trail — Every tool invocation is traced with the calling user, tool name, input payload (including the Cypher query), and latency. Traces export via OpenTelemetry to your observability stack.
  • Guardrails — TrueFoundry’s guardrail hooks apply at mcp_pre_tool (before a tool is invoked) and mcp_post_tool (after the tool returns), letting you enforce policies on queries and results in real time.

​
Prerequisites

  • A TrueFoundry account with permission to add MCP servers.
  • A running Neo4j instance — Neo4j Aura (cloud), self-managed, or Docker — and its connection URI (for example, neo4j+s://xxxxxx.databases.neo4j.io for Aura).
  • The Neo4j MCP server deployed and reachable over a public HTTPS URL. You can run the mcp/neo4j-cypher Docker image on any platform (AWS ECS, Azure Container Apps, Google Cloud Run, Railway, Render, etc.).

​
Deploy the Neo4j MCP Server

The Neo4j MCP server must run in HTTP transport mode to work as a remote MCP server. The default STDIO mode only works for local desktop clients (Claude Desktop, VS Code). HTTP mode exposes a network endpoint that TrueFoundry’s MCP Gateway can route traffic to. Use the official Docker image mcp/neo4j-cypher:latest, expose port 8080, and set these environment variables: 
# Neo4j connection — required
NEO4J_URL=neo4j+s://<your-instance-id>.databases.neo4j.io
NEO4J_USERNAME=<your-neo4j-username>
NEO4J_PASSWORD=<your-neo4j-password>
NEO4J_DATABASE=<your-database-name>      # e.g. your Aura instance ID

# HTTP server config — required for remote deployment
NEO4J_TRANSPORT=http
NEO4J_MCP_SERVER_HOST=0.0.0.0
NEO4J_MCP_SERVER_PORT=8080
NEO4J_MCP_SERVER_PATH=/mcp/

# Security — whitelist your public hostname
NEO4J_MCP_SERVER_ALLOWED_HOSTS=<your-public-hostname>

# Optional — disable write operations in production
NEO4J_READ_ONLY=true
Once deployed, your MCP endpoint will be: 
https://<your-public-hostname>/mcp/
NEO4J_DATABASE — For Neo4j Aura, the database name is typically your instance ID (visible in the Aura console top bar), not the default neo4j. Run SHOW DATABASES in the Aura Query tab to confirm.NEO4J_MCP_SERVER_ALLOWED_HOSTS — If you see Invalid host header after deployment, this variable is missing. Set it to your public hostname (for example, neo4j.mcp.example.com).
See the full environment variable reference below.

​
Register Neo4j in TrueFoundry

1

Open the Add MCP Server picker

Navigate to MCP Servers in the TrueFoundry sidebar and click Add new MCP Server. Select Connect any Remote MCP Server — this lets you provide the URI and auth credentials for any remote MCP server you host.
Add new MCP Server picker with the Connect any Remote MCP Server option highlighted
2

Configure the server and auth

Fill in your deployed server’s details and Basic Auth credentials:
FieldValue
Nameneo4j
DescriptionNeo4j graph database
URLhttps://<your-public-hostname>/mcp/
Auth TypeAPI Key → Shared Credentials
Header NameAuthorization
Header ValueBasic <base64(username:password)>
Add Collaborators — the users and teams that can use or manage this server — and assign each an MCP Server Manager or MCP Server User role. Click Update MCP Server to save.
Generate the Basic Auth token by base64-encoding your username:password:
echo -n "your-username:your-password" | base64
Paste the output after Basic as the Authorization header value.
MCP Server registration form showing API Key auth with Shared Credentials and the Authorization header configured
3

Verify tools

Once saved, TrueFoundry introspects the server and lists its tools automatically — covering schema inspection and read and write Cypher execution. Each tool shows its description and a Try button so you can test it before wiring it into an agent.
Neo4j MCP server Tools tab listing the introspected tools
The server detail page shows the registered endpoint, auth type, and the full tool list.
Neo4j MCP server detail page showing the endpoint, auth configuration, and registered tools

​
Connecting to an MCP Client

TrueFoundry exposes the Neo4j MCP server over HTTP transport. The endpoint is specific to your TrueFoundry tenant, so don’t construct it by hand — copy the exact URL and ready-to-paste connection commands from the How To Use tab on the Neo4j server detail page. The How To Use tab generates connection instructions for every major client, including Cursor, VS Code, Claude Code, Claude Desktop, Windsurf, Codex, and the Python and TypeScript MCP SDKs. Click Show API Key to reveal your personal gateway API key, which authenticates your client to the TrueFoundry Gateway. Copy the snippet for your client and paste it into the relevant settings file.
Neo4j How To Use tab showing per-client connection configs

​
Using Neo4j in TrueFoundry Agents

You can attach the Neo4j MCP server directly to an agent in the TrueFoundry AI Engineering UI:
1

Create or open an agent

Go to AI Engineering → Agents → New Agent.
2

Attach the MCP server

Under MCP Servers, click + and select neo4j. Choose All tools or select specific tools as needed.
3

Query your graph

Send a message like “What does my database contain?” The agent automatically inspects the schema with get_neo4j_schema and runs Cypher queries against your graph to answer.
TrueFoundry agent using Neo4j MCP tools to inspect the schema and return query results

​
Environment Variables Reference

VariableRequiredDescription
NEO4J_URL✅Bolt URI to your Neo4j instance
NEO4J_USERNAME✅Neo4j username
NEO4J_PASSWORD✅Neo4j password
NEO4J_DATABASE✅Database name
NEO4J_TRANSPORT✅Set to http for remote deployment
NEO4J_MCP_SERVER_HOST✅Set to 0.0.0.0 for Docker
NEO4J_MCP_SERVER_PORT✅Port to expose (e.g. 8080)
NEO4J_MCP_SERVER_PATHRecommendedURL path prefix (e.g. /mcp/)
NEO4J_MCP_SERVER_ALLOWED_HOSTSRecommendedComma-separated allowed hostnames
NEO4J_READ_ONLYOptionaltrue to disable write operations
NEO4J_READ_TIMEOUTOptionalQuery timeout in seconds (default: 30)
NEO4J_SCHEMA_SAMPLE_SIZEOptionalNodes to sample for schema (default: 100)

​
Next Steps

MCP Gateway Overview

Learn how the TrueFoundry MCP Gateway centralizes access, auth, and observability for all your MCP servers.

MCP Gateway Getting Started

Add MCP servers and use them in the AI Gateway playground and IDEs.

Neo4j MCP documentation

Reference for the Neo4j MCP server, its tools, and configuration options.

MCP Gateway Security

Configure authentication and guardrails on your MCP servers.