Set up Neo4j MCP Server - TrueFoundry Docs

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

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

Configure the server and auth

Fill in your deployed server’s details and Basic Auth credentials:

Field	Value
Name	`neo4j`
Description	`Neo4j graph database`
URL	`https://<your-public-hostname>/mcp/`
Auth Type	API Key → Shared Credentials
Header Name	`Authorization`
Header Value	`Basic <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

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:

Create or open an agent

Go to AI Engineering → Agents → New Agent.

Attach the MCP server

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

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

Variable	Required	Description
`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_PATH`	Recommended	URL path prefix (e.g. `/mcp/`)
`NEO4J_MCP_SERVER_ALLOWED_HOSTS`	Recommended	Comma-separated allowed hostnames
`NEO4J_READ_ONLY`	Optional	`true` to disable write operations
`NEO4J_READ_TIMEOUT`	Optional	Query timeout in seconds (default: 30)
`NEO4J_SCHEMA_SAMPLE_SIZE`	Optional	Nodes to sample for schema (default: 100)

​How TrueFoundry Manages the MCP Server

​Prerequisites

​Deploy the Neo4j MCP Server

​Register Neo4j in TrueFoundry

​Connecting to an MCP Client

​Using Neo4j in TrueFoundry Agents

​Environment Variables Reference

How TrueFoundry Manages the MCP Server

Prerequisites

Deploy the Neo4j MCP Server

Register Neo4j in TrueFoundry

Connecting to an MCP Client

Using Neo4j in TrueFoundry Agents

Environment Variables Reference