MCP Ambassador Client

A lightweight stdio MCP proxy that connects any MCP-compatible AI tool to an MCP Ambassador server. Install once -- tools appear automatically.

What Is This

The Ambassador Client is the only MCP you install on your workstation. It connects to an MCP Ambassador Server and dynamically discovers all the tools your admin has published for you. Tools from dozens of downstream MCPs appear as native tools in your AI client. No per-tool installation, no credential management, no configuration drift.

Install

npm install -g @mcpambassador/client

Or with npx (zero install):

npx @mcpambassador/client --config /path/to/config.json

Quick Start

VS Code -- add to your VS Code settings or .vscode/mcp.json:

{
  "mcp.servers": {
    "mcpambassador": {
      "command": "npx",
      "args": ["-y", "@mcpambassador/client", "--config", "/path/to/amb-client-config.json"],
      "env": {
        "MCP_AMBASSADOR_URL": "https://your-server:8443",
        "MCP_AMBASSADOR_PRESHARED_KEY": "amb_pk_YOUR_KEY"
      }
    }
  }
}

Claude Desktop -- add to claude_desktop_config.json:

{
  "mcpServers": {
    "mcpambassador": {
      "command": "npx",
      "args": ["-y", "@mcpambassador/client", "--config", "/path/to/amb-client-config.json"],
      "env": {
        "MCP_AMBASSADOR_URL": "https://your-server:8443",
        "MCP_AMBASSADOR_PRESHARED_KEY": "amb_pk_YOUR_KEY"
      }
    }
  }
}

Any MCP Host -- the generic pattern:

command: npx -y @mcpambassador/client --config /path/to/amb-client-config.json
env: MCP_AMBASSADOR_URL=https://your-server:8443
env: MCP_AMBASSADOR_PRESHARED_KEY=amb_pk_YOUR_KEY

Configuration

The client accepts a JSON configuration file. A template is provided at amb-client-config.example.json:

{
  "server_url": "https://ambassador.internal:8443",
  "preshared_key": "amb_pk_...",
  "friendly_name": "my-workstation",
  "host_tool": "vscode",
  "heartbeat_interval_seconds": 120,
  "allow_self_signed": true
}

Copy and configure:

cp amb-client-config.example.json amb-client-config.json

Note: amb-client-config.json is gitignored. Never commit configuration files containing credentials.

Environment Variables

Variable	Required	Default	Description
MCP_AMBASSADOR_URL	Yes	--	Server URL (e.g., https://your-server:8443)
MCP_AMBASSADOR_PRESHARED_KEY	Yes	--	Client preshared key (amb_pk_...)
MCP_AMBASSADOR_ALLOW_SELF_SIGNED	No	false	Allow self-signed TLS certificates (dev only)
MCP_AMBASSADOR_HOST_TOOL	No	vscode	Host tool identifier
MCP_AMBASSADOR_HEARTBEAT_INTERVAL	No	120	Heartbeat interval in seconds

CLI Usage

mcpambassador-client --server <url>
mcpambassador-client --config <path>

Options:
  --server <url>               Ambassador Server URL
  --config <path>              Path to JSON config file
  --allow-self-signed          Allow self-signed TLS certificates (dev/test only)
  --heartbeat-interval <sec>   Heartbeat interval in seconds (default: 120)
  --cache-ttl <sec>            Tool catalog cache TTL in seconds (default: 300)
  --help, -h                   Show help

How It Works

• Client registers with the server using a preshared key
• Server returns an ephemeral session token and the tool catalog
• Client exposes discovered tools as native MCP tools via stdio
• The host AI tool (VS Code, Claude Desktop) sees tools as if they were local
• Heartbeat keeps the session alive; the tool catalog refreshes automatically

Session Lifecycle

• Sessions are ephemeral and stored in memory only
• If the server returns 401 with session_expired, the client automatically re-registers
• If the server returns 401 with session_suspended, the client attempts to reconnect
• On SIGINT/SIGTERM, the client performs a best-effort disconnect (2-second timeout)

Requirements

• Node.js 20 or later
• An MCP Ambassador server (server repo)
• A preshared key (obtained from the server admin or the self-service portal)

Development

pnpm install
pnpm build
pnpm test
pnpm typecheck
pnpm lint

Related Projects

Project	Description
MCP Ambassador Server	Centralized MCP governance server
Community Registry	Curated registry of 38+ MCP configurations
Documentation	Full documentation, guides, and API reference

License

Apache License 2.0 -- see LICENSE.

Contributing

We welcome contributions. See CONTRIBUTING.md for guidelines, including the zero-dependency requirement that applies to all changes.

Performance Tuning

The client exposes several timing parameters that affect server load and responsiveness:

Setting	Default	Range	Description
heartbeat_interval_seconds	120	15–300	How often the client pings the server to keep the session alive. Higher values reduce server traffic.
cache_ttl_seconds	300	0+	How long the tool catalog is cached locally. Set to 0 to disable caching.

Deployment profiles

Profile	Heartbeat	Cache TTL	Notes
Solo developer	120s (default)	300s (default)	Works out of the box
Small team (5–10 devs)	120s	300s	Default settings are fine
Large org (50–100 devs)	180s	600s	Reduces server load at scale

All settings are configurable via CLI flags, environment variables, or the JSON config file.

Support

MCP Ambassador is free and open source. If it's useful to you, consider supporting development.

Support via GitHub Sponsors: https://github.com/sponsors/mcpambassador

Crypto donations:

• Bitcoin: 3QH4WQoQqnhU3LhbZQU8ttXaNco5Ge3xVp
• Ethereum: 0xa5462444c5AEf0B2e32822D9a9B7f91aC794FfF0