# MCP server for AI agents

[Wiki](../README.md) / [Clients and drivers](README.md)

The Galactus DB MCP server connects AI assistants and agents to your database
through the [Model Context Protocol](https://modelcontextprotocol.io). Agents
use it to read the schema, run Cypher, check the documentation and manage
their running queries.

It is an optional download that runs beside the database. The image is
`ianknowles/galactus-db-mcp:latest`, about 1 MB, for Linux AMD64 and ARM64. It
needs no licence of its own and works with the free Developer edition.

## How it signs in

The MCP server has no database identity of its own. Every tool call signs in to
Galactus DB as the person or agent using it, and the database checks their
[roles](../operations/authentication.md) on every statement.

- **Over stdio**, a desktop client starts the server and passes `GDB_USER` and `GDB_PASSWORD`.
- **Over HTTP**, every request carries its own credentials as HTTP Basic authentication. The server keeps no session between requests.

The server lists only the tools the caller's privileges can use. Hiding a tool
only tidies the list. A call to a tool that isn't listed still runs as the
caller, and the database refuses whatever their roles don't allow.

Give each agent its own database user with the least privilege it needs. With
the built-in `reader` role, an agent sees only the read, documentation and
operations tools, and the database refuses its writes.

## Start the server

### Shared HTTP server

Run one container next to the database. Each person or agent then connects to
`http://<host>:7688/mcp` with their own Galactus DB user.

```sh
docker run -d --name galactus-db-mcp --network <your-gdb-network> \
  -e GDB_URI=bolt://gdb:7687 \
  -p 127.0.0.1:7688:7688 \
  ianknowles/galactus-db-mcp:latest
```

In Compose, add a service beside the database:

```yaml
  mcp:
    image: ianknowles/galactus-db-mcp:latest
    environment:
      GDB_URI: bolt://db:7687
    ports: ["127.0.0.1:7688:7688"]
    depends_on:
      db: {condition: service_healthy}
```

### Desktop client over stdio

A desktop MCP client can start the image itself. This entry goes in its MCP
server configuration:

```json
{
  "mcpServers": {
    "galactus-db": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "GDB_MCP_TRANSPORT=stdio",
        "-e", "GDB_URI=bolt://host.docker.internal:7687",
        "-e", "GDB_USER=agent",
        "-e", "GDB_PASSWORD",
        "ianknowles/galactus-db-mcp:latest"],
      "env": {"GDB_PASSWORD": "<the agent's password>"}
    }
  }
}
```

## Connect a client

Claude Code, against a shared HTTP server:

```sh
claude mcp add --transport http galactus-db http://127.0.0.1:7688/mcp \
  --header "Authorization: Basic $(printf 'agent:password' | base64)"
```

Postman and other HTTP clients need:
- the MCP URL `http://127.0.0.1:7688/mcp`;
- Basic authentication with a Galactus DB user and password.

Any client that supports MCP over stdio or streamable HTTP can connect.

## Tools

| Tool | Listed for | What it does |
|---|---|---|
| `list-docs`, `search-docs`, `read-doc` | Everyone | Lists, searches and reads these documentation pages, built into the server |
| `get-schema` | Users who can read | Labels and relationship types with counts, property types, connecting patterns, indexes and constraints |
| `read-cypher` | Users who can read | Runs Cypher in a read transaction; the database refuses any write |
| `explain-cypher` | Users who can read | Shows the query plan without running the query |
| `write-cypher` | Users who can write or change the schema | Runs one statement in its own transaction |
| `list-databases` | Every signed-in user | Your databases, your home database and your access to each |
| `list-queries`, `terminate-query` | Every signed-in user | Lists and stops running queries: your own, or everyone's for administrators |
| `admin-cypher` | Administrators, when enabled | Users, roles, privileges and databases on `system` |

`get-schema`, `read-cypher` and `write-cypher` use the same names and arguments
as Neo4j's MCP server, so prompts written for it keep working.

### Results

Results come back as JSON rows:
- **Rows:** 100 by default; a call can ask for up to 1,000. The server discards the rest instead of transferring them.
- **Size:** results stop at about 64 KB, with a note saying why.
- **Graph elements:** nodes and relationships carry `_id` and `_labels`, or `_type`, `_start` and `_end`.
- **Long values:** embedding vectors and very long strings are summarised unless the call asks for them.
- **Dates and times:** returned as ISO 8601 strings.

## Settings

| Environment | Default | Purpose |
|---|---|---|
| `GDB_URI` | `bolt://127.0.0.1:7687` | The Galactus DB Bolt address |
| `GDB_MCP_TRANSPORT` | `http` in the image | `http`, or `stdio` for desktop clients |
| `GDB_MCP_BIND` | `0.0.0.0:7688` in the image | HTTP listen address; the endpoint is `/mcp` |
| `GDB_USER`, `GDB_PASSWORD` | none | The user for stdio; HTTP callers send their own |
| `GDB_MCP_READ_ONLY` | `false` | Never list or run `write-cypher` or `admin-cypher` |
| `GDB_MCP_ADMIN_TOOLS` | `false` | List `admin-cypher` to administrators |
| `GDB_MCP_ALLOWED_ORIGINS` | none | Browser origins allowed to call over HTTP, comma-separated |
| `GDB_MCP_QUERY_TIMEOUT_MS` | `30000` | Time limit for each statement; the server's own limit also applies |
| `GDB_MCP_DEFAULT_ROWS` | `100` | Rows returned when a call does not say |
| `GDB_MCP_MAX_ROWS` | `1000` | Most rows a call may ask for |
| `GDB_MCP_MAX_RESULT_BYTES` | `65536` | Approximate cap on returned rows |

## Security

- **Reads cannot write.** The read tools run in a Bolt read transaction, and the database refuses writes there even for users who may write.
- **Time limit.** Every statement carries one. When it passes, the server stops the statement and rolls it back.
- **Browser protection.** Requests with an `Origin` header are refused unless the origin is listed in `GDB_MCP_ALLOWED_ORIGINS`. This blocks DNS-rebinding attacks from web pages.
- **Audit log.** Each call writes one line to the container log: user, tool, database, outcome, rows and duration. Query text, parameters and passwords are never logged.
- **No encryption yet.** The HTTP endpoint has no TLS of its own, and passwords travel with every request. Publish it on `127.0.0.1` or a private network only, or put it behind a TLS reverse proxy. The connection from the MCP server to the database is plain Bolt in this release, so run the two side by side.
- **Prompt injection.** Text stored in your graph can contain instructions an agent might follow. Least-privilege users and `GDB_MCP_READ_ONLY` limit the harm; no tool list can prevent it.

## Current scope

- **Release:** 0.1 early access.
- **Protocol:** MCP tools only, with no resources or prompts. Supports protocol revisions 2024-11-05 to 2025-11-25.
- **Sign-in:** username and password only, with no OAuth or API tokens.
- **Connections:** each call opens a new database connection.

## Related articles

[Authentication and roles](../operations/authentication.md) · [Docker deployment](../operations/docker.md) · [Vector search](../indexes/vector.md)