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.

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.

string

Optional path to the SQLite database file to use when DATABASE_URL and POSTGRES_HOST are not set. If this variable is not set, MCPJungle defaults to ./mcpjungle.db. The --sqlite-db-path CLI flag takes precedence over this variable.

export SQLITE_DB_PATH=./.mcpjungle.db
mcpjungle start

When this variable is set, MCPJungle uses that exact path instead of auto-detecting mcpjungle.db.

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

string

default:"5432"

PostgreSQL port.

export POSTGRES_PORT=5432

string

default:"postgres"

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

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

string

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

string

Path to a file containing the PostgreSQL password.

export POSTGRES_PASSWORD_FILE=/run/secrets/pg_password

string

default:"postgres"

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

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:

DATABASE_URL — used as-is if set.
POSTGRES_HOST + optional POSTGRES_* variables — MCPJungle constructs a DSN if POSTGRES_HOST is set.
--sqlite-db-path — uses the configured SQLite file path if the CLI flag is set.
SQLITE_DB_PATH — uses the configured SQLite file path if the environment variable is set.
SQLite fallback — creates or opens mcpjungle.db in the current working directory, while still recognizing an existing legacy mcp.db.

Server

string

Host or network interface the HTTP server binds to. The --host CLI flag takes precedence over this variable. If unset, MCPJungle listens on all interfaces.

export MCPJUNGLE_BIND_HOST=127.0.0.1
mcpjungle start

string

default:"8080"

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

export PORT=9090
mcpjungle start

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.

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

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

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

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

string

Docker image tag used when pulling ghcr.io/mcpjungle/mcpjungle in the provided Docker Compose files.Set this when you want to lock your mcpjungle deployment to a specific version when using one of the provided docker compose files.

MCPJUNGLE_IMAGE_TAG=0.4.0-stdio docker compose up -d

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

Quick reference

Variable	Category	Default	Description
`DATABASE_URL`	Database	—	Full PostgreSQL DSN.
`SQLITE_DB_PATH`	Database	—	SQLite database path used when PostgreSQL is not configured.
`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.
`MCPJUNGLE_BIND_HOST`	Server	all interfaces	HTTP listen host or network interface.
`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.

CLI

API

Configuration

Environment variables

Database

Database resolution order

Server

Observability

Connections

Docker

Quick reference

​Database

​Database resolution order

​Server

​Observability

​Connections

​Docker

​Quick reference

Database

Database resolution order

Server

Observability

Connections

Docker

Quick reference