MCP Ambassador Server

One server to authenticate, authorize, and audit every MCP tool your team uses. It proxies tool calls between AI clients and downstream MCP servers, and records each decision.

Features

• Marketplace and self-service: admins publish downstream MCPs; users browse and subscribe from the web portal. Visibility follows group membership.

• Group RBAC, including per-tool group policy: a group's MCP grant can allow all tools, only a list, or all but a list.

• Per-user MCP instances with encrypted credentials (AES-256-GCM, HKDF-derived keys) and OAuth 2.0 for downstream MCPs.

• Tool pinning: tool definitions are hashed; new or changed tools wait in a review queue (single and bulk approve) before agents see them.

• Approval gates: an admin can require a person to approve each use of a risky tool. They apply to remote-agent (/mcp) grants; stdio client calls to a gated tool are refused (not_supported_for_client).

• Kill switches: disable a client, an MCP, or a single tool of one MCP.

• Progressive disclosure: agents can be given three search/describe/call tools instead of the full tool list.

• Audit log: append-only JSONL of authentication decisions and tool calls.

• Admin and user SPA (React 19) on the web port.

Details for each: mcpambassador.ai/docs.

Related MCP server: MCP OAuth Test

Quick start

Needs Docker Engine 20+ and docker compose v2.

git clone https://github.com/mcpambassador/server.git
cd server
cp .env.example .env
./setup-host-dirs.sh         # creates data/ config/ cache/ owned by uid 1000 (data/ mode 700)
docker compose up -d

Open https://localhost:9443 (self-signed TLS) and follow the first-run setup wizard to create the admin account.

First boot also writes data/initial-credentials.txt (admin API key and recovery token, mode 600). Record them in a password manager, then delete the file.

The compose default is NODE_ENV=production. For a local trial you can set NODE_ENV=development in .env: after the admin exists, first boot then creates an all-tools dev preshared key (never use that in production). For verbose logs set LOG_LEVEL=debug.

The reference compose file binds 9443 to 127.0.0.1. Production setup, TLS, and reverse proxies: Docker guide and Production guide.

Container requirements

MCP children run under their own uids, so the container must start as root, drop to uid 1000 in the entrypoint, and keep only the capabilities it needs. docker-compose.yml in this repo is the reference; a deployment's compose must match it:

user: '0:0'
cap_drop: [ALL]
cap_add: [SETUID, SETGID, KILL, CHOWN, SETPCAP]
security_opt:
  - no-new-privileges:true
read_only: true # with ./data:/data and ./cache:/tmp bind mounts
deploy:
  resources:
    limits:
      pids: 4096

Without SETUID/SETGID/KILL, MCP children refuse to start; without SETPCAP, the container refuses to start. See the 0.10.0 BREAKING notes in CHANGELOG.md before upgrading.

Configuration

Configured by environment variables (see .env.example, docker-compose.yml, and the configuration reference). The compose file has no env_file: .env only feeds the ${...} substitutions already in docker-compose.yml (such as LOG_LEVEL, NODE_ENV, PUBLIC_URL, REGISTRY_*). To set any other variable below, add it under environment: in docker-compose.yml. Commonly used:

Agent endpoint grant lifetimes

Set in the agent_endpoint block of the server config (the endpoint is off by default).

Lowering max_grant_ttl_seconds or max_dcr_grant_ttl_seconds (the cap for dynamically registered clients, since v0.10.4) only limits grants created afterwards. Existing grants keep their original expiry; to end one sooner, revoke it.

Session heartbeat

Set in the session block of the server config.

Security model

• Isolation: each downstream stdio MCP instance runs under its own uid with a private home, cannot read /data or other instances, and starts with no-new-privs. The container has a read-only root filesystem and a reduced capability set. This is process-level isolation, not a sandbox:

  • instances share the container's network namespace and process list;

  • the server process keeps SETUID/SETGID/KILL;

  • isolation can be disabled, and the legacy single-uid mode puts every instance under one uid;

  • git/URL package specs in an MCP definition are not guarded yet, so only add MCPs you trust;

  • docker is not in the default command allowlist. If you add it (MCP_ALLOWED_COMMANDS), only docker run/podman run with a small allowlist of confinement-preserving options is accepted (no mounts, --privileged, host namespaces, added capabilities, root user, --entrypoint, or daemon-redirecting global options), and DOCKER_*/CONTAINER_* env names are blocked. Running docker needs access to the Docker socket, which is host-root equivalent. It is unsupported for untrusted MCPs, whatever the argument guard accepts.

• Tool pinning: the full definition of every downstream tool is hashed. Unreviewed or changed definitions are hidden from agents until an admin approves them (unless that MCP's pin policy is auto, which is not allowed for registry or imported MCPs); flagged or previously revoked definitions need an explicit extra step.

• Authorization order per call: kill switch, group policy, then the subscription's selected tools. A tool that is denied answers the same as one that does not exist.

• Approval gates: per-tool human approval for remote-agent (/mcp) grants; the approver sees a redacted argument preview. Stdio client calls to a gated tool are refused (not_supported_for_client).

• Credentials: AES-256-GCM encryption with per-user HKDF-derived keys; Argon2id password hashing; HMAC-SHA256 session tokens.

• Transport: TLS on every listener (self-signed by default, or CA-signed).

• Audit: every decision and call is written to an append-only log.

Report vulnerabilities as described in .github/SECURITY.md. Deeper reading: security, tool pinning, approval gates, kill switches, RBAC, progressive disclosure.

Connecting a client

The client is a stdio MCP you point your AI tool at. Install it from npm: npx -y @mcpambassador/client --config <path> or npm i -g @mcpambassador/client (releases carry provenance; check with npm audit signatures). See the client README for tool configs. When agent_endpoint.enabled is set in the server config (off by default; the routes return 404 otherwise), agents that speak MCP over HTTP can also use the agent endpoint on 8443 (see client-server docs).

Repository layout

pnpm monorepo:

Development

Node.js 22+ and pnpm 10+. Changes to protocol or contracts also affect the client; see CONTRIBUTING.md.

pnpm install && pnpm -r build && pnpm -r lint && pnpm format:check && pnpm -r typecheck && pnpm -r test

Related

Client · Community registry · Documentation · Changelog

Support

Free and open source. Sponsor: https://github.com/sponsors/mcpambassador

• Bitcoin: 3QH4WQoQqnhU3LhbZQU8ttXaNco5Ge3xVp

• Ethereum: 0xa5462444c5AEf0B2e32822D9a9B7f91aC794FfF0

License

Apache License 2.0, see LICENSE. Pre-1.0: the API may change between releases.