MCPJungle environment variable reference

Complete reference for every environment variable the MCPJungle server reads at startup, grouped by category: database, server, observability, and connections.

MCPJungle reads environment variables at startup to configure the database connection, server mode, observability, and connection behaviour. Variables can be set in the shell, in a .env file in the working directory (loaded automatically via godotenv), or as Docker environment variables.

Database

MCPJungle supports SQLite (default) and PostgreSQL. Use either DATABASE_URL for a full DSN or the individual POSTGRES_* variables to build the DSN from parts.

DATABASE_URL · string

Full PostgreSQL connection string. When set, MCPJungle connects to PostgreSQL and ignores any POSTGRES_* variables.

export DATABASE_URL=postgres://admin:root@localhost:5432/mcpjungle_db

When this variable is not set and POSTGRES_HOST is also not set, MCPJungle falls back to an embedded SQLite database file (mcpjungle.db) in the current working directory.

POSTGRES_HOST · string

PostgreSQL host. Required when using the individual POSTGRES_* variables instead of DATABASE_URL. If this variable is not set, MCPJungle does not attempt to build a PostgreSQL DSN from the other POSTGRES_* variables.

export POSTGRES_HOST=localhost

POSTGRES_PORT · string · default: "5432"

PostgreSQL port.

export POSTGRES_PORT=5432

POSTGRES_USER · string · default: "postgres"

PostgreSQL username. If both POSTGRES_USER and POSTGRES_USER_FILE are set, POSTGRES_USER takes precedence.

POSTGRES_USER_FILE · string

Path to a file containing the PostgreSQL username. Useful with Docker secrets. MCPJungle reads the file and trims surrounding whitespace.

export POSTGRES_USER_FILE=/run/secrets/pg_user

POSTGRES_PASSWORD · string

PostgreSQL password. If both POSTGRES_PASSWORD and POSTGRES_PASSWORD_FILE are set, POSTGRES_PASSWORD takes precedence. The password can be empty.

POSTGRES_PASSWORD_FILE · string

Path to a file containing the PostgreSQL password.

export POSTGRES_PASSWORD_FILE=/run/secrets/pg_password

POSTGRES_DB · string · default: "postgres"

PostgreSQL database name. If both POSTGRES_DB and POSTGRES_DB_FILE are set, POSTGRES_DB takes precedence.

POSTGRES_DB_FILE · string

Path to a file containing the PostgreSQL database name.

export POSTGRES_DB_FILE=/run/secrets/pg_db

Database resolution order

When the server starts it resolves the database connection in this order:

1. DATABASE_URL — used as-is if set.
2. POSTGRES_HOST + optional POSTGRES_* variables — MCPJungle constructs a DSN if POSTGRES_HOST is set.
3. SQLite fallback — creates or opens mcpjungle.db in the current working directory.

---

Server

PORT · string · default: "8080"

TCP port the HTTP server listens on. The --port CLI flag takes precedence over this variable.

export PORT=9090
mcpjungle start

SERVER_MODE · string · default: "development"

Server operating mode. Accepted values are development and enterprise (case-insensitive). The --enterprise CLI flag takes precedence over this variable.

export SERVER_MODE=enterprise
mcpjungle start

Mode	Behaviour
development	No authentication enforced. All MCP clients have full access to all registered servers. Ideal for local use.
enterprise	Strict access control, user management, and observability features. Requires running mcpjungle init-server after the first start.

The value production is accepted for backward compatibility but is deprecated. Use enterprise instead.

MCP_SERVER_INIT_REQ_TIMEOUT_SEC · integer · default: "30"

Maximum number of seconds MCPJungle waits for a newly registered MCP server to respond to its initialization request before aborting. Must be a positive integer. Increase this value if you register STDIO servers that take a long time to start up.

export MCP_SERVER_INIT_REQ_TIMEOUT_SEC=60

---

Observability

OTEL_ENABLED · boolean · default: "false (development) / true (enterprise)"

Enables Prometheus-compatible OpenTelemetry metrics. When enabled, metrics are exposed at the /metrics HTTP endpoint. Accepted values are true, 1, false, and 0 (case-insensitive).

In enterprise mode this defaults to true. In development mode it defaults to false. Setting this variable explicitly overrides the mode-based default.

export OTEL_ENABLED=true
mcpjungle start

OTEL_RESOURCE_ATTRIBUTES · string

Additional key-value attributes attached to all emitted OTel metrics. Use the standard key=value,key2=value2 format defined by the OpenTelemetry specification.

export OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=enterprise

These attributes are appended to the resource description alongside the automatically detected service name, host, and process attributes.

---

Connections

SESSION_IDLE_TIMEOUT_SEC · integer · default: "-1"

Idle timeout in seconds for stateful MCP sessions. A stateful session is kept open between tool calls to avoid cold-start overhead (see Session modes).

Value	Behaviour
-1 (default)	No timeout. Sessions live until the server stops or the server is deregistered.
0	No timeout (equivalent to -1). Sessions run until server shutdown.
> 0	Sessions are closed after this many seconds of inactivity.

export SESSION_IDLE_TIMEOUT_SEC=300

This setting has no effect on stateless connections, which are the default and are closed immediately after each tool call.

---

Docker

MCPJUNGLE_IMAGE_TAG · string · default: "latest"

Docker image tag used when pulling ghcr.io/mcpjungle/mcpjungle in the provided Docker Compose files. Set this to latest-stdio to use the larger image that bundles npx and uvx runtimes needed for STDIO-based MCP servers.

MCPJUNGLE_IMAGE_TAG=latest-stdio docker compose up -d

Tag	Description
latest	Minimal image — MCPJungle binary only. Recommended for production.
latest-stdio	Includes node, npx, and uvx. Required if you register STDIO servers that rely on those runtimes.

---

Quick reference

Variable	Category	Default	Description
DATABASE_URL	Database	—	Full PostgreSQL DSN.
POSTGRES_HOST	Database	—	PostgreSQL host. Required to enable POSTGRES_* variables.
POSTGRES_PORT	Database	5432	PostgreSQL port.
POSTGRES_USER	Database	postgres	PostgreSQL username.
POSTGRES_USER_FILE	Database	—	File path for PostgreSQL username.
POSTGRES_PASSWORD	Database	(empty)	PostgreSQL password.
POSTGRES_PASSWORD_FILE	Database	—	File path for PostgreSQL password.
POSTGRES_DB	Database	postgres	PostgreSQL database name.
POSTGRES_DB_FILE	Database	—	File path for PostgreSQL database name.
PORT	Server	8080	HTTP listen port.
SERVER_MODE	Server	development	Server mode: development or enterprise.
MCP_SERVER_INIT_REQ_TIMEOUT_SEC	Server	30	Seconds to wait for MCP server initialization.
OTEL_ENABLED	Observability	mode-dependent	Enable OpenTelemetry metrics.
OTEL_RESOURCE_ATTRIBUTES	Observability	—	Additional OTel resource attributes.
SESSION_IDLE_TIMEOUT_SEC	Connections	-1	Idle timeout for stateful sessions.
MCPJUNGLE_IMAGE_TAG	Docker	latest	Docker image tag for Compose deployments.