Configuration reference

This page lists every configuration key and environment variable that affects the MCP server. Keys are written to the Neptune DXP - Open Edition configuration file (typically planet9.json) unless noted otherwise. Environment variables take precedence over file values at runtime.

For instructions on how to apply configuration changes so they persist through the database layer, see Applying configuration changes.

Configuration keys

Key Environment variable Type Default Description

mcpPublicUrl

PLANET9_MCP_PUBLIC_URL

String

(empty)

The public URL at which clients reach the MCP server. Required when the server runs behind a reverse proxy. Supply scheme and host only, without a trailing slash, for example, https://mcp.planet9.com. When empty, the server falls back to the bind URL.

Can also be set from the Cockpit under System Settings → AI → MCP → Public URL; this is equivalent to setting the key directly. The scheme must match how the server actually runs (http:// for plain HTTP, https:// only when SSL is enabled or a TLS-terminating proxy is in front). A scheme mismatch is logged as a warn at startup and is a common cause of connections that hang silently — see Troubleshooting.

See Reverse proxy deployments.

enableSSL

—

Boolean

false

Enables the built-in HTTPS listener. Must be true in production environments. See Production HTTPS.

sslPort

—

Integer

8443

The port on which the HTTPS listener binds when enableSSL is true.

sslKey

—

String

(empty)

Absolute path to the PEM-encoded private key file used for TLS. Required when enableSSL is true.

sslCert

—

String

(empty)

Absolute path to the PEM-encoded certificate file used for TLS. Required when enableSSL is true.

Environment variables (runtime only)

The following variables are set in the process environment and are not written to the configuration file. They are evaluated at server startup.

Variable Values Description

NODE_ENV

development | production

When set to development, the MCP server relaxes the HTTPS enforcement for non-localhost hostnames. Always leave this unset or set to production in live environments. See Local development.

MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL

1

Disables the startup check that prevents OAuth metadata from advertising a plain HTTP issuer URL. Use only on non-localhost development hosts. Never set in production. See Local development.

MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL=1 removes a security safeguard. Setting it in a production environment exposes the OAuth flow to downgrade attacks.

Startup flags

The following flags are passed to the planet9 binary (or the equivalent npm script) at startup. They are not persistent configuration values.

Flag Description

--overwrite

Initializes the database schema, seeds the default admin user, and exits. Required once on a fresh install before the server can authenticate anyone or serve the /mcp endpoint. On Windows, run planet9.exe --initialize. See Initial setup

--overwrite

Related topics