# Mcpambassador Server

> Open-source MCP governance proxy -- authentication, authorization, audit, and a marketplace for AI tools. Self-hosted via Docker.

- **Type:** MCP server
- **Install:** `agentstack add mcp-mcpambassador-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [mcpambassador](https://agentstack.voostack.com/s/mcpambassador)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [mcpambassador](https://github.com/mcpambassador)
- **Source:** https://github.com/mcpambassador/server
- **Website:** https://mcpambassador.ai

## Install

```sh
agentstack add mcp-mcpambassador-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# MCP Ambassador Server

[](https://github.com/mcpambassador/server/actions/workflows/ci.yml) [](./LICENSE) []() []() []() [](https://mcpambassador.ai)

Centralized authentication, authorization, and audit for MCP tools. One server governs every downstream MCP your organization uses.

## What Is This

MCP Ambassador Server is the control plane for managing MCP tools across your organization. It proxies, authenticates, authorizes, and audits every tool call between AI clients and downstream MCP servers. Think of it as what LiteLLM does for LLM providers, but for MCP servers.

## Key Features

- **MCP Marketplace** -- Admin-published catalog of downstream MCPs with group-based visibility
- **User Self-Service** -- Users browse, subscribe to, and manage their own tool access through the web portal
- **Per-User MCP Isolation** -- Dedicated MCP instances per user with encrypted credential injection
- **Group-Based RBAC** -- Control which teams see which tools through group assignments
- **Credential Vault** -- AES-256-GCM encrypted per-user API keys with HKDF-derived keys
- **OAuth 2.0 Integration** -- Authorization code flow for downstream MCP authentication (GitHub, etc.)
- **Admin Dashboard** -- React SPA for managing users, groups, MCPs, and audit logs
- **Audit Logging** -- Append-only JSONL log of every authentication decision and tool invocation
- **Kill Switches** -- Instantly disable any MCP or client across the entire organization
- **Docker Deployment** -- Single container with bind-mount volumes and auto-generated TLS

## Quick Start

Prerequisites: Docker Engine 20+, docker compose v2

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

Open https://localhost:9443 -- the first-run setup wizard will guide you through creating an admin account.

### Ports

| Port | Service |
|------|---------|
| 8443 | Client API (MCP proxy endpoint) |
| 9443 | Admin and user web portal |

For production deployment, see the [Deployment Guide](https://mcpambassador.ai/docs/docker).

## MCP Lifecycle

Every MCP goes through a four-step lifecycle before users can access its tools:

```
Create (draft/pending) --> Validate (draft/valid) --> Discover Tools --> Publish (active)
```

| Step | Action | What Happens |
|------|--------|--------------|
| 1. Create | Admin > MCPs > Create MCP | Define name, transport, command, environment variables, isolation mode. MCP starts as **draft / pending**. |
| 2. Validate | Click **Validate** on the MCP | Server checks the configuration is well-formed. Status moves to **draft / valid**. |
| 3. Discover Tools | Click **Discover Tools** | Server spawns the MCP process, connects, calls `tools/list`, and records the available tools. |
| 4. Publish | Click **Publish** | MCP becomes **published** and appears in the user Marketplace. |

After publishing, users can browse the Marketplace, subscribe their clients to the MCP, and start using the tools through their AI clients.

**Note:** If an MCP requires per-user credentials (e.g., API keys), the Discover Tools step will prompt for temporary credentials to use during discovery. These are not stored.

## Connecting a Client

Install the MCP Ambassador Client to connect AI tools to this server.

```bash
npm install -g @mcpambassador/client
```

VS Code configuration example:

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

See [@mcpambassador/client](https://github.com/mcpambassador/client) for Claude Desktop, OpenCode, and other integrations.

## Monorepo Structure

| Package | Description |
|---------|-------------|
| `@mcpambassador/protocol` | Type-only API contract between client and server (zero runtime deps) |
| `@mcpambassador/core` | Database schema, SPI interfaces, pipeline, validation |
| `@mcpambassador/server` | Hono HTTP/2 server, REST API routes, MCP process pools |
| `@mcpambassador/spa` | React 19 admin dashboard and user self-service portal |
| `@mcpambassador/authn-ephemeral` | Preshared key and ephemeral session authentication |
| `@mcpambassador/authz-local` | Group-based RBAC authorization |
| `@mcpambassador/audit-file` | JSONL audit log provider |
| `@mcpambassador/contracts` | Zod schemas for API request/response validation |

## Security

- TLS on all ports (self-signed auto-generated or CA-signed)
- Argon2id password hashing
- AES-256-GCM credential encryption with per-user HKDF-derived keys
- HMAC-SHA256 session tokens with configurable idle timeout
- Process isolation for stdio MCP child processes
- Non-root Docker container with read-only root filesystem
- Append-only audit log for compliance and forensics

## Development

```bash
# Prerequisites: Node.js 20+, pnpm 8.15+
pnpm install
pnpm -r build
pnpm -r test
pnpm -r lint
pnpm -r typecheck
pnpm format:check
```

## Related Projects

| Project | Description |
|---------|-------------|
| [@mcpambassador/client](https://github.com/mcpambassador/client) | Lightweight MCP proxy for developer workstations |
| [Community Registry](https://github.com/mcpambassador/community-registry) | Curated registry of 38+ MCP server configurations |
| [Documentation](https://mcpambassador.ai) | Full documentation, guides, and API reference |

## Configuration Reference

MCP Ambassador is configured via environment variables. All settings have production-ready defaults. See [mcpambassador.ai/docs/configuration](https://mcpambassador.ai/docs/configuration) for the full reference.

### Timing & Performance

These settings control session management, health monitoring, and internal scheduling. The defaults are tuned for production use with hundreds of concurrent sessions.

| Setting | Default | Description |
|---------|---------|-------------|
| Session TTL | 28800s (8h) | Client session token lifetime before re-authentication |
| Session eval interval | 120s | How often the server checks for idle/expired sessions |
| Session sweep interval | 1800s (30m) | How often the server purges expired sessions from memory |
| Heartbeat expected interval | 120s | Expected interval between client heartbeats |
| Heartbeat rate limit | 1 per 10s | Maximum heartbeat frequency per client |
| Health check interval | 120s | How often the server checks downstream MCP health |

### SPA Polling Intervals

The admin/user web portal polls the server for live data. These intervals balance responsiveness with server load.

| Endpoint | Interval | Description |
|----------|----------|-------------|
| Health status | 60s | MCP instance health |
| MCP list | 60s | Admin MCP catalog |
| Catalog | 60s | User marketplace |
| Logs | 30s | MCP instance logs |

### Deployment Profiles

| Profile | Session TTL | Heartbeat | Eval Interval | Recommended For |
|---------|-------------|-----------|---------------|-----------------|
| **Default** | 8h | 120s | 120s | Most production deployments |
| **High-security** | 4h | 60s | 60s | Regulated environments, SOC2 |
| **Development** | 24h | 30s | 30s | Local development, testing |

For client-side settings (heartbeat interval, cache TTL, catalog refresh), see [@mcpambassador/client](https://github.com/mcpambassador/client#performance-tuning).

## Contributing

We welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

Prerequisites: Node.js 20+, pnpm 8.15+, Docker

## 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`

## License

Apache License 2.0 -- see [LICENSE](./LICENSE).

## Status

MCP Ambassador is at v0.8.0-beta.2. The API may change before 1.0. Production use is supported but expect breaking changes during the beta period.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [mcpambassador](https://github.com/mcpambassador)
- **Source:** [mcpambassador/server](https://github.com/mcpambassador/server)
- **License:** Apache-2.0
- **Homepage:** https://mcpambassador.ai

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-mcpambassador-server
- Seller: https://agentstack.voostack.com/s/mcpambassador
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.