Architecture Overview

MCP Ambassador is a two-component system: a lightweight client that developers install once, and a centralized server that handles everything else.

Two-component architecture

DEVELOPER WORKSTATIONS
┌──────────────────────────────────────────────────────────────┐
│  VS Code/Copilot  Claude Code  OpenCode  Gemini CLI  Others  │
└──────────────────────┬───────────────────────────────────────┘
                       │ (all tools connect to one place)
                ┌──────┴──────┐
                │  AMBASSADOR  │  ← Only MCP installed on client
                │   CLIENT    │    Lightweight, dynamic discovery
                └──────┬──────┘
                       │ Authenticated + Encrypted
AMBASSADOR SERVER      │
┌──────────────────────┼───────────────────────────────────────┐
│             ┌────────┴────────┐                               │
│             │ GATEWAY + AAA   │                               │
│             │ Authentication  │                               │
│             │ Authorization   │                               │
│             │ Audit Logging   │                               │
│             │ Rate Limiting   │                               │
│             │ Kill Switches   │                               │
│             └────────┬────────┘                               │
│         ┌────────────┼────────────┐                          │
│  Transform Engine  Router  Service Registry                   │
│         └────────────┼────────────┘                          │
│    ┌───────┬──────┬──┴──┬────────┐                           │
│  GitHub  DB MCP  AWS  Firewall  Custom...                     │
└──────────────────────────────────────────────────────────────┘

Ambassador Client

The Ambassador Client is the only MCP a developer installs. It:

• Connects to the Ambassador Server using a preshared key (amb_pk_)
• Registers on first run, receiving a session token (amb_st_)
• Fetches the user's personalized tool catalog from the server
• Proxies tool calls through to the server, which routes them to the correct downstream MCP
• Refreshes the tool catalog automatically or on demand

The client is stateless — all configuration, credentials, and tool assignments live on the server. Switching machines is seamless: install the client, authenticate, and the same tool set appears.

Ambassador Server

The Ambassador Server is the centralized control plane. It handles:

Authentication

Every client connection uses a two-step auth flow:

1. Client presents preshared key (amb_pk_) at registration
2. Server issues an ephemeral session token (amb_st_, HMAC-SHA256 signed)
3. Client uses session token for all subsequent requests via X-Session-Token header
4. Sessions expire after idle timeout; client re-registers with preshared key

Authorization (RBAC)

Authorization is group-based:

• Admin creates groups (e.g., developers, analysts, all-users)
• Admin assigns users to groups
• Admin assigns MCPs to groups (controls who can see each MCP in the marketplace)
• Users see only MCPs published to groups they belong to
• Per-client tool selection: granular down to individual tools within an MCP

Audit Logging

Every tool invocation generates a structured audit event:

{
  "timestamp": "2026-02-23T10:00:00.000Z",
  "event": "tool_invocation",
  "user": "alice@company.com",
  "client_id": "client-abc123",
  "tool": "github.search_code",
  "downstream_mcp": "github-mcp",
  "request": { "query": "authentication" },
  "response": { "status": "success", "results": 12 },
  "authorization": { "decision": "permit", "policy": "developers-github" }
}

Kill Switches

Admins can instantly disable:

Kill switches take effect immediately on the next tool call — no client restart, no config push.

Downstream MCP routing

The Service Registry tracks all downstream MCPs:

• Transport: stdio (process spawn) or HTTP/SSE
• Isolation mode: shared (one process for all users) or per_user (separate process per user)
• Credential injection: per-user encrypted credentials decrypted at spawn time

The Router directs each tool call to the correct downstream MCP based on the tool name prefix (github.search_code → github-mcp).

Deployment tiers

Technology stack

• Server: Node.js 20+, Fastify 5, TypeScript, ESM modules
• Database: SQLite (community) / PostgreSQL (enterprise) via Drizzle ORM
• Auth: Argon2id password hashing, HMAC-SHA256 session tokens, Argon2id password hashing
• Crypto: AES-256-GCM credential encryption, HKDF key derivation
• SPA: React 19, Vite 6, Tailwind CSS 4, shadcn/ui, TanStack Query v5