Skip to main content
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
ModeBehaviour
developmentNo authentication enforced. All MCP clients have full access to all registered servers. Ideal for local use.
enterpriseStrict 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).
ValueBehaviour
-1 (default)No timeout. Sessions live until the server stops or the server is deregistered.
0No timeout (equivalent to -1). Sessions run until server shutdown.
> 0Sessions 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
TagDescription
latestMinimal image — MCPJungle binary only. Recommended for production.
latest-stdioIncludes node, npx, and uvx. Required if you register STDIO servers that rely on those runtimes.

​
Quick reference

VariableCategoryDefaultDescription
DATABASE_URLDatabase—Full PostgreSQL DSN.
POSTGRES_HOSTDatabase—PostgreSQL host. Required to enable POSTGRES_* variables.
POSTGRES_PORTDatabase5432PostgreSQL port.
POSTGRES_USERDatabasepostgresPostgreSQL username.
POSTGRES_USER_FILEDatabase—File path for PostgreSQL username.
POSTGRES_PASSWORDDatabase(empty)PostgreSQL password.
POSTGRES_PASSWORD_FILEDatabase—File path for PostgreSQL password.
POSTGRES_DBDatabasepostgresPostgreSQL database name.
POSTGRES_DB_FILEDatabase—File path for PostgreSQL database name.
PORTServer8080HTTP listen port.
SERVER_MODEServerdevelopmentServer mode: development or enterprise.
MCP_SERVER_INIT_REQ_TIMEOUT_SECServer30Seconds to wait for MCP server initialization.
OTEL_ENABLEDObservabilitymode-dependentEnable OpenTelemetry metrics.
OTEL_RESOURCE_ATTRIBUTESObservability—Additional OTel resource attributes.
SESSION_IDLE_TIMEOUT_SECConnections-1Idle timeout for stateful sessions.
MCPJUNGLE_IMAGE_TAGDockerlatestDocker image tag for Compose deployments.