> ## Documentation Index
> Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up Neo4j MCP Server

> Connect a deployed Neo4j MCP server to the TrueFoundry MCP Gateway so agents can inspect schema and run Cypher queries using natural language.

The [Neo4j MCP server](https://neo4j.com/docs/mcp/current/) implements the [Model Context Protocol](https://modelcontextprotocol.io), 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](https://console.neo4j.io) (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:

```bash theme={"dark"}
# 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/
```

<Note>
  **`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`).
</Note>

See the [full environment variable reference](#environment-variables-reference) below.

## Register Neo4j in TrueFoundry

<Steps>
  <Step title="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.

    <Frame>
      <img src="https://mintcdn.com/truefoundry/-YvpciUU4Kg6EYfl/images/docs/ai-gateway/neo4j-add-mcp-options.jpg?fit=max&auto=format&n=-YvpciUU4Kg6EYfl&q=85&s=15d5c28961a2947dfb63ca0aac375cc1" alt="Add new MCP Server picker with the Connect any Remote MCP Server option highlighted" width="1674" height="1664" data-path="images/docs/ai-gateway/neo4j-add-mcp-options.jpg" />
    </Frame>
  </Step>

  <Step title="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.

    <Tip>
      Generate the Basic Auth token by base64-encoding your `username:password`:

      ```bash theme={"dark"}
      echo -n "your-username:your-password" | base64
      ```

      Paste the output after `Basic ` as the Authorization header value.
    </Tip>

    <Frame>
      <img src="https://mintcdn.com/truefoundry/-YvpciUU4Kg6EYfl/images/docs/ai-gateway/neo4j-auth-config.png?fit=max&auto=format&n=-YvpciUU4Kg6EYfl&q=85&s=afe48376107bcc28689c05c55c0562a5" alt="MCP Server registration form showing API Key auth with Shared Credentials and the Authorization header configured" width="1976" height="1034" data-path="images/docs/ai-gateway/neo4j-auth-config.png" />
    </Frame>
  </Step>

  <Step title="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.

    <Frame>
      <img src="https://mintcdn.com/truefoundry/-YvpciUU4Kg6EYfl/images/docs/ai-gateway/neo4j-tools-list.png?fit=max&auto=format&n=-YvpciUU4Kg6EYfl&q=85&s=01958edbe59c9c0c971da091ecf626be" alt="Neo4j MCP server Tools tab listing the introspected tools" width="3498" height="1980" data-path="images/docs/ai-gateway/neo4j-tools-list.png" />
    </Frame>
  </Step>
</Steps>

The server detail page shows the registered endpoint, auth type, and the full tool list.

<Frame>
  <img src="https://mintcdn.com/truefoundry/-YvpciUU4Kg6EYfl/images/docs/ai-gateway/neo4j-server-detail.png?fit=max&auto=format&n=-YvpciUU4Kg6EYfl&q=85&s=7003974a08e4b6d6cbcc252150f474bc" alt="Neo4j MCP server detail page showing the endpoint, auth configuration, and registered tools" width="1994" height="1980" data-path="images/docs/ai-gateway/neo4j-server-detail.png" />
</Frame>

## 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.

<Frame>
  <img src="https://mintcdn.com/truefoundry/-YvpciUU4Kg6EYfl/images/docs/ai-gateway/neo4j-how-to-use.jpg?fit=max&auto=format&n=-YvpciUU4Kg6EYfl&q=85&s=2fd7f4bf0a0d790179f31368f9a47bf1" alt="Neo4j How To Use tab showing per-client connection configs" width="3230" height="1666" data-path="images/docs/ai-gateway/neo4j-how-to-use.jpg" />
</Frame>

## Using Neo4j in TrueFoundry Agents

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

<Steps>
  <Step title="Create or open an agent">
    Go to **AI Engineering → Agents → New Agent**.
  </Step>

  <Step title="Attach the MCP server">
    Under **MCP Servers**, click **+** and select `neo4j`. Choose **All tools** or select specific tools as needed.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Frame>
  <img src="https://mintcdn.com/truefoundry/-YvpciUU4Kg6EYfl/images/docs/ai-gateway/neo4j-agent-query.jpg?fit=max&auto=format&n=-YvpciUU4Kg6EYfl&q=85&s=17c5750c064927edaf1e99760b6ad0cc" alt="TrueFoundry agent using Neo4j MCP tools to inspect the schema and return query results" width="3222" height="1666" data-path="images/docs/ai-gateway/neo4j-agent-query.jpg" />
</Frame>

## 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) |