Sync MCP prefix environment variable changes PR with 2.x branch

.changes/unreleased/Minor-20260818-110500.yaml

@@ -0,0 +1,46 @@
+kind: Minor
+body: |
+  Deprecates the existing configuration environment variables and `--neo4j-*` CLI flags in favor of consistently scoped `NEO4J_MCP_*` environment variables and concise CLI flags.
+
+  Deprecated environment variables:
+
+  | Deprecated | Canonical replacement |
+  | --- | --- |
+  | `NEO4J_URI` | `NEO4J_MCP_URI` |
+  | `NEO4J_USERNAME` | `NEO4J_MCP_USERNAME` |
+  | `NEO4J_PASSWORD` | `NEO4J_MCP_PASSWORD` |
+  | `NEO4J_DATABASE` | `NEO4J_MCP_DATABASE` |
+  | `NEO4J_READ_ONLY` | `NEO4J_MCP_READ_ONLY` |
+  | `NEO4J_TELEMETRY` | `NEO4J_MCP_TELEMETRY` |
+  | `NEO4J_LOG_LEVEL` | `NEO4J_MCP_LOG_LEVEL` |
+  | `NEO4J_LOG_FORMAT` | `NEO4J_MCP_LOG_FORMAT` |
+  | `NEO4J_SCHEMA_SAMPLE_SIZE` | `NEO4J_MCP_SCHEMA_SAMPLE_SIZE` |
+  | `NEO4J_TRANSPORT_MODE` | `NEO4J_MCP_TRANSPORT_MODE` |
+  | `NEO4J_MCP_TRANSPORT` | `NEO4J_MCP_TRANSPORT_MODE` |
+  | `NEO4J_HTTP_AUTH_HEADER_NAME` | `NEO4J_MCP_HTTP_AUTH_HEADER_NAME` |
+  | `NEO4J_HTTP_ALLOW_UNAUTHENTICATED_PING` | `NEO4J_MCP_HTTP_ALLOW_UNAUTHENTICATED_PING` |
+  | `NEO4J_HTTP_ALLOW_UNAUTHENTICATED_TOOLS_LIST` | `NEO4J_MCP_HTTP_ALLOW_UNAUTHENTICATED_TOOLS_LIST` |
+
+  Deprecated CLI flags:
+
+  | Deprecated | Canonical replacement |
+  | --- | --- |
+  | `--neo4j-uri` | `--uri` |
+  | `--neo4j-username` | `--username` |
+  | `--neo4j-password` | `--password` |
+  | `--neo4j-database` | `--database` |
+  | `--neo4j-read-only` | `--read-only` |
+  | `--neo4j-telemetry` | `--telemetry` |
+  | `--neo4j-schema-sample-size` | `--schema-sample-size` |
+  | `--neo4j-transport-mode` | `--transport-mode` |
+  | `--neo4j-http-port` | `--http-port` |
+  | `--neo4j-http-host` | `--http-host` |
+  | `--neo4j-http-allowed-origins` | `--http-allowed-origins` |
+  | `--neo4j-http-tls-enabled` | `--http-tls-enabled` |
+  | `--neo4j-http-tls-cert-file` | `--http-tls-cert-file` |
+  | `--neo4j-http-tls-key-file` | `--http-tls-key-file` |
+  | `--neo4j-http-auth-header-name` | `--http-auth-header-name` |
+  | `--neo4j-http-allow-unauthenticated-ping` | `--http-allow-unauthenticated-ping` |
+  | `--neo4j-http-allow-unauthenticated-tools-list` | `--http-allow-unauthenticated-tools-list` |
+
+time: 2026-08-18T11:05:00+01:00

.env.example

@@ -4,7 +4,7 @@
 # These environment variables are loaded automatically by Taskfile (dotenv).
 # Only used when running commands through `task`.
 
-NEO4J_URI=bolt://localhost:7687
-NEO4J_USERNAME=neo4j
-NEO4J_PASSWORD=password
-NEO4J_DATABASE=neo4j
+NEO4J_MCP_URI=bolt://localhost:7687
+NEO4J_MCP_USERNAME=neo4j
+NEO4J_MCP_PASSWORD=password
+NEO4J_MCP_DATABASE=neo4j

.github/workflows/docker-release-alpha.yml

@@ -19,7 +19,7 @@ jobs:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4
+        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4
 
       - name: Log in to DockerHub
         uses: docker/login-action@abd2ef45e78c5afb21d64d4ca52ee8550d9572c7 # v4

.github/workflows/docker-release.yml

@@ -44,7 +44,7 @@ jobs:
           platforms: arm64
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4
+        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4
 
       - name: Log in to DockerHub
         uses: docker/login-action@abd2ef45e78c5afb21d64d4ca52ee8550d9572c7 # v4

CONTRIBUTING.md

