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`	`28800`	Client session token TTL (8 hours)
`SESSION_HEARTBEAT_INTERVAL`	`120`	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.

Timing and performance

MCP Ambassador's internal timers are tuned for production workloads with hundreds of concurrent sessions. You can adjust these in the YAML config file (ambassador-server.yaml) or via environment variables.

Server-side timing

Setting	Default	Config Path	Description
Session TTL	28800s (8h)	`session.ttl_seconds`	How long a client session token is valid before the client must re-authenticate
Evaluation interval	120s	`session.evaluation_interval_seconds`	How often the server evaluates sessions for idle timeout
Sweep interval	1800s (30m)	`session.sweep_interval_seconds`	How often the server purges expired sessions from memory
Heartbeat expected	120s	`session.heartbeat_expected_interval_seconds`	How often the server expects a heartbeat from each client
Heartbeat rate limit	1 per 10s	Hardcoded	Maximum heartbeat frequency per client (prevents misconfigured clients from flooding)
Health check interval	120000ms	`mcp.health_check_interval_ms`	How often the server pings downstream MCPs to verify they are alive

Admin SPA polling

The web dashboard polls the server for live status updates. These intervals balance responsiveness with server load.

Endpoint	Interval	What it shows
Health status	60s	MCP instance health indicators
MCP list	60s	Admin MCP catalog
Catalog	60s	User marketplace
Logs	30s	MCP instance log stream

Client-side timing

The Ambassador Client (@mcpambassador/client) has its own performance settings. See the client documentation for details.

Setting	Default	Description
Heartbeat interval	120s	How often the client sends a heartbeat to keep the session alive
Cache TTL	300s	How long the client caches the tool catalog before refreshing
Cache enabled	`true`	Whether tool catalog caching is active (recommended for production)

Deployment profiles

Choose the profile that matches your security and scale requirements.

Profile	Session TTL	Heartbeat	Eval interval	Best for
Default	8h	120s	120s	Most production deployments
High-security	4h	60s	60s	Regulated environments, SOC2 compliance
Development	24h	30s	30s	Local development and testing
High-scale	8h	180s	180s	1000+ concurrent sessions, minimize server load