MCPlexer Documentation
MCPlexer is a directory-scoped MCP gateway that sits between your AI client and multiple downstream MCP servers. It provides routing, authentication, tool namespacing, approval workflows, and audit logging — all from a single configuration.
architecture
┌─────────────┐
│ AI Client │ Claude Desktop, Cursor, Windsurf, etc.
│ (MCP Host) │
└──────┬───────┘
│ stdio / HTTP / socket
▼
┌──────────────────────────────────────────┐
│ MCPlexer Gateway │
│ │
│ ┌──────────┐ ┌────────┐ ┌───────────┐ │
│ │ Routing │ │ Auth │ │ Approvals│ │
│ │ Engine │ │ Scopes │ │ & Audit │ │
│ └──────────┘ └────────┘ └───────────┘ │
└──┬──────┬──────┬──────┬──────┬───────────┘
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
┌──────┐┌──────┐┌──────┐┌──────┐┌──────┐
│GitHub││Linear││ Click││ Sentry││ Your │
│ MCP ││ MCP ││ Up ││ MCP ││ MCP │
│Server││Server││ MCP ││Server││Server│
└──────┘└──────┘└──────┘└──────┘└──────┘
Key Concepts
| Concept | Description |
|---|---|
| Workspace | A directory-scoped security context. Each workspace has a root path and a default policy (allow or deny). |
| Downstream Server | An MCP server instance (stdio or HTTP) that MCPlexer manages. Each gets a unique namespace prefix. |
| Route Rule | Maps a workspace + path glob + tool pattern to a downstream server, auth scope, and policy. |
| Auth Scope | A credential container — environment variables, HTTP headers, or OAuth tokens injected into downstream calls. |
| Namespace | Tool names are always prefixed as {namespace}__{toolname} to prevent collisions across servers. |
| Policy | Either allow or deny. Deny-first evaluation means explicit denies always win. |
How It Works
- Your AI client connects to MCPlexer via stdio, HTTP, or Unix socket
- MCPlexer discovers tools from all configured downstream servers
- When a tool call arrives, the routing engine matches it to the correct downstream
- Auth scopes inject credentials before forwarding the request
- Approval workflows gate sensitive operations
- Every call is audit logged with full redaction of secrets
Documentation
Getting Started
- Quickstart — Install, configure, and make your first tool call
- Concepts — Architecture, request lifecycle, and transport modes
Platform Support
Desktop app: macOS (Apple Silicon and Intel). Linux via make electron-package-linux. Windows is not supported.
CLI: macOS, Linux, and anywhere Go compiles to.
Configuration
- Config Methods — YAML, Web UI, Desktop App, and environment variables
- CLI Reference — All subcommands, flags, and usage examples
- File Locations — Where MCPlexer stores data, config, and keys
Core Concepts
- Workspaces — Directory-scoped security contexts
- Downstream Servers — Managing MCP server instances
- Routing Engine — Route matching, priorities, and glob patterns
- Authentication — Auth scopes, OAuth, and credential injection
- Secrets — Age encryption and secret management
Features
- Tool Approvals — Approval workflows for sensitive tools
- Audit Logging — Request/response logging with redaction
- Caching — Response caching for downstream servers
- GitHub Policy — Org and repo allowlist enforcement
- Connect / Bridge — Bridge stdio to daemon socket
Operations
- Dashboard & Web UI — Real-time monitoring and configuration
- REST API Reference — Programmatic access to all MCPlexer features
- Control Server — Read-only MCP server for introspection
- Desktop App — Native desktop application
- Deployment — Production deployment patterns
- Troubleshooting — Common issues and debugging