@@ -39,6 +39,18 @@ go run ./cmd/neo4j-mcp
 go install -C cmd/neo4j-mcp
 ```
 
+## User-facing configuration naming (environment variables and CLI args)
+
+When adding a user-facing configuration setting:
+
+- Prefix environment variables with `NEO4J_MCP_` and use uppercase snake case, for example `NEO4J_MCP_SCHEMA_SAMPLE_SIZE`.
+- Keep CLI flags short and use kebab case. Avoid redundant `neo4j-` or `mcp-` prefixes because the executable already provides that scope, for example `--schema-sample-size`.
+- Keep the environment variable and CLI flag names aligned, and update their help text, tests, examples, and changelog together.
+
+Note:
+These conventions apply only to environment variables and CLI flags exposed as supported configuration for users of the Neo4j MCP server. Do not add the `MCP` scope to variables consumed by internal development, test, build, or CI helpers, because those variables configure the helper rather than the MCP server. 
+Internal tooling may intentionally use organization-wide names such as `NEO4J_URI`, `NEO4J_USERNAME`, and `NEO4J_PASSWORD` for the Neo4j instance used in CI, alongside controls such as `NEO4J_IMAGE` and `USE_CONTAINER`. The unscoped connection variables are deprecated only when consumed as user-facing MCP server configuration.
+
 ## Mocks
 
 We rely on interface-based dependency injection plus generated mocks (gomock) so tests run without a live Neo4j instance.
@@ -215,12 +227,6 @@ When adding new database operations:
 - Tests failing unexpectedly → regenerate mocks, verify env vars, rerun full test suite.
 - Dependency/build issues → `go mod tidy`.
 
-## Update the MCPB bundle (for Claude Desktop)
-
-If your changes impact the end-user configuration (e.g., adding new environment variables or modifying tool definitions), you must update the `manifest.json` file. This ensures that integrations like Claude Desktop are aware of the new server configuration.
-
-For more information refer to the dedicated guide: [the MCPB build documentation](https://neo4j.com/docs/mcp/current/installation#mcpb).
-
 ### Getting help
 
 - Check existing [GitHub Issues](https://github.com/neo4j/mcp/issues)

README.md

@@ -15,8 +15,8 @@ By implementing the Model Context Protocol (MCP), it acts as a bridge between an
 ## Tools
 
 - `get-schema` — introspect labels, relationship types, property keys
-- `read-cypher` — execute read-only Cypher queries
-- `write-cypher` — execute write Cypher queries (disabled if `NEO4J_READ_ONLY=true`)
+- `read-cypher` — execute read-only Cypher queries that do not modify database data, enforced via `EXPLAIN` and Neo4j's query-type classification. **Note:** custom procedures or functions incorrectly classified as read-only by Neo4j may bypass this check; ensuring correct classification is the responsibility of the procedure/function maintainer.
+- `write-cypher` — execute write Cypher queries (disabled if `NEO4J_MCP_READ_ONLY=true`)
 - `list-gds-procedures` — list available GDS procedures
 
 ## Migrating from v1 to v2
@@ -74,10 +74,10 @@ Create / edit `mcp.json`:
       "command": "python",
       "args": ["-m", "neo4j_mcp_server"],
       "env": {
-        "NEO4J_URI": "bolt://localhost:7687",
-        "NEO4J_USERNAME": "neo4j",
-        "NEO4J_PASSWORD": "password",
-        "NEO4J_DATABASE": "neo4j"
+        "NEO4J_MCP_URI": "bolt://localhost:7687",
+        "NEO4J_MCP_USERNAME": "neo4j",
+        "NEO4J_MCP_PASSWORD": "password",
+        "NEO4J_MCP_DATABASE": "neo4j",
       }
     }
   }

cmd/neo4j-mcp/main.go

@@ -95,7 +95,7 @@ func main() {
 	if cfg.Telemetry && Version != "development" {
 		anService.Enable()
 		log.Println("Telemetry is enabled to help us improve the product by collecting anonymous usage data such as: tools being used, the operating system, and CPU architecture.")
-		log.Println("To disable telemetry, set the NEO4J_TELEMETRY environment variable to \"false\".")
+		log.Println("To disable telemetry, set the NEO4J_MCP_TELEMETRY environment variable to \"false\" or use --telemetry false.")
 	} else {
 		log.Println("Telemetry disabled.")
 		anService.Disable()

docs/TLS_SETUP.md

@@ -45,18 +45,20 @@ openssl req -x509 -newkey rsa:4096 \
 ```bash
 # Default port 443 when TLS is enabled
 ./bin/neo4j-mcp \
-  --neo4j-transport-mode http \
-  --neo4j-http-tls-enabled true \
-  --neo4j-http-tls-cert-file cert.pem \
-  --neo4j-http-tls-key-file key.pem
+  --uri bolt://localhost:7687 \
+  --transport-mode http \
+  --http-tls-enabled true \
+  --http-tls-cert-file cert.pem \
+  --http-tls-key-file key.pem
 
 # Or specify a custom port like 8443
 ./bin/neo4j-mcp \
-  --neo4j-transport-mode http \
-  --neo4j-http-port 8443 \
-  --neo4j-http-tls-enabled true \
-  --neo4j-http-tls-cert-file cert.pem \
-  --neo4j-http-tls-key-file key.pem
+  --uri bolt://localhost:7687 \
+  --transport-mode http \
+  --http-port 8443 \
+  --http-tls-enabled true \
+  --http-tls-cert-file cert.pem \
+  --http-tls-key-file key.pem
 ```
 
 
@@ -149,4 +151,4 @@ openssl s_client -connect 127.0.0.1:8443 </dev/null 2>/dev/null | grep "Cipher"
 - **`-k` flag**: Skips certificate verification (needed for self-signed certificates)
 - **Basic Auth**: All requests require `-u username:password`
 - **Content-Type**: MCP requests need `Content-Type: application/json` header
-- **Port**: Default port is 443 when TLS is enabled, 80 when TLS is disabled (configurable via `--neo4j-http-port` or `NEO4J_MCP_HTTP_PORT`)
+- **Port**: Default port is 443 when TLS is enabled, 80 when TLS is disabled (configurable via `--http-port` or `NEO4J_MCP_HTTP_PORT`)