Docker Quickstart

MCP Ambassador runs as a single Docker container. Start everything with one command.

Requirements

• Docker Engine 20+
• docker compose v2 (docker compose not docker-compose)

Quick start

git clone https://github.com/mcpambassador/server.git
cd server
cp .env.example .env
docker compose up

Default ports

First boot behavior

On first docker compose up:

1. TLS certificates auto-generated (self-signed, stored in ./data/certs/)
2. SQLite database initialized at ./data/ambassador.db
3. Credential master key generated at ./data/credential_master_key (permissions 0600)
4. Session HMAC secret generated and persisted (survives restarts)
5. Default accounts created (development mode only):
   • Admin: admin / admin123
   • Test user: qa-tester / test1234

Watch for these log lines:

INFO: admin key generated: ADMIN_KEY=adminkey_XXXXXXXXXXXXXXXX
[seed] Created admin user: <uuid> (password: admin123)
[Server] Initialization complete — listening on :8443 (client) :9443 (admin)

docker-compose.yml overview

services:
  ambassador:
    image: mcpambassador-server:latest
    # Or build locally:
    # build: .
    ports:
      - "8443:8443"
      - "9443:9443"
    volumes:
      - ambassador-data:/data
    environment:
      - NODE_ENV=development
      # Optional: set these for production
      # - ADMIN_SESSION_SECRET=<32-byte-hex>
      # - CREDENTIAL_MASTER_KEY=<32-byte-hex>
      # - DATABASE_URL=<postgres-url>  # for Pro tier
    restart: unless-stopped

volumes:
  ambassador-data:

Production deployment

See Production Setup for:

• Setting NODE_ENV=production (disables seed accounts)
• Configuring CA-signed TLS certificates
• Setting ADMIN_SESSION_SECRET and CREDENTIAL_MASTER_KEY
• Persistent data volume management
• Reverse proxy configuration (nginx/Caddy/Cloudflare Tunnel)

Health check

curl -k https://localhost:8443/health
# → {"status":"ok","version":"0.8.0-beta.1"}

Build from source

# Clone the repo
git clone https://github.com/mcpambassador/server.git
cd mcpambassador_server

# Build packages
pnpm install
pnpm -r build

# Build Docker image
docker build -t mcpambassador-server:local .

# Run
docker compose up