Configuration — MCP Ambassador | Enterprise MCP Gateway — MCPAmbassador

MCP Ambassador is configured via environment variables. All configuration has sensible defaults for development — production deployments should set secrets and TLS options explicitly.

Environment variables

Core

Variable	Default	Description
`NODE_ENV`	`development`	`development` or `production`. Production disables seed accounts and enables stricter settings.
`LOG_LEVEL`	`info`	`debug`, `info`, `warn`, `error`
`PORT_CLIENT`	`8443`	Ambassador Client API port
`PORT_ADMIN`	`9443`	Admin + User Web UI port

Secrets

Variable	Default	Description
`ADMIN_SESSION_SECRET`	auto-generated	32-byte hex secret for admin session HMAC. Auto-generated in development, persisted to `./data/`. Must be set explicitly in production.
`CREDENTIAL_MASTER_KEY`	auto-generated	32-byte hex key for AES-256-GCM credential vault encryption. Auto-generated in development, persisted to `./data/credential_master_key`. Must be set explicitly in production.
`ADMIN_KEY`	auto-generated	Admin API key shown in startup logs. Used for first-time admin user creation.

TLS

Variable	Default	Description
`TLS_CERT_PATH`	`/data/certs/server.crt`	Path to TLS certificate
`TLS_KEY_PATH`	`/data/certs/server.key`	Path to TLS private key
`TLS_DISABLED`	`false`	Set to `true` to disable TLS (for reverse proxy deployments)

Database

Variable	Default	Description
`DATABASE_URL`	SQLite at `/data/ambassador.db`	SQLite file path or PostgreSQL URL (Pro tier)

Session

Variable	Default	Description
`SESSION_TTL_SECONDS`	`86400`	Client session token TTL (24 hours)
`SESSION_HEARTBEAT_INTERVAL`	`300`	Expected heartbeat interval in seconds
`LOGIN_RATE_LIMIT_ATTEMPTS`	`5`	Max login attempts per IP per window
`LOGIN_RATE_LIMIT_WINDOW_SECONDS`	`300`	Rate limit window (5 minutes)

Data paths

Inside the container, all persistent data lives at /data/ (mounted as a Docker volume):

/data/
  ambassador.db          # SQLite database (WAL mode)
  certs/
    server.crt           # TLS certificate (auto-generated or provided)
    server.key           # TLS private key
    ca.crt               # CA certificate (returned to Ambassador Clients)
  credential_master_key  # 32-byte hex master key (permissions 0600)

Mount these to a persistent volume:

volumes:
  ambassador-data:
    driver: local

services:
  ambassador:
    volumes:
      - ambassador-data:/data

Generating secrets

# Generate ADMIN_SESSION_SECRET
openssl rand -hex 32

# Generate CREDENTIAL_MASTER_KEY
openssl rand -hex 32

Full docker-compose.yml example

services:
  ambassador:
    image: mcpambassador-server:latest
    ports:
      - "8443:8443"
      - "9443:9443"
    volumes:
      - ambassador-data:/data
    environment:
      - NODE_ENV=production
      - ADMIN_SESSION_SECRET=your_64_char_hex_session_secret
      - CREDENTIAL_MASTER_KEY=your_64_char_hex_master_key
      - LOG_LEVEL=info
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-fk", "https://localhost:8443/health"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  ambassador-data:

Log format

MCP Ambassador emits structured JSON logs to stdout:

{
  "level": "info",
  "timestamp": "2026-02-19T14:32:01.123Z",
  "correlation_id": "corr_uuid",
  "message": "Tool invocation completed",
  "user_id": "user_uuid",
  "tool": "github.search_code",
  "duration_ms": 234
}

Set LOG_LEVEL=debug to see verbose output including request details and MCP spawn events.