Installation

MCP Ambassador has two components: the server (Docker) and the Ambassador Client (npm package installed on each developer machine or agent host).

System requirements

Server

Ambassador Client

Install the server

See Docker Quickstart for the full setup guide. The short version:

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

The server starts on:

• 8443 — Client API (Ambassador Clients connect here)
• 9443 — Admin + User Web UI (browser access)

Install the Ambassador Client

The Ambassador Client is installed as an MCP server in your AI tool's config. It does not need to be installed globally.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "ambassador": {
      "command": "npx",
      "args": ["-y", "@mcpambassador/client"],
      "env": {
        "MCP_AMBASSADOR_URL": "https://your-server:8443",
        "MCP_AMBASSADOR_PRESHARED_KEY": "amb_pk_your_preshared_key"
      }
    }
  }
}

Restart Claude Desktop. The Ambassador Client connects on startup and loads your personalized tool catalog.

VS Code (Copilot / GitHub Copilot Chat)

Add to VS Code settings.json:

{
  "mcp": {
    "servers": {
      "mcpambassador": {
        "command": "npx",
        "args": ["-y", "@mcpambassador/client"],
        "env": {
          "MCP_AMBASSADOR_URL": "https://your-server:8443",
          "MCP_AMBASSADOR_PRESHARED_KEY": "amb_pk_your_preshared_key"
        }
      }
    }
  }
}

Claude Code (CLI)

claude mcp add ambassador -- npx -y @mcpambassador/client

Then set the environment variables in your shell profile or .env:

export MCP_AMBASSADOR_URL=https://your-server:8443
export MCP_AMBASSADOR_PRESHARED_KEY=amb_pk_your_preshared_key

Getting a preshared key

Preshared keys are created by an admin in the Admin UI:

1. Log in to https://your-server:9443 as admin
2. Navigate to Users → select the user
3. Click Create Preshared Key
4. Copy the key (shown once) — provide it to the user

Alternatively, via Admin API:

curl -k -b cookies.txt \
  -X POST https://localhost:9443/v1/admin/users/:id/preshared-keys \
  -H "Content-Type: application/json" \
  -d '{"label": "VS Code - Dev Laptop"}'

Self-signed TLS

By default, MCP Ambassador generates self-signed TLS certificates. The Ambassador Client automatically trusts the server's certificate using the CA fingerprint returned during registration — no manual certificate installation required.

For browsers accessing the Admin UI, you'll see a browser TLS warning. Accept it, or see Production Setup for CA-signed certificates.

Environment variables

In development mode, secrets are auto-generated and persisted to ./data/ on first boot. In production, set them explicitly — see Production Setup.