You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: rewrite README with problem-focused narrative and user-centric features
Rewrites README to lead with the core problem: MCP config is per-client
and credentials sit in plain text. Shows the before/after clearly with
diagrams. Features are explained from the user's perspective (what they
do, not how the code works). Security section contrasts against MCP's
default plain-text approach. Getting started is 3 simple steps.
https://claude.ai/code/session_01W32JdTpYeN92qNrHPgMyVo
**One gateway. Every MCP server. Zero cloud traffic.**
6
+
### Configure your MCP servers once. Connect every AI client.
7
7
8
-
McpMux is a cross-platform desktop application that aggregates all your Model Context Protocol (MCP) servers behind a single local endpoint. It manages credentials, isolates projects into Spaces, and keeps every tool call on your machine.
8
+
McpMux is a desktop app that gives you **one place** to manage all your MCP servers — so you never have to copy-paste server configs across Cursor, Claude Desktop, VS Code, or any other AI client again.
9
9
10
10
---
11
11
12
-
## The Problem
12
+
## Why McpMux?
13
13
14
-
Working with MCP servers today means juggling multiple connections, credentials, and configurations across different AI clients. Each server may require its own authentication, and switching between projects means reconfiguring everything. Credentials end up scattered, there is no unified view of available tools, and sensitive data often passes through third-party services unnecessarily.
14
+
### The problem: MCP config is per-client
15
15
16
-
## The Solution
16
+
Every AI client that supports MCP has its own configuration file. Want to use a GitHub server, a database server, and a Slack server? You configure all three **separately** in every single client.
17
17
18
-
McpMux runs a local gateway on `localhost:9315` that acts as a single entry point for all your MCP servers. AI clients connect to McpMux once, and it handles the rest: routing tool calls to the right backend, refreshing OAuth tokens automatically, and keeping credentials locked in your OS keychain.
18
+
```
19
+
Cursor → config.json → github, slack, db servers + credentials
20
+
Claude Desktop → config.json → github, slack, db servers + credentials (again)
21
+
VS Code → settings.json → github, slack, db servers + credentials (again)
Add a new server? Update **every client**. Rotate an API key? Update **every client**. Start a new project with different servers? Reconfigure **everything**.
26
+
27
+
### The other problem: credentials in plain text
28
+
29
+
MCP configs store API keys and tokens in **plain JSON files on disk**. No encryption, no access control — just raw secrets sitting in your home directory.
30
+
31
+
### The fix: configure once, connect everywhere
32
+
33
+
McpMux runs a local gateway on your machine. You configure your servers and credentials **once** inside McpMux, then point all your AI clients to a single local URL. That's it.
Claude Desktop ─┤──→ McpMux (localhost:9315) ──→ github, slack, db servers
38
+
VS Code ─┤ manages all credentials
39
+
Windsurf ─┘ one config, one place
43
40
```
44
41
42
+
Add a server in McpMux → every client has it instantly. No files to edit. No credentials to copy.
43
+
45
44
---
46
45
47
-
## Features
46
+
## How It Works
48
47
49
-
### Local-First Gateway
50
-
All MCP traffic stays on your machine. McpMux runs entirely on `localhost` and never routes tool calls through external services. Cloud sync is optional and limited to configuration data only (server definitions, space settings) — never command payloads or responses.
48
+
**1. Install servers** — Browse the built-in registry or add servers manually.
51
49
52
-
### Spaces: Project Isolation
53
-
Organize servers into isolated workspaces called **Spaces**. Each Space has its own set of server configurations, credentials, and permissions. Switch between "Work", "Personal", or "Client Project" contexts without reconfiguring anything. Credentials are never shared across Spaces.
50
+
**2. Copy one config** — McpMux gives you a single JSON snippet to paste into any AI client:
54
51
55
-
### Secure Credential Management
56
-
Credentials are stored using your operating system's native keychain:
57
-
-**macOS**: Keychain
58
-
-**Windows**: Credential Manager
59
-
-**Linux**: Secret Service (GNOME Keyring, KWallet)
52
+
```json
53
+
{
54
+
"mcpServers": {
55
+
"mcpmux": {
56
+
"url": "http://localhost:9315/mcp"
57
+
}
58
+
}
59
+
}
60
+
```
60
61
61
-
Sensitive fields in the local database are encrypted with **AES-256-GCM**authenticated encryption. Encryption keys live in the OS keychain, not on disk. Sensitive data is zeroized from memory after use to prevent leaks.
62
+
**3. Done**— Every tool, prompt, and resource from all your servers is now available in every connected client.
62
63
63
-
### OAuth 2.1 with PKCE
64
-
McpMux implements the full OAuth 2.1 authorization flow with Proof Key for Code Exchange (PKCE, RFC 7636) for connecting to remote MCP servers. It handles:
65
-
- Automatic server discovery via RFC 8414 (`.well-known/oauth-authorization-server`)
66
-
- Dynamic Client Registration (RFC 7591)
67
-
- Automatic token refresh — no manual re-authentication
64
+
When an AI client calls a tool, McpMux routes the request to the right server automatically. OAuth tokens refresh in the background. Credentials stay encrypted in your OS keychain. You don't think about it.
68
65
69
-
### Multi-Transport Support
70
-
Connect to MCP servers over any supported transport:
71
-
-**stdio** — local processes (Node.js, Python, Rust, Go, etc.)
72
-
-**Streamable HTTP** — remote servers over HTTP/HTTPS
73
-
-**SSE** — Server-Sent Events for streaming
66
+
---
67
+
68
+
## Features
74
69
75
-
### Server Registry & Discovery
76
-
Browse and install servers from the built-in MCP registry. McpMux automatically discovers available tools, prompts, and resources from each connected server and caches them for offline access.
70
+
### One Dashboard for Everything
71
+
See all your servers, their connection status, available tools, and connected clients in one place. Install new servers from the registry with a click. View logs when something goes wrong.
77
72
78
-
### Feature Sets & Permissions
79
-
Create fine-grained permission bundles called **Feature Sets**to control which tools, prompts, and resources each client can access. Compose sets from other sets, include or exclude specific features, and assign them per client.
73
+
### Spaces — Switch Contexts Instantly
74
+
Working on multiple projects that need different servers? Create **Spaces**like "Work", "Personal", or "Client Project". Each Space has its own servers, credentials, and permissions. Switch between them in the sidebar — your AI clients follow automatically.
80
75
81
-
### Client Access Keys
82
-
Generate access keys for each AI client. Clients authenticate to the gateway using `MCP-Key` or `Bearer` tokens. Each client can be assigned different Feature Sets, giving you granular control over what each client can do.
76
+
### Credentials That Aren't in Plain Text
77
+
McpMux stores credentials in your **OS keychain** (macOS Keychain, Windows Credential Manager, Linux Secret Service). Database fields are encrypted with AES-256-GCM. No more API keys sitting in plain JSON files.
83
78
84
-
### Server Logging & Monitoring
85
-
Each server gets its own rotating log file with entries categorized by source (Connection, OAuth, Transport, MCP, Feature). View logs directly in the app's UI. Sensitive tokens are never written to logs.
79
+
### OAuth That Just Works
80
+
Remote MCP servers that require OAuth? McpMux handles the entire flow — browser-based login, token storage, and **automatic refresh** when tokens expire. You authenticate once and forget about it.
86
81
87
-
### System Tray & Auto-Start
88
-
McpMux runs in the system tray and can be configured to start automatically with your OS. The gateway keeps running in the background so your AI clients always have access to their tools.
82
+
### Server Registry
83
+
Browse, search, and install MCP servers from the built-in registry. Filter by category, see what tools each server provides, and install with one click. Servers you've used before are cached for offline access.
89
84
90
-
### Auto-Updates
91
-
Built-in update mechanism checks for new releases automatically. Updates are signed and verified before installation.
85
+
### Control What Each Client Can Access
86
+
Not every AI client should have access to every tool. Create **Feature Sets** — permission bundles that control which tools, prompts, and resources a client can see. Give Cursor full access but limit VS Code to read-only tools. It's up to you.
92
87
93
-
### Deep Linking
94
-
The `mcpmux://` URL scheme allows external applications to trigger actions in McpMux directly, such as initiating OAuth flows or installing servers.
88
+
### Runs in the Background
89
+
McpMux sits in your system tray and starts automatically with your OS. The gateway is always running, so your AI clients always have their tools available.
95
90
96
91
---
97
92
98
93
## Security
99
94
100
-
McpMux is designed with a defense-in-depth approach to credential and data security.
101
-
102
-
| Layer | Mechanism | Details |
103
-
|-------|-----------|---------|
104
-
|**Credential Storage**| OS Keychain | Master encryption key and JWT signing secret stored in platform-native secure storage |
105
-
|**Database Encryption**| AES-256-GCM | Field-level authenticated encryption with unique nonces per operation |
106
-
|**Memory Safety**| Zeroize | Sensitive data cleared from memory after use |
|**Network**| Local-only by default | Gateway binds to `127.0.0.1`; no external exposure |
110
-
|**TLS**| rustls | HTTPS support for remote server connections |
111
-
|**Logging**| Sanitized | Tokens and secrets are never written to log files |
112
-
|**Isolation**| Spaces | Credentials and configurations never leak between Spaces |
113
-
|**Sessions**| JWT (HS256) | Signed with 32-byte secret stored in OS keychain |
95
+
MCP's default approach is plain-text JSON config files with raw credentials. McpMux replaces that with proper security:
96
+
97
+
-**OS Keychain** — Encryption keys and secrets stored in your platform's native keychain, not on disk
98
+
-**AES-256-GCM Encryption** — Sensitive database fields are encrypted with authenticated encryption
99
+
-**Memory Zeroization** — Secrets are wiped from memory after use
100
+
-**OAuth 2.1 + PKCE** — Industry-standard auth flow for remote servers with automatic token refresh
101
+
-**Local-Only Gateway** — Binds to `127.0.0.1` only — nothing is exposed to the network
102
+
-**Per-Client Permissions** — Access keys and Feature Sets control what each client can do
103
+
-**Sanitized Logs** — Tokens and secrets never appear in log files
104
+
105
+
All MCP traffic stays on your machine. McpMux never routes tool calls through external services. Cloud sync (optional) only covers configuration metadata — never credentials or MCP payloads.
114
106
115
107
---
116
108
117
109
## Getting Started
118
110
119
-
### Download
111
+
### 1. Download McpMux
120
112
121
-
Download the latest release for your platform from the [Releases page](https://github.com/MCP-Mux/mcp-mux/releases):
113
+
Grab the latest release for your platform from the [Releases page](https://github.com/MCP-Mux/mcp-mux/releases):
122
114
123
115
| Platform | Format |
124
116
|----------|--------|
125
-
|**Windows**| MSI installer |
126
-
|**macOS**| DMG |
127
-
|**Linux**| DEB, RPM, AppImage |
117
+
| Windows | MSI installer |
118
+
| macOS | DMG |
119
+
| Linux | DEB, RPM, AppImage |
120
+
121
+
### 2. Add Your Servers
128
122
129
-
### Configure Your AI Client
123
+
Open McpMux and head to the **Discover** tab to browse the registry, or add servers manually via **My Servers → Add Server Manually**.
130
124
131
-
Once McpMux is running, point your AI client to the local gateway:
125
+
### 3. Connect Your AI Clients
126
+
127
+
Copy the gateway config from the Dashboard and paste it into your AI client's MCP settings:
132
128
133
129
```json
134
130
{
@@ -140,6 +136,8 @@ Once McpMux is running, point your AI client to the local gateway:
140
136
}
141
137
```
142
138
139
+
That's the last config file you'll need to touch.
140
+
143
141
---
144
142
145
143
## Development
@@ -150,120 +148,46 @@ Once McpMux is running, point your AI client to the local gateway:
150
148
-[Node.js](https://nodejs.org/) 18+
151
149
-[pnpm](https://pnpm.io/) 9+
152
150
153
-
**Linux additional dependencies** (for credential storage via Secret Service):
151
+
Linux also needs: `gnome-keyring libsecret-1-dev librsvg2-dev pkg-config`
0 commit comments