Skip to content

Add HTTP mode configuration and environment variables #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
keremgocen wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add HTTP mode configuration and environment variables #7

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
65eea39
add http config and new env vars
keremgocen Dec 20, 2025
50b528b
fix http mode type
keremgocen Dec 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
107 changes: 106 additions & 1 deletion modules/ROOT/pages/installation.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,8 @@ This should print the installed version.

== Configure VSCode (MCP)

=== STDIO mode configuration

Create / edit `mcp.json`:

[source, json]
Expand Down Expand Up @@ -80,6 +82,58 @@ Alternatively, you can use command-line flags in the `args` array to override en
}
----

=== HTTP mode configuration

For HTTP mode with CORS support:

[source, json]
----
{
"servers": {
"neo4j-http": {
"type": "http",
"command": "neo4j-mcp",
"env": {
"NEO4J_URI": "bolt://localhost:7687",
"NEO4J_MCP_TRANSPORT": "http",
"NEO4J_MCP_HTTP_HOST": "127.0.0.1",
"NEO4J_MCP_HTTP_PORT": "8080",
"NEO4J_MCP_HTTP_ALLOWED_ORIGINS": "http://localhost:3000,https://app.example.com"
}
}
}
}
----

For HTTP mode with TLS enabled:

[source, json]
----
{
"servers": {
"neo4j-https": {
"type": "http",
"command": "neo4j-mcp",
"env": {
"NEO4J_URI": "bolt://localhost:7687",
"NEO4J_MCP_TRANSPORT": "http",
"NEO4J_MCP_HTTP_HOST": "0.0.0.0",
"NEO4J_MCP_HTTP_PORT": "8443",
"NEO4J_MCP_HTTP_TLS_ENABLED": "true",
"NEO4J_MCP_HTTP_TLS_CERT_FILE": "/path/to/cert.pem",
"NEO4J_MCP_HTTP_TLS_KEY_FILE": "/path/to/key.pem"
}
}
}
}
----

[NOTE]
====
In HTTP mode, credentials are provided per-request via Basic Authentication headers.
Do NOT set `NEO4J_USERNAME` or `NEO4J_PASSWORD` environment variables.
====

Restart VSCode.
Open Copilot Chat and make sure that the prompt "List Neo4j MCP tools" returns expected results.

Expand All @@ -99,6 +153,8 @@ Find the files at:

Make sure to create the file if it doesn't exist.

=== STDIO mode configuration

Add the `neo4j-mcp` MCP in the `mcpServers` key:

[source, json]
Expand Down Expand Up @@ -146,10 +202,59 @@ Alternatively, you can use command-line flags in the `args` array:
}
----

=== HTTP mode configuration

For HTTP mode with CORS support:

[source, json]
----
{
"mcpServers": {
"neo4j-mcp-http": {
"type": "http",
"command": "neo4j-mcp",
"args": [],
"env": {
"NEO4J_URI": "bolt://localhost:7687",
"NEO4J_MCP_TRANSPORT": "http",
"NEO4J_MCP_HTTP_HOST": "127.0.0.1",
"NEO4J_MCP_HTTP_PORT": "8080",
"NEO4J_MCP_HTTP_ALLOWED_ORIGINS": "http://localhost:3000,https://app.example.com"
}
}
}
}
----

For HTTP mode with TLS enabled:

[source, json]
----
{
"mcpServers": {
"neo4j-mcp-https": {
"type": "http",
"command": "neo4j-mcp",
"args": [],
"env": {
"NEO4J_URI": "bolt://localhost:7687",
"NEO4J_MCP_TRANSPORT": "http",
"NEO4J_MCP_HTTP_HOST": "0.0.0.0",
"NEO4J_MCP_HTTP_PORT": "8443",
"NEO4J_MCP_HTTP_TLS_ENABLED": "true",
"NEO4J_MCP_HTTP_TLS_CERT_FILE": "/path/to/cert.pem",
"NEO4J_MCP_HTTP_TLS_KEY_FILE": "/path/to/key.pem"
}
}
}
}
----

Notes:

- Command-line flags (in `args`) take precedence over environment variables (in `env`).
- `NEO4J_READ_ONLY` is optional. Set to `true` to disable write tools.
- Neo4j Desktop example URI: `bolt://localhost:7687`.
- For Aura, use the connection string from the Aura Console.
- All connection parameters (URI, username, password) are required and have no default values.
- **STDIO mode**: All connection parameters (URI, username, password) are required and have no default values.
- **HTTP mode**: Only the URI is required. Credentials are provided per-request via Basic Authentication headers. Do NOT set `NEO4J_USERNAME` or `NEO4J_PASSWORD` in HTTP mode.
147 changes: 128 additions & 19 deletions modules/ROOT/pages/usage.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,51 +24,119 @@ When enabled, write tools (such as `write-cypher`) are not exposed to clients.
`neo4j-mcp` requires explicit configuration to connect to your Neo4j instance.
Configuration can be provided through environment variables or command-line flags.

=== Transport modes

The server supports two transport modes:

- **STDIO** (default): Traditional standard input/output mode for desktop clients
- **HTTP**: Web-based mode for multi-tenant scenarios and web clients

Set the transport mode using the `NEO4J_MCP_TRANSPORT` environment variable or `--neo4j-transport-mode` flag.

==== STDIO mode

In STDIO mode, credentials are provided via environment variables (`NEO4J_USERNAME` and `NEO4J_PASSWORD`).
The server validates connectivity and APOC availability at startup.

==== HTTP mode

In HTTP mode, the server operates statelessly and accepts per-request Basic Authentication credentials.
Do NOT set `NEO4J_USERNAME` or `NEO4J_PASSWORD` environment variables in HTTP mode, as credentials come from per-request Basic Auth headers.

=== Environment variables

The following environment variables are used for configuration:

[cols="3*", options="header"]
|===
| Variable | Description | Default
| `NEO4J_URI` | Connection URI (e.g., `bolt://localhost:7687`) | _Required_
| `NEO4J_USERNAME` | Neo4j username | _Required_
| `NEO4J_PASSWORD` | Neo4j password | _Required_
| `NEO4J_DATABASE` | Database name | `neo4j`
| `NEO4J_READ_ONLY` | Set to `true` to disable write tools | `false`
| `NEO4J_TELEMETRY` | Set to `false` to disable telemetry | `true`
| `NEO4J_LOG_LEVEL` | Log level (see <<Logging>> section) | `info`
| `NEO4J_LOG_FORMAT` | Log output format: `text` or `json` | `text`
| Variable | Description | Default
| `NEO4J_URI` | Connection URI (e.g., `bolt://localhost:7687`) | _Required_
| `NEO4J_USERNAME` | Neo4j username (STDIO mode only) | _Required for STDIO_
| `NEO4J_PASSWORD` | Neo4j password (STDIO mode only) | _Required for STDIO_
| `NEO4J_DATABASE` | Database name | `neo4j`
| `NEO4J_READ_ONLY` | Set to `true` to disable write tools | `false`
| `NEO4J_TELEMETRY` | Set to `false` to disable telemetry | `true`
| `NEO4J_LOG_LEVEL` | Log level (see <<Logging>> section) | `info`
| `NEO4J_LOG_FORMAT` | Log output format: `text` or `json` | `text`
| `NEO4J_SCHEMA_SAMPLE_SIZE` | Number of nodes to sample for schema inference | 100
| `NEO4J_MCP_TRANSPORT` | Transport mode: `stdio` or `http` | `stdio`
|===

==== HTTP mode configuration

Additional environment variables for HTTP mode:

[cols="3*", options="header"]
|===
| Variable | Description | Default
| `NEO4J_MCP_HTTP_HOST` | Server binding address | `127.0.0.1`
| `NEO4J_MCP_HTTP_PORT` | Server listening port | `80` (or `443` with TLS)
| `NEO4J_MCP_HTTP_ALLOWED_ORIGINS` | CORS configuration (comma-separated list, `*` for all, empty to disable) | _empty (disabled)_
|===

==== TLS/HTTPS configuration

Configure TLS for secure HTTPS connections in HTTP mode:

[cols="3*", options="header"]
|===
| Variable | Description | Default
| `NEO4J_MCP_HTTP_TLS_ENABLED` | Enable TLS/HTTPS | `false`
| `NEO4J_MCP_HTTP_TLS_CERT_FILE` | Path to TLS certificate file | _Required if TLS enabled_
| `NEO4J_MCP_HTTP_TLS_KEY_FILE` | Path to TLS private key file | _Required if TLS enabled_
|===

[NOTE]
====
TLS configuration enforces TLS 1.2 minimum with secure default cipher suites.
When TLS is enabled, the default port changes from 80 to 443.
====

=== Command-line flags

The following command-line flags are available and take precedence over environment variables:

==== General flags

[cols="2*", options="header"]
|===
| Flag | Description
| `--neo4j-uri` | Override `NEO4J_URI` environment variable
| `--neo4j-username` | Override `NEO4J_USERNAME` environment variable
| `--neo4j-password` | Override `NEO4J_PASSWORD` environment variable
| `--neo4j-database` | Override `NEO4J_DATABASE` environment variable
| `--neo4j-read-only` | Override `NEO4J_READ_ONLY` environment variable
| `--neo4j-telemetry` | Override `NEO4J_TELEMETRY` environment variable
| Flag | Description
| `--neo4j-uri` | Override `NEO4J_URI` environment variable
| `--neo4j-username` | Override `NEO4J_USERNAME` environment variable (STDIO mode only)
| `--neo4j-password` | Override `NEO4J_PASSWORD` environment variable (STDIO mode only)
| `--neo4j-database` | Override `NEO4J_DATABASE` environment variable
| `--neo4j-read-only` | Override `NEO4J_READ_ONLY` environment variable
| `--neo4j-telemetry` | Override `NEO4J_TELEMETRY` environment variable
| `--neo4j-schema-sample-size` | Override `NEO4J_SCHEMA_SAMPLE_SIZE` environment variable
| `-v`, `--version` | Display version information
| `--neo4j-transport-mode` | Override `NEO4J_MCP_TRANSPORT` (values: `stdio` or `http`)
| `-v`, `--version` | Display version information
|===

==== HTTP mode flags

[cols="2*", options="header"]
|===
| Flag | Description
| `--neo4j-http-host` | Override `NEO4J_MCP_HTTP_HOST` environment variable
| `--neo4j-http-port` | Override `NEO4J_MCP_HTTP_PORT` environment variable
| `--neo4j-http-tls-enabled` | Override `NEO4J_MCP_HTTP_TLS_ENABLED` environment variable
| `--neo4j-http-tls-cert-file` | Override `NEO4J_MCP_HTTP_TLS_CERT_FILE` environment variable
| `--neo4j-http-tls-key-file` | Override `NEO4J_MCP_HTTP_TLS_KEY_FILE` environment variable
|===

Command-line flags take precedence over environment variables.

[NOTE]
====
The three required connection parameters (URI, username, and password) must be provided via environment variables, command-line flags, or a combination of both.
There are no default values.
**STDIO mode**: The three required connection parameters (URI, username, and password) must be provided via environment variables, command-line flags, or a combination of both.

**HTTP mode**: Only the URI is required via environment variables or command-line flags. Credentials are provided per-request via Basic Authentication headers.
====

=== Usage examples

==== STDIO mode examples

Running with environment variables only (as configured in MCP client):

[source, bash]
Expand Down Expand Up @@ -96,6 +164,47 @@ neo4j-mcp --neo4j-username admin \
--neo4j-database production
----

==== HTTP mode examples

Running HTTP mode with environment variables:

[source, bash]
----
export NEO4J_URI="bolt://localhost:7687"
export NEO4J_MCP_TRANSPORT="http"
export NEO4J_MCP_HTTP_HOST="0.0.0.0"
export NEO4J_MCP_HTTP_PORT="8080"
neo4j-mcp
----

Running HTTP mode with CORS enabled:

[source, bash]
----
export NEO4J_URI="bolt://localhost:7687"
export NEO4J_MCP_TRANSPORT="http"
export NEO4J_MCP_HTTP_ALLOWED_ORIGINS="http://localhost:3000,https://app.example.com"
neo4j-mcp
----

Running HTTP mode with TLS enabled:

[source, bash]
----
neo4j-mcp --neo4j-uri bolt://localhost:7687 \
--neo4j-transport-mode http \
--neo4j-http-tls-enabled true \
--neo4j-http-tls-cert-file /path/to/cert.pem \
--neo4j-http-tls-key-file /path/to/key.pem \
--neo4j-http-port 8443
----

[NOTE]
====
In HTTP mode, authentication credentials are provided per-request via Basic Authentication headers, not through environment variables or command-line flags.
Each HTTP request must include an `Authorization` header with Base64-encoded credentials in the format `Basic <base64(username:password)>`.
====

== Logging

`neo4j-mcp` implements a structured logging system using the log levels defined in the MCP specification.
Expand Down