{ "markdown": "\n\n# Neo4j MCP Canary — _The canary goes first so the rest of us know what's coming_\n\nNeo4j MCP Canary is a fast-moving, experimental release of the Neo4j MCP server for customers who want to explore emerging capabilities before they are considered for the official server.\n\nBuilt on the source of the official Model Context Protocol (MCP) server for Neo4j, this variant is here for exploring potential new capabilities with experimentation.\n\nAs it is a labs project, be aware that:\n\n- It is not supported.\n- It may contain breaking changes between its own releases and with the official Neo4j MCP server.\n- It should be tested before using.\n\nYou are welcome to contribute — we are always open to new ideas, especially in this canary channel.\n\n> Do not assume the canary will work for your situation. Test first.\n\n## Prerequisites\n\n- A running Neo4j database instance; options include [Aura](https://neo4j.com/product/auradb/), [Neo4j Desktop](https://neo4j.com/download/), or [self-managed](https://neo4j.com/deployment-center/#gdb-tab).\n- APOC plugin installed in the Neo4j instance (required — `get-schema` uses `apoc.meta.schema`).\n- Any MCP-compatible client (e.g. [VSCode](https://code.visualstudio.com/) with [MCP support](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)).\n\n> **⚠️ Known Issue**: Neo4j **5.26.18** has a bug in APOC that causes the `get-schema` tool to fail. This is fixed in **5.26.19** and above. If you're on 5.26.18, please upgrade. See [#136](https://github.com/neo4j-labs/neo4j-mcp-canary/issues/136) for details.\n\n## Startup Checks & Adaptive Operation\n\nThe server performs several pre-flight checks at startup to ensure your environment is correctly configured.\n\n**STDIO Mode — Mandatory Requirements**\nIn STDIO mode, the server verifies the following. If any check fails (e.g. invalid configuration, incorrect credentials, missing APOC), the server will not start:\n\n- A valid connection to your Neo4j instance.\n- The ability to execute queries.\n- The presence of the APOC plugin.\n\n**HTTP Mode — Verification Skipped**\nIn HTTP mode, startup verification checks are skipped because credentials come from per-request auth headers. The server starts immediately without connecting to Neo4j. The one exception is [Query API mode](#connecting-via-the-query-api-instead-of-bolt): its minimum-version check runs at startup in both transport modes, since it only needs an unauthenticated GET and doesn't depend on per-request credentials.\n\n**Optional Requirements**\nIf an optional dependency is missing, the server starts in adaptive mode. For instance, if the Graph Data Science (GDS) library is not detected, the server still launches but automatically disables GDS-dependent tools such as `list-gds-procedures`. All other tools remain available.\n\n## Installation (Binary)\n\nReleases: https://github.com/neo4j-labs/neo4j-mcp-canary/releases\n\n1. Download the archive for your OS/arch.\n2. Extract and place `neo4j-mcp-canary` on your `PATH`.\n\nMac / Linux:\n\n> On Mac, you may be warned the first time you try to run the binary. If so, approve it via **System Settings → Privacy & Security**.\n\n```bash\nchmod +x neo4j-mcp-canary\nsudo mv neo4j-mcp-canary /usr/local/bin/\n```\n\nWindows (PowerShell / cmd):\n\n```powershell\nmove neo4j-mcp-canary.exe C:\\Windows\\System32\n```\n\nVerify the installation:\n\n```bash\nneo4j-mcp-canary -v\n```\n\nShould print the installed version.\n\n## Building from Source\n\nRequires Go 1.25.3+ (see `go.mod`).\n\nBuild for your current platform with [Task](https://taskfile.dev):\n\n```bash\ntask build\n```\n\nThis produces `bin/neo4j-mcp-canary`. Without Task, the equivalent is:\n\n```bash\ngo build -C cmd/neo4j-mcp -o ../../bin/\n```\n\n### Cross-compiling for macOS / Linux\n\nCross-compile by setting `GOOS`/`GOARCH` and disabling cgo (the codebase is\npure Go, so `CGO_ENABLED=0` produces a fully static binary with no runtime\ndependencies on the target machine):\n\n```bash\nCGO_ENABLED=0 GOOS=darwin GOARCH=amd64 go build -C cmd/neo4j-mcp -o ../../dist/neo4j-mcp-canary_darwin_amd64\nCGO_ENABLED=0 GOOS=darwin GOARCH=arm64 go build -C cmd/neo4j-mcp -o ../../dist/neo4j-mcp-canary_darwin_arm64\nCGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -C cmd/neo4j-mcp -o ../../dist/neo4j-mcp-canary_linux_amd64\nCGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -C cmd/neo4j-mcp -o ../../dist/neo4j-mcp-canary_linux_arm64\n```\n\nTo stamp a version into the binary (`-v` / `--version`), pass an `ldflags`\noverride — this is what the release pipeline does for tagged builds:\n\n```bash\ngo build -C cmd/neo4j-mcp -o ../../dist/neo4j-mcp-canary \\\n -ldflags \"-X 'main.Version=$(git rev-parse --short HEAD)'\"\n```\n\nWithout it, `Version` defaults to `\"development\"`, which also disables\ntelemetry regardless of `NEO4J_TELEMETRY` (see [Telemetry](#telemetry)).\n\nOfficial multi-platform release archives (including Windows) are built by\n[GoReleaser](https://goreleaser.com/) per `.goreleaser.yaml` — see\n[Installation (Binary)](#installation-binary) to download those instead of\nbuilding locally.\n\n## Transport Modes\n\nThe Neo4j MCP Canary server supports two transport modes:\n\n- **STDIO** (default): Standard MCP communication via stdin/stdout for desktop clients (Claude Desktop, VSCode).\n- **HTTP**: RESTful HTTP server with per-request Bearer token or Basic Authentication for web-based clients and multi-tenant scenarios. Where the standard `Authorization` header cannot be used, a custom header name can be configured.\n\n### Key Differences\n\n| Aspect | STDIO | HTTP |\n| -------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------- |\n| Startup verification | Required — server verifies APOC, connectivity, queries | Skipped — server starts immediately |\n| Credentials | Set via environment variables | Per-request via Bearer token or Basic Auth headers |\n| Telemetry | Collects Neo4j version, edition, Cypher version at startup | Reports `unknown-http-mode` — per-request credentials prevent introspection |\n\nSee the [Client Setup Guide](docs/CLIENT_SETUP.md) for configuration instructions for both modes.\n\n## Unauthenticated MCP Client Requests\n\nBy default, there are four requests a MCP client can send without authentication when using HTTP(S) transport. Some integrations (AWS AgentCore, AWS Gateway, etc.) rely on this as an initial health-check mechanism:\n\n- `ping`\n- `initialize`\n- `tools/list`\n- `notifications/initialize`\n\nIf you do not need these, enforce authentication individually via the variables below.\n\n| Environment Variable | CLI Flag | Default | Purpose |\n| ------------------------------------------------------------ | ---------------------------------------------------------- | ------- | -------------------------------------------------- |\n| `NEO4J_HTTP_ALLOW_UNAUTHENTICATED_PING` | `--neo4j-http-allow-unauthenticated-ping` | `true` | Allow unauthenticated ping health checks |\n| `NEO4J_HTTP_ALLOW_UNAUTHENTICATED_TOOLS_LIST` | `--neo4j-http-allow-unauthenticated-tools-list` | `true` | Allow unauthenticated tool listing |\n| `NEO4J_HTTP_ALLOW_UNAUTHENTICATED_INITIALIZE` | `--neo4j-http-allow-unauthenticated-initialize` | `true` | Allow unauthenticated initialize |\n| `NEO4J_HTTP_ALLOW_UNAUTHENTICATED_NOTIFICATIONS_INITIALIZE` | `--neo4j-http-allow-unauthenticated-notifications-initialize` | `true` | Allow unauthenticated `notifications/initialize` |\n\n## TLS/HTTPS Configuration\n\nWhen using HTTP transport, enable TLS for secure communication via the variables below.\n\n| Environment Variable | CLI Flag | Default | Purpose |\n| ------------------------------- | ------------------------------ | ---------------------------------------- | ----------------------------------------- |\n| `NEO4J_MCP_HTTP_TLS_ENABLED` | `--neo4j-http-tls-enabled` | `false` | Enable TLS/HTTPS |\n| `NEO4J_MCP_HTTP_TLS_CERT_FILE` | `--neo4j-http-tls-cert-file` | — | Path to TLS certificate (required w/ TLS) |\n| `NEO4J_MCP_HTTP_TLS_KEY_FILE` | `--neo4j-http-tls-key-file` | — | Path to TLS private key (required w/ TLS) |\n| `NEO4J_MCP_HTTP_PORT` | `--neo4j-http-port` | `443` with TLS, `80` without | HTTP server port |\n| `NEO4J_HTTP_AUTH_HEADER_NAME` | `--neo4j-http-auth-header-name`| `Authorization` | Header name to read credentials from |\n\n**Security Configuration**\n\n- **Minimum TLS Version:** TLS 1.2 (TLS 1.3 negotiated when available)\n- **Cipher Suites:** Go's secure default cipher suites\n- **Default Port:** Automatically uses 443 when TLS is enabled\n\n**Example**\n\n```bash\nexport NEO4J_URI=\"bolt://localhost:7687\"\nexport NEO4J_TRANSPORT_MODE=\"http\"\nexport NEO4J_MCP_HTTP_TLS_ENABLED=\"true\"\nexport NEO4J_MCP_HTTP_TLS_CERT_FILE=\"/path/to/cert.pem\"\nexport NEO4J_MCP_HTTP_TLS_KEY_FILE=\"/path/to/key.pem\"\n\nneo4j-mcp-canary\n# Server listens on https://127.0.0.1:443 by default\n```\n\n**Production Usage:** use certificates from a trusted CA (Let's Encrypt, your organisation's CA, etc.) for production deployments.\n\nFor detailed instructions on certificate generation, TLS testing, and production deployment, see [CONTRIBUTING.md](CONTRIBUTING.md#tlshttps-configuration).\n\n## Configuration Options\n\nThe `neo4j-mcp-canary` server is configured via environment variables, CLI flags, and/or an optional config file. **CLI flags take precedence over environment variables, which take precedence over an optional config file.**\n\n### Environment Variables\n\nCore connection and behaviour:\n\n| Environment Variable | Default | Purpose |\n| --------------------------------- | --------- | ------------------------------------------------------------------------ |\n| `NEO4J_URI` | — | Neo4j connection URI (required) |\n| `NEO4J_USERNAME` | — | Database username (required in STDIO mode; must be unset in HTTP mode) |\n| `NEO4J_PASSWORD` | — | Database password (required in STDIO mode; must be unset in HTTP mode) |\n| `NEO4J_DATABASE` | `neo4j` | Database name |\n| `NEO4J_READ_ONLY` | `false` | When `true`, the `write-cypher` tool is not registered |\n| `NEO4J_TELEMETRY` | `true` | Enable/disable anonymous telemetry |\n| `NEO4J_SCHEMA_SAMPLE_SIZE` | `1000` | Nodes per label APOC examines when inferring schema |\n| `NEO4J_LOG_LEVEL` | `info` | `debug`, `info`, `notice`, `warning`, `error`, `critical`, `alert`, `emergency` |\n| `NEO4J_LOG_FORMAT` | `text` | `text` or `json` |\n| `NEO4J_OUTPUT_FORMAT` | `json` | Tool response format sent to the LLM client: `json` or `toon` |\n| `NEO4J_TRANSPORT_MODE` | `stdio` | `stdio` or `http` (supersedes the deprecated `NEO4J_MCP_TRANSPORT`) |\n\n#### Connecting via the Query API instead of Bolt\n\n`NEO4J_URI`'s scheme determines which wire protocol the server uses to talk\nto Neo4j — no separate flag is needed:\n\n- `bolt://`, `bolt+s://`, `neo4j://`, `neo4j+s://`, etc. → the Bolt driver (default, unchanged behaviour).\n- `http://` or `https://` → the [Neo4j Query API](https://neo4j.com/docs/query-api/current/), Neo4j's HTTP-based query interface. Useful for deployments that only expose HTTP or otherwise prefer not to use Bolt.\n\nQuery API mode requires Neo4j **2026.07** or newer (calendar-versioned\nreleases) or **5.27-aura** or newer (classic-versioned Aura releases only —\na bare classic version with no `-aura` suffix is not supported). This floor\nis one release past the Query API's own general availability (2026.06):\nread-cypher's write-query rejection depends on the `queryType` field in the\nquery response, which Neo4j only introduced in 2026.07 — a 2026.06 server\nhas no reliable signal to classify a query as read-only before running it.\nThe server checks the connected instance's reported version against this\nfloor at startup (via an unauthenticated GET to the base URI) and refuses\nto start if it's too old, with an error naming the version it found and the\nminimum required.\n\n`NEO4J_USERNAME`/`NEO4J_PASSWORD` and per-request Basic/Bearer credentials\nwork the same way in Query API mode as they do for Bolt — see\n[Transport Modes](#transport-modes) and\n[Authentication Methods (HTTP Mode)](#authentication-methods-http-mode).\n\nCypher execution safeguards (see [Cypher Execution Safeguards](#cypher-execution-safeguards)):\n\n| Environment Variable | Default | Purpose |\n| ----------------------------------- | ----------- | ----------------------------------------------------------------------- |\n| `NEO4J_CYPHER_MAX_ROWS` | `1000` | Per-call row cap on `read-cypher` / `write-cypher`; `0` disables |\n| `NEO4J_CYPHER_MAX_BYTES` | `900000` | Per-call byte cap (~900 KB) on the response envelope; `0` disables |\n| `NEO4J_CYPHER_TIMEOUT` | `30` | Execution timeout in seconds; `0` disables |\n| `NEO4J_CYPHER_MAX_ESTIMATED_ROWS` | `1000000` | EXPLAIN-time planner estimate above which `read-cypher` refuses a query; `0` disables |\n\nHTTP transport, TLS, and auth (see tables above).\n\n### CLI Flags\n\nYou can override any environment variable using CLI flags:\n\n```bash\nneo4j-mcp-canary \\\n --neo4j-uri \"bolt://localhost:7687\" \\\n --neo4j-username \"neo4j\" \\\n --neo4j-password \"password\" \\\n --neo4j-database \"neo4j\" \\\n --neo4j-read-only false \\\n --neo4j-telemetry true\n```\n\nAvailable flags:\n\n**Connection & behaviour**\n\n- `--neo4j-uri` — overrides `NEO4J_URI`\n- `--neo4j-username` — overrides `NEO4J_USERNAME`\n- `--neo4j-password` — overrides `NEO4J_PASSWORD`\n- `--neo4j-database` — overrides `NEO4J_DATABASE`\n- `--neo4j-read-only` — overrides `NEO4J_READ_ONLY` (`true` / `false`)\n- `--neo4j-telemetry` — overrides `NEO4J_TELEMETRY` (`true` / `false`)\n- `--neo4j-schema-sample-size` — overrides `NEO4J_SCHEMA_SAMPLE_SIZE`\n- `--neo4j-output-format` — overrides `NEO4J_OUTPUT_FORMAT` (`json` / `toon`)\n\n**Cypher execution safeguards**\n\n- `--neo4j-cypher-max-rows` — overrides `NEO4J_CYPHER_MAX_ROWS` (`0` disables)\n- `--neo4j-cypher-max-bytes` — overrides `NEO4J_CYPHER_MAX_BYTES` (`0` disables)\n- `--neo4j-cypher-timeout` — overrides `NEO4J_CYPHER_TIMEOUT` (seconds; `0` disables)\n- `--neo4j-cypher-max-estimated-rows` — overrides `NEO4J_CYPHER_MAX_ESTIMATED_ROWS` (`0` disables)\n\n**Transport / HTTP**\n\n- `--neo4j-transport-mode` — `stdio` or `http`\n- `--neo4j-http-host` — overrides `NEO4J_MCP_HTTP_HOST`\n- `--neo4j-http-port` — overrides `NEO4J_MCP_HTTP_PORT`\n- `--neo4j-http-allowed-origins` — overrides `NEO4J_MCP_HTTP_ALLOWED_ORIGINS` (comma-separated CORS origins)\n- `--neo4j-http-tls-enabled` — overrides `NEO4J_MCP_HTTP_TLS_ENABLED`\n- `--neo4j-http-tls-cert-file` — overrides `NEO4J_MCP_HTTP_TLS_CERT_FILE`\n- `--neo4j-http-tls-key-file` — overrides `NEO4J_MCP_HTTP_TLS_KEY_FILE`\n- `--neo4j-http-auth-header-name` — overrides `NEO4J_HTTP_AUTH_HEADER_NAME`\n- `--neo4j-http-allow-unauthenticated-ping` — overrides `NEO4J_HTTP_ALLOW_UNAUTHENTICATED_PING`\n- `--neo4j-http-allow-unauthenticated-tools-list` — overrides `NEO4J_HTTP_ALLOW_UNAUTHENTICATED_TOOLS_LIST`\n- `--neo4j-http-allow-unauthenticated-initialize` — overrides `NEO4J_HTTP_ALLOW_UNAUTHENTICATED_INITIALIZE`\n- `--neo4j-http-allow-unauthenticated-notifications-initialize` — overrides `NEO4J_HTTP_ALLOW_UNAUTHENTICATED_NOTIFICATIONS_INITIALIZE`\n\nRun `neo4j-mcp-canary --help` to see the complete list with descriptions.\n\n### Configuration File\n\nAs a lowest-priority alternative to environment variables, `neo4j-mcp-canary` can read configuration from an optional JSON or YAML file:\n\n```bash\nneo4j-mcp-canary --config-file /etc/neo4j-mcp/config.yaml\n# or\nNEO4J_CONFIG_FILE=/etc/neo4j-mcp/config.yaml neo4j-mcp-canary\n```\n\nKeys are the lower-cased form of the environment variable they correspond to:\n\n```yaml\nneo4j_uri: bolt://localhost:7687\nneo4j_username: neo4j\nneo4j_password: password\nneo4j_read_only: false\nneo4j_transport_mode: http\nneo4j_http_tls_enabled: true\nneo4j_cypher_max_rows: 500\n```\n\nThe equivalent JSON is also accepted (`.json` extension). Only scalar values (strings, numbers, booleans) are supported — a nested object or list is a startup error. Values from CLI flags or environment variables always take precedence over the config file; a `--config-file` that fails to read or parse is a startup error.\n\nAdding a new configuration parameter to the server (env var + CLI flag + config-file key, all at once) means adding one entry to the `fields` slice in [`internal/config/schema.go`](internal/config/schema.go) — see that file's doc comments for the shape.\n\n### Response Format (JSON vs TOON)\n\nTool responses (`read-cypher`, `write-cypher`, `get-schema`, `list-gds-procedures`) are rendered as JSON by default. Set `NEO4J_OUTPUT_FORMAT` (or `--neo4j-output-format`) to `toon` to render them as [TOON](https://github.com/toon-format/toon-go) (Token-Oriented Object Notation) instead — a compact, still human-readable format that cuts LLM token usage versus JSON, especially for the tabular row shapes these tools return:\n\n```bash\nneo4j-mcp-canary --neo4j-output-format toon\n# or\nNEO4J_OUTPUT_FORMAT=toon neo4j-mcp-canary\n```\n\nA `read-cypher` result as JSON:\n\n```json\n{\n \"rows\": [\n { \"name\": \"Alice\", \"age\": 30 },\n { \"name\": \"Bob\", \"age\": 25 }\n ],\n \"rowCount\": 2,\n \"truncated\": false\n}\n```\n\nThe same result as TOON:\n\n```\nrowCount: 2\nrows[2]{age,name}:\n 30,Alice\n 25,Bob\ntruncated: false\n```\n\nAn invalid value falls back to `json` with a warning on stderr, the same way `NEO4J_LOG_FORMAT` does.\n\n## Cypher Execution Safeguards\n\n`read-cypher` and `write-cypher` are protected by four layered safeguards that together keep an overeager LLM from hanging the MCP transport or exhausting the database. Each layer catches a different failure mode; together they act as defence in depth.\n\n| Layer | Setting | Default | When it fires |\n| --------------------- | --------------------------------- | ----------- | ------------------------------------------------------- |\n| Planner estimate | `NEO4J_CYPHER_MAX_ESTIMATED_ROWS` | `1000000` | Before execution — query refused if the planner's root `EstimatedRows` exceeds the threshold |\n| Execution timeout | `NEO4J_CYPHER_TIMEOUT` | `30s` | During execution — query cancelled after the deadline |\n| Row cap | `NEO4J_CYPHER_MAX_ROWS` | `1000` | During streaming — response truncated at the row limit |\n| Byte cap | `NEO4J_CYPHER_MAX_BYTES` | `900000` | During streaming — response truncated when the envelope grows past ~900 KB |\n\nSet any value to `0` to disable that specific layer.\n\n### Truncation envelope\n\nWhen either the row cap or the byte cap fires, the tool returns the rows it has already collected plus a truncation envelope:\n\n```json\n{\n \"rows\": [ /* ... */ ],\n \"rowCount\": 1000,\n \"truncated\": true,\n \"truncationReason\": \"rows\",\n \"maxRows\": 1000,\n \"hint\": \"Results were truncated at 1000 rows. Add a LIMIT clause or a more selective filter and retry for a complete result.\"\n}\n```\n\nCallers (including LLM agents) can read `truncated` / `truncationReason` / `hint` programmatically and retry with a tighter query rather than seeing an opaque transport-level failure.\n\n### Timeout and cancellation errors\n\nWhen `NEO4J_CYPHER_TIMEOUT` fires, the tool returns a classified error that names the configured limit and offers tool-specific remediation (bound variable-length patterns, add `WHERE` filters, or `LIMIT` for `read-cypher`; reduce batch size, narrow the `MATCH`, or use `apoc.periodic.iterate` for `write-cypher`). Caller cancellation (as distinct from timeout) surfaces as a concise `cancelled` message without remediation guidance.\n\n### Planner estimate refusal\n\nThe planner-estimate guard reads the root `EstimatedRows` of an `EXPLAIN` plan before the query runs. Because Neo4j folds `LIMIT` into the root estimate, a legitimate `MATCH ... LIMIT 100` query passes cleanly with an estimate of ~100, while a bare `MATCH` on a multi-million-row label is refused before it starts.\n\n## Authentication Methods (HTTP Mode)\n\nWhen using HTTP transport mode, the Neo4j MCP Canary server supports two authentication methods to accommodate different deployment scenarios.\n\n### Bearer Token Authentication\n\nBearer token authentication enables seamless integration with **Neo4j Enterprise Edition** and **Neo4j Aura** environments that use SSO/OAuth/OIDC for identity management. This method is ideal for:\n\n- Enterprise deployments with centralised identity providers (Okta, Azure AD, etc.)\n- Neo4j Aura databases configured with SSO\n- Organisations requiring OAuth 2.0 compliance\n- Multi-factor authentication scenarios\n\n**Example:**\n\n```bash\ncurl -X POST http://localhost:8080/mcp \\\n -H \"Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"jsonrpc\":\"2.0\",\"method\":\"tools/list\",\"id\":1}'\n```\n\nThe bearer token is obtained from your identity provider and passed to Neo4j for authentication. The MCP server acts as a pass-through, forwarding the token to Neo4j's authentication system.\n\n### Basic Authentication\n\nTraditional username/password authentication suitable for:\n\n- Neo4j Community Edition\n- Development and testing environments\n- Direct database credentials without SSO\n\n**Example:**\n\n```bash\ncurl -X POST http://localhost:8080/mcp \\\n -u neo4j:password \\\n -H \"Content-Type: application/json\" \\\n -d '{\"jsonrpc\":\"2.0\",\"method\":\"tools/list\",\"id\":1}'\n```\n\n## Client Configuration\n\nTo configure MCP clients (VSCode, Claude Desktop, etc.) to use the Neo4j MCP Canary server, see:\n\n📘 **[Client Setup Guide](docs/CLIENT_SETUP.md)** – Complete configuration for STDIO and HTTP modes.\n\n## Tools & Usage\n\nProvided tools:\n\n| Tool | ReadOnly | Purpose | Notes |\n| --------------------- | -------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |\n| `get-schema` | `true` | Introspect labels, relationship types, property keys | Uses `apoc.meta.schema`. Sampling controlled by `NEO4J_SCHEMA_SAMPLE_SIZE`. |\n| `read-cypher` | `true` | Execute arbitrary read-only Cypher | Rejects writes, schema/admin DDL, `EXPLAIN`, and `PROFILE`. See [Cypher Execution Safeguards](#cypher-execution-safeguards). |\n| `write-cypher` | `false` | Execute arbitrary Cypher (write mode) | **Caution:** LLM-generated queries can cause harm. Use only in development environments. Not registered when `NEO4J_READ_ONLY=true`. |\n| `list-gds-procedures` | `true` | List GDS procedures available in the Neo4j instance | Disabled automatically if GDS is not installed. |\n| `give-feedback` | `true` | Submit free-text feedback about the MCP server itself | For feedback on the server (tools, behaviour, docs), not on Cypher/database issues. Limited to 300 characters. See [Feedback](#feedback). |\n\n### Read-only mode flag\n\nEnable read-only mode by setting `NEO4J_READ_ONLY=true` (accepted: `true` / `false`; default: `false`).\n\nYou can also use the CLI flag:\n\n```bash\nneo4j-mcp-canary \\\n --neo4j-uri \"bolt://localhost:7687\" \\\n --neo4j-username \"neo4j\" \\\n --neo4j-password \"password\" \\\n --neo4j-read-only true\n```\n\nWhen enabled, write tools (e.g. `write-cypher`) are not exposed to clients.\n\n### Query classification\n\n`read-cypher` prepends `EXPLAIN` to the caller's query to classify it as read or write before executing. Consequences:\n\n- **Write operations** (`CREATE`, `MERGE`, `DELETE`, `SET`, `REMOVE`, ...) — rejected with a message directing the caller to `write-cypher`.\n- **Schema/DDL operations** (`CREATE INDEX`, `DROP CONSTRAINT`, ...) — rejected, same message.\n- **Admin commands** (`SHOW USERS`, `SHOW DATABASES`, ...) — rejected, same message.\n- **`EXPLAIN` prefix** — rejected with a dedicated message noting that runaway-query protection is already provided by the planner-estimate guard and the execution timeout, and pointing at `write-cypher` for a profiled plan.\n- **`PROFILE` prefix** — rejected with a message directing the caller to `write-cypher`.\n- **Read-only `SHOW` commands** (`SHOW INDEXES`, `SHOW CONSTRAINTS`, `SHOW PROCEDURES`, `SHOW FUNCTIONS`) — allowed.\n\nIf the wrapped query produces a syntax error, the server strips the internal `EXPLAIN ` prefix from the error text, column offset, and caret alignment before returning — so the error reads as if the caller's original query had been submitted directly.\n\n### Response format for `read-cypher` / `write-cypher`\n\nDriver types are wrapped in camelCase JSON shapes matching Cypher conventions:\n\n- **Nodes:** `{ \"elementId\": \"...\", \"labels\": [...], \"properties\": {...} }`\n- **Relationships:** `{ \"elementId\": \"...\", \"startElementId\": \"...\", \"endElementId\": \"...\", \"type\": \"...\", \"properties\": {...} }`\n- **Paths:** `{ \"nodes\": [...], \"relationships\": [...] }`\n- **Points:** `{ \"x\": ..., \"y\": ..., \"srid\": ... }` (and `z` for 3D)\n- **Date / Time / DateTime / LocalTime / LocalDateTime / Duration:** ISO 8601 strings\n\nDeprecated numeric `id` / `startId` / `endId` identifiers are **not** surfaced — `elementId` / `startElementId` / `endElementId` are the only identifiers returned.\n\n### Feedback\n\n`give-feedback` lets an agent submit free-text feedback about the MCP server itself — positive or negative — as a single `feedback` string argument, capped at 300 characters (enforced both in the advertised tool schema and by the handler, in case a client doesn't validate the schema before sending). It's for feedback on the server's tools, behaviour, or documentation, not for reporting Cypher/database errors.\n\nFeedback is sent as a Mixpanel event alongside the server's other telemetry, so it is only recorded when telemetry is enabled (see [Telemetry](#telemetry)) — the tool call itself always succeeds either way.\n\n## Usage Guidance\n\nLessons from canary testing that help an LLM (or a human) get the most out of `read-cypher`:\n\n1. **Aggregate in the database.** `count`, `sum`, `avg`, `collect`, `reduce`, `percentileCont`, `stDev`, and similar reductions collapse to one row and are unaffected by the row cap. A query like `UNWIND range(1, 50000) AS i RETURN sum(i)` runs cleanly; the same range streamed row-by-row is truncated at the row cap.\n2. **Always use `LIMIT` for exploratory queries.** The row cap will truncate bare `MATCH` returns; the truncation envelope's `hint` field will tell the caller to add a `LIMIT`. Prefer a `LIMIT` you picked over one the server imposed.\n3. **Narrow the `RETURN` projection for wide nodes.** When a record carries many properties (e.g. a full Company node with 19 fields), the byte cap fires before the row cap. Return only the fields you need (`RETURN c.name, c.companyNumber`) rather than the whole node.\n4. **Use parameters, including nested maps.** Parameter placeholders (`$name`) are bound from the `params` object; nested access works (`$config.thresholds.pr`). Missing required parameters produce a clear `ParameterMissing` error; extra parameters are silently ignored.\n5. **Be explicit about types in comparisons.** Cross-type comparisons like `t.amount > \"foo\"` evaluate to null and silently filter everything out — no error, just an empty result set. Validate incoming parameter types on the caller side when the result shape surprises you.\n6. **`SHOW INDEXES` / `SHOW CONSTRAINTS` are allowed.** Useful before writing a query that depends on an index, or for debugging why a match is slow.\n7. **`EXPLAIN` and `PROFILE` are not exposed on `read-cypher`.** Runaway-query protection is already handled by the planner-estimate guard and execution timeout. If you need a profiled plan with runtime stats, use `write-cypher` with `PROFILE`.\n8. **Watch for duplicated payloads when returning paths.** `RETURN p, nodes(p), relationships(p)` triples the serialised payload. Return the path or its components, not both.\n9. **Long-running queries return a classified error.** When `NEO4J_CYPHER_TIMEOUT` fires, the error names the timeout value and suggests remediation (bound variable-length patterns, add `WHERE` filters, use `LIMIT`) instead of a raw `context deadline exceeded` from the driver.\n10. **`OPTIONAL MATCH` for missing data.** When looking up by ID where some IDs may not exist, `OPTIONAL MATCH` returns nulls for misses instead of dropping rows — better for batch lookups.\n11. **Defaults are calibrated, not arbitrary.** `1000` rows / `~900 KB` / `30s` / `1M` planner estimate cover the overwhelming majority of exploratory and production queries. Increase them for bulk export workloads; reduce them when serving high-traffic agent deployments.\n\n## Example Natural Language Prompts\n\nPrompts to try in Copilot or any other MCP client:\n\n- \"What does my Neo4j instance contain? List all node labels, relationship types, and property keys.\"\n- \"Find all Person nodes and show their top relationships, limited to 50 results.\"\n- \"What indexes and constraints exist on my database?\"\n- \"Summarise the transaction graph: total count, average amount, and the top 5 customers by PageRank.\"\n\n## Security tips\n\n- Use a restricted Neo4j user for exploration.\n- Review LLM-generated Cypher before executing it in production databases.\n- Keep `NEO4J_READ_ONLY=true` for any deployment that shouldn't mutate the graph.\n- Leave the Cypher safeguards at their defaults unless you have a specific reason to change them.\n\n## Logging\n\nThe server uses structured logging with support for multiple log levels and output formats.\n\n### Configuration\n\n**Log Level** (`NEO4J_LOG_LEVEL`, default: `info`)\n\nControls verbosity. Supports all [MCP log levels](https://modelcontextprotocol.io/specification/2025-03-26/server/utilities/logging#log-levels): `debug`, `info`, `notice`, `warning`, `error`, `critical`, `alert`, `emergency`.\n\n**Log Format** (`NEO4J_LOG_FORMAT`, default: `text`)\n\n- `text` — human-readable (default)\n- `json` — structured JSON (useful for log aggregation)\n\n## Telemetry\n\nBy default, `neo4j-mcp-canary` collects anonymous usage data to help improve the product. This includes information such as the tools being used, the operating system, and CPU architecture. No personal or sensitive information is collected.\n\nTo disable telemetry, set `NEO4J_TELEMETRY=false` (accepted: `true` / `false`; default: `true`). You can also use the `--neo4j-telemetry` CLI flag.\n\n## Documentation\n\n📘 **[Client Setup Guide](docs/CLIENT_SETUP.md)** – Configure VSCode, Claude Desktop, and other MCP clients (STDIO and HTTP modes)\n📚 **[Contributing Guide](CONTRIBUTING.md)** – Contribution workflow, development environment, mocks & testing\n\nIssues / feedback: open a GitHub issue with reproduction details (omit sensitive data).\n", "bytes": 32440, "sha": "f1068745bf496812e9bdcf8cae66e8d17f4f2be8699f065f0f45a7aff0271730", "repo_slug": "neo4j-labs/neo4j-mcp-canary", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_neo4j_labs_neo4j_mcp_canary_cc0f7596/readme" }