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.

SQLITE_DB_PATH

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.

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:

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

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

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.
`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