MCP聚合网关

MCP Gateway

One connector. Total visibility. Secure tool access.

A self-hosted MCP-native aggregation, routing, and security layer for desktop AI clients and agentic workflows. Connect all your MCP servers behind a single, centrally managed endpoint with full audit trails, RBAC, and policy enforcement.

Demo

https://github.com/user-attachments/assets/208b8fe2-bebd-436d-ad0c-acf2cc170226

Architecture

MCP Gateway is a three-component system:

┌─────────────────────┐     ┌─────────────────────────────────────────┐
│  AI Client          │     │  MCP Gateway Server (Rust/Axum)         │
│  (Claude, Cursor,   │────▶│                                         │
│   etc.)             │ MCP │  ┌─────────┐ ┌────────┐ ┌───────────┐  │
└─────────────────────┘     │  │ Router   │ │ Policy │ │ Audit     │  │
                            │  │ & Tools  │ │ Engine │ │ Recorder  │  │
                            │  └────┬─────┘ └────────┘ └───────────┘  │
                            │       │                                  │
                            │  ┌────┴──────────────────────────────┐  │
                            │  │         Backend Manager           │  │
                            │  │  stdio | http | sse | agent(ws)   │  │
                            │  └──┬─────────┬──────────┬───────────┘  │
                            └─────┼─────────┼──────────┼──────────────┘
                                  │         │          │
                            ┌─────┴──┐ ┌────┴───┐ ┌───┴──────────┐
                            │ Local  │ │ Remote │ │ MCP Gateway  │
                            │ stdio  │ │ HTTP   │ │ Agent (WS)   │
                            │ MCP    │ │ MCP    │ │              │
                            │ Server │ │ Server │ │ ┌──────────┐ │
                            └────────┘ └────────┘ │ │local MCP │ │
                                                  │ │servers   │ │
                                                  │ └──────────┘ │
                                                  └──────────────┘

Components

Quick Start

1. Start the gateway

The server and dashboard are published as prebuilt images on Docker Hub, so there's no build step — just pull and run. Grab the compose file, set a JWT secret, and start:

# Download the compose file
curl -O https://raw.githubusercontent.com/SidPad03/unified-mcp-gateway/main/docker-compose.yml

# A JWT secret is required — the server refuses to boot without one
echo "JWT_SECRET=$(openssl rand -hex 32)" > .env

# Pull the prebuilt images and start everything (server + dashboard + postgres)
docker compose up -d

This starts three containers:

• MCP Gateway Server on port 3200
• Dashboard on port 8080
• PostgreSQL (internal to the compose network)

The images are:

The agent is no longer published as a container image. It is a macOS app, released as a .dmg — see Remote Agent. Historical sidpad03/mcp-gateway-agent tags are left on Docker Hub but are not updated.

Each image is a multi-arch manifest (linux/amd64 + linux/arm64), so it runs natively on Intel and Apple Silicon / arm64 hosts with no emulation. The compose file tracks :latest — to pin a release, change the image: tags to a version like :v1.0.0. CI keeps the five most recent version tags plus latest, so pin to a version you have actually deployed. Prefer to build from source? See Development.

2. Log in to the dashboard

Open http://localhost:8080 and log in with the default credentials: admin / admin.

You'll be required to set a new password on first login before you can use the dashboard — the default is only for initial setup. (To skip the default and set your own initial password, put MCPGW_ADMIN_PASSWORD=... in your .env.)

3. Add an MCP backend

In the dashboard's Backends page, add a backend. For example, to add the GitHub MCP server:

The gateway will start the backend and register its tools automatically.

4. Connect your AI client

Point your MCP client (Claude Desktop, Cursor, etc.) at the gateway's MCP endpoint:

// Claude Desktop config (~/.claude/claude_desktop_config.json)
{
  "mcpServers": {
    "gateway": {
      "url": "http://localhost:3200/mcp",
      "headers": {
        "Authorization": "Bearer <your_api_key>"
      }
    }
  }
}

The dashboard's Backends → Connect a client builds this block for you, with a key for the client you pick. All backends' tools are then available through this single endpoint.

Production deployment

For production, put strong secrets in a .env file (git-ignored — Compose reads it automatically):

# Required — the server will not start without it
JWT_SECRET=your-strong-random-secret
# Optional — defaults to `mcpgateway` if unset
POSTGRES_PASSWORD=your-strong-db-password
# Optional — if unset, defaults to `admin` with a forced change on first login
MCPGW_ADMIN_PASSWORD=your-initial-admin-password

Then:

docker compose up -d

Always deploy behind a TLS-terminating reverse proxy (nginx, Caddy, etc.) in production.

Remote Agent

MCP Gateway Agent is a macOS app that connects the MCP servers running on your Mac to the gateway over a single authenticated WebSocket. The gateway sees them as if they were running on the server itself. Because the app dials out, your Mac needs no inbound ports and no firewall changes.

Requires macOS 26 or later, Apple Silicon or Intel.

Install

Homebrew is the easiest route, and the one that upgrades cleanly:

brew install --cask sidpad03/tap/mcp-gateway-agent

Later versions arrive with brew upgrade --cask mcp-gateway-agent.

Or download MCP-Gateway-Agent-<version>.dmg from the latest agent release and drag it to Applications. Updating is then yours to do.

First launch

Releases are signed with a Developer ID and notarized by Apple, so the app opens like any other download.

Older releases, and builds made without a Developer ID certificate, are ad-hoc signed instead. Gatekeeper refuses those the first time and says Apple cannot check the app for malicious software. Right-clicking and choosing Open does not get past this on current macOS. What does:

1. Open the app, and dismiss the warning.
2. Go to System Settings, then Privacy & Security.
3. Scroll to the Security section. There is a line naming the app that was just blocked, with an Open Anyway button beside it.
4. Click Open Anyway, authenticate, and confirm Open in the dialog.

macOS remembers, so this is once per install. In one line instead:

xattr -dr com.apple.quarantine "/Applications/MCP Gateway Agent.app"

Updates the app installs itself are not quarantined and skip all of this.

The keychain prompt

The gateway API key is kept in your login keychain rather than in a config file, so the first time the app reads it macOS asks:

MCP Gateway Agent wants to use your confidential information stored in "gateway-api-key" in your keychain.

Type your login password and click Always Allow, not Allow. Allow answers for that single read, so you would be asked again on the next launch.

Keychain access is granted to a code signature. A Developer ID signature stays the same from one release to the next, so updates do not ask again. An ad-hoc signature differs in every build, so on an ad-hoc build macOS sees each new version as a different application and asks once more.

Set up

Open the app, type your gateway address, and click Sign in with your gateway. A browser window opens on the gateway's authorization page; sign in with your normal account and click Authorize.

That is the whole setup. There is no API key to create, copy, or paste, and nothing to configure in the dashboard first — the Mac registers itself.

Add your MCP servers from Backends → Add backend. Test connection starts the backend, completes the MCP handshake and lists the tools it found before anything is saved, so a mistyped command is caught immediately. Backends can be added, edited, disabled and deleted while the agent is connected.

What it shows

Connection state and tool counts; every local backend with its status, PID, uptime, restarts and last error; tool calls as they happen; the agent's log and every backend's stderr, merged and exportable; and the gateway's audit trail and usage graph, scoped to this machine.

Closing the window keeps the app running in the menu bar. Settings is the standard ⌘, window.

How it works

1. The app connects to the gateway via WebSocket (/agent/ws)
2. It starts every local backend concurrently and discovers their tools
3. It registers the tools of the backends that came up, under this machine's name
4. When an AI client calls one, the gateway routes the request over the WebSocket
5. The app forwards it to the right local backend and returns the result

Each backend has a supervisor watching it: if a process exits, its tools are withdrawn from the gateway immediately — so a client is never offered a tool that cannot answer — and it is restarted with a capped backoff.

All tool calls go through the gateway's policy engine, RBAC, and audit logging — even for remote agent tools.

Full documentation: docs/agent.md. Design and rationale: docs/agent-desktop-app.md.

Features

MCP Aggregation & Routing

• Connect multiple MCP backends behind a single endpoint
• Supports stdio, streamable-http, SSE, and agent (WebSocket) transports
• Automatic tool namespacing: {backend}__{tool} with collision resolution
• Centralized tool registry with enable/disable per tool

Self-Configuration

• A gateway_* tool namespace: register, probe, start, stop and restart backends; write and reorder RBAC policy; reclassify a tool; tail a backend's logs; search the audit trail
• An agent_* mirror on each connected Mac: install, start, stop and reconfigure the MCP servers it runs
• Classified and policy-governed like every other tool — nothing here is a side door
• Invisible on the gateway itself: absent from the Tools page, the counts, the audit trail, the metrics and the usage graph, because the gateway is for the tools you put behind it
• One switch in Settings → Gateway tools, and a separate one on each Mac
• See Self-Configuration Tools

Security & Access Control

• JWT + API Key authentication (API keys use mcpgw_ prefix, SHA-256 hashed)
• RBAC — a built-in owner role plus any roles you create, each with a default allow/deny and its own attached policy rules
• Policy Engine — Priority-ordered allow/deny rules with glob patterns, risk categories, and per-application matching
• Risk Classification — Tools auto-classified as read, write, admin, destructive, execute, or unclassified
• Audit Logging — Every tool call recorded with configurable redaction

Observability

• Prometheus metrics at /metrics — call counts, latency histograms, error rates, backend health
• Homepage widget — tools, backends and 24-hour calls on a Homepage dashboard, read with a token that opens nothing else (setup)
• Metrics dashboard with charts for volume, latency, and per-tool breakdowns
• Usage graphs with time-series analysis

Remote Agent System

• MCP Gateway Agent, a macOS app, runs on your Mac
• Connects local MCP servers (stdio/http) to the gateway via authenticated WebSocket
• Browser sign-in (OAuth 2.0 + PKCE) — no API key to copy; the credential lives in the Keychain
• Backends added, edited and deleted live, with a supervisor that restarts crashed ones
• Live view of connection state, tool calls, merged logs, audit and usage
• Auto-reconnect with exponential backoff
• macOS notifications when a local server fails or crashes, the gateway is unreachable for 30 seconds, or an update is ready — each switchable, tool-call errors opt-in
• Start at login, and signed self-updates from GitHub Releases

Dashboard Pages

API Reference

All endpoints under /api/v1. Auth via Authorization: Bearer <jwt_or_api_key>.

MCP Endpoints

Environment Variables

Server

Development

# Backend (requires Rust + PostgreSQL)
cd mcp-gateway-server
cargo run

# Dashboard (requires Node.js)
cd mcp-gateway-dashboard
npm install
npm run dev

# Agent core and its C ABI (no macOS needed)
cd mcp-gateway-agent
cargo test --workspace

# The macOS app (needs macOS 26 and the Command Line Tools — no Xcode required)
./macos/build.sh            # builds build/MCP Gateway Agent.app
open "build/MCP Gateway Agent.app"

Deployment

The project includes CI/CD via GitHub Actions:

• Server & Dashboard: multi-arch Docker images (linux/amd64 + linux/arm64), built natively per-architecture and published to Docker Hub (sidpad03/mcp-gateway-*) on every main push. Old tags are pruned automatically — the five newest versions plus latest are retained
• Agent app: built universal on a macos-26 runner and published as a .dmg on an agent-v* GitHub Release, alongside a signed appcast.json the app self-updates from

Publishing requires two repository secrets — DOCKERHUB_USERNAME and DOCKERHUB_TOKEN, an access token with Read/Write/Delete scope. Delete is needed by the tag-retention step.

See CONTRIBUTING.md for local development setup and deployment details.

Documentation

Full documentation lives in docs/:

Changelog

See CHANGELOG.md for the list of changes, fixes, and upgrade notes in each release.

Security

Please see SECURITY.md for information on reporting vulnerabilities and security considerations.

Contributing

See CONTRIBUTING.md for guidelines on contributing to this project.

License

Apache 2.0