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 not published to npm yet: the @mcpambassador/client package there is an out-of-date 0.8.0-beta.2, and publishing is coming. Build it from source (Node.js 20+):

git clone https://github.com/mcpambassador/client.git
cd client
npm install && npm run build

The executable is dist/cli.js. In the configs below, replace /absolute/path/to/client with the path to your clone.

It runs as an MCP server from your AI tool's config; there is no global install.

Claude Desktop

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

{
  "mcpServers": {
    "ambassador": {
      "command": "node",
      "args": ["/absolute/path/to/client/dist/cli.js"],
      "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": "node",
        "args": ["/absolute/path/to/client/dist/cli.js"],
        "env": {
          "MCP_AMBASSADOR_URL": "https://your-server:8443",
          "MCP_AMBASSADOR_PRESHARED_KEY": "amb_pk_your_preshared_key"
        }
      }
    }
  }
}

Claude Code (CLI)

claude mcp add ambassador -- node /absolute/path/to/client/dist/cli.js

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.