Skip to content

Commit 6a8d7a0

Browse files
its-mashits-mash
committed
docs: complete the end-to-end flow and update to workspace-driven routing
The getting-started guide stopped at "connect your client" and several docs still described the removed Follow-Active / per-client-grant model. - getting-started: add the missing steps — connection approval, folder → Space/FeatureSet routing (Workspaces), and @mux Tool Optimization — so the guide covers the full journey end to end. - clients: replace the obsolete "connection modes" and per-client grants with the current model — one-click OAuth approval + workspace-driven routing (tools decided by the folder the app reports, not the app). - spaces / gateway / index: fix the remaining Follow-Active references; the active Space is now the fallback for unmapped folders. Add Workspaces and Tool Optimization to the index Key Concepts. Validated by building discover.ui against these docs (164 pages, all cross-links and screenshots resolve). Signed-off-by: Mohammod Al Amin Ashik <maa.ashik00@gmail.com>
1 parent 25a6fbb commit 6a8d7a0

5 files changed

Lines changed: 104 additions & 159 deletions

File tree

‎docs/guide/clients.mdx‎

Lines changed: 29 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
---
2-
title: Clients — AI Application Management
3-
description: Connect Cursor, Claude Desktop, VS Code, Windsurf, and other AI clients to McpMux. Configure connection modes and per-Space permissions for each client.
2+
title: Clients — Connected AI Apps
3+
description: Connect Cursor, Claude Desktop, VS Code, Windsurf, and other AI clients to McpMux. Approve them with one click, and let workspace-driven routing decide each app's tools by the folder it has open.
44
---
55

6-
Clients are the AI applications that connect to McpMux's gateway to access MCP tools, resources, and prompts. McpMux lets you manage each client independently with its own permissions and Space behavior.
6+
Clients are the AI applications that connect to McpMux's gateway to access MCP tools, resources, and prompts. McpMux registers each app with a one-click approval, then **routes its tools by the folder it has open** — not by the app itself.
77

8-
## Supported Clients
8+
## Supported clients
99

1010
McpMux works with any MCP-compatible client, including:
1111

@@ -23,79 +23,50 @@ McpMux works with any MCP-compatible client, including:
2323

2424
All clients connect to the same endpoint: `http://localhost:45818/mcp`
2525

26-
![Authorization Request dialog — VS Code connecting to McpMux with connection mode selection](https://mcpmux.com/screenshots/clients.png)
26+
## Connecting and approval
2727

28-
## Connection Modes
28+
When a new client connects to the gateway, McpMux prompts you to **approve it** with one click. Approving registers the app and completes an **OAuth 2.1 + PKCE** handshake; its access key is stored in your OS keychain. (VS Code and Cursor can be connected in one click from the Home dashboard; other clients paste the gateway URL — see [Getting Started](/docs/getting-started/).)
2929

30-
Each client has a **connection mode** that determines how it interacts with Spaces:
30+
![Approve a new app connecting to the gateway](https://mcpmux.com/screenshots/clients.png)
3131

32-
### Follow Active
32+
## How routing works — workspace-driven
3333

34-
The client automatically uses whichever Space is currently active. When you switch the active Space, the client immediately sees the new Space's servers and tools.
34+
The tools an app sees are decided by the **folder it reports** (its MCP workspace root), resolved through a [Workspace](/docs/workspaces/) mapping — **not** configured per app. This means:
3535

36-
**Best for:** Your primary development tools that should always match your current context.
36+
- Open your **backend repo** in any IDE and it sees your database and deploy tools; open a **docs folder** and it sees only search and filesystem.
37+
- Two different apps (say Cursor and VS Code) opening the **same folder** get the **same tools** — routing follows the folder, not the app's identity.
38+
- A session with **no reported folder** falls through to the **active Space's** FeatureSet.
3739

38-
### Locked
40+
To control an app's tools, map its folder in the **Workspaces** tab (or let the AI do it with [Tool Optimization](/docs/tool-optimization/)) rather than configuring the app itself.
3941

40-
The client always uses a specific Space, regardless of which Space is active. This is useful for:
42+
![A connected app — its toolset is decided by the Workspace binding for the folder it reports](https://mcpmux.com/screenshots/client-detail.png)
4143

42-
- A monitoring tool that should always see production servers
43-
- A client dedicated to a specific project
44-
- Background automation that shouldn't change behavior
44+
Open any app to see how it's currently routed and exactly which tools, prompts, and resources resolve for it.
4545

46-
### Ask on Change
46+
![Effective features resolved for a connected app](https://mcpmux.com/screenshots/client-permissions.png)
4747

48-
When the active Space changes, McpMux prompts you to confirm whether this client should switch too. This provides a safety net for important clients.
49-
50-
**Best for:** Clients with elevated permissions where an accidental Space switch could be problematic.
51-
52-
## Per-Space Permissions
53-
54-
Each client receives **FeatureSet grants** per Space. This means a single client can have different permissions in different Spaces:
55-
56-
| Client | Work Space | Personal Space |
57-
|--------|-----------|---------------|
58-
| Cursor | All tools | Read Only |
59-
| Claude Desktop | Developer FeatureSet | All tools |
60-
| Monitoring Bot | Read Only | — (no access) |
61-
62-
This is configured in the **Clients** page by selecting a client and managing its grants for each Space.
63-
64-
![Client detail panel — Cursor with per-Space FeatureSet grants and permission management](https://mcpmux.com/screenshots/client-detail.png)
65-
66-
## Access Keys
48+
## Access keys
6749

6850
Each client authenticates with McpMux using an **access key**. Access keys are:
6951

70-
- Generated automatically when a client registers
52+
- Issued automatically through the OAuth approval when a client registers
7153
- Stored encrypted in the OS keychain
7254
- Unique per client
7355
- Revocable at any time
7456

75-
## Client Lifecycle
76-
77-
### Registration
78-
79-
Clients can be registered in two ways:
80-
81-
1. **Automatic** — when a new client connects to the gateway via OAuth, McpMux prompts you to approve it
82-
2. **Manual** — add a client through the McpMux UI and copy the access key into your client's configuration
83-
84-
![Effective Features view showing 45 tools, 8 prompts, and 3 resources available to Cursor](https://mcpmux.com/screenshots/client-permissions.png)
85-
86-
### Monitoring
57+
## Managing connected apps
8758

88-
The **Clients** page shows:
89-
- Each registered client's name and type
90-
- Connection mode (Follow Active / Locked / Ask on Change)
91-
- Last seen timestamp
59+
The **Apps** page shows every app connected to your gateway in real time:
9260

93-
### Disconnecting
61+
- Each app's name, type, and live status
62+
- How it's routed (which folder → which Space + FeatureSet)
63+
- Last-seen timestamp
9464

95-
You can disconnect or remove a client at any time from the Clients page. This revokes its access key and it will no longer be able to make MCP requests through the gateway.
65+
From there you can **rename** an app, inspect its routing, or **revoke** it — revoking removes its access key so it can no longer make requests through the gateway.
9666

97-
## Next Steps
67+
## Next steps
9868

99-
- [Configure FeatureSets](/docs/feature-sets/) to build permission bundles for your clients
100-
- [Learn about Spaces](/docs/spaces/) to understand how connection modes interact with workspaces
101-
- [Set up the Gateway](/docs/gateway/) to understand how client requests are routed
69+
- [Workspaces](/docs/workspaces/) — map each folder to the toolset it should get
70+
- [FeatureSets](/docs/feature-sets/) — build the tool bundles a folder resolves to
71+
- [Tool Optimization](/docs/tool-optimization/) — let an app curate its own toolset from chat
72+
- [Gateway](/docs/gateway/) — how client requests are authenticated and routed

‎docs/guide/gateway.mdx‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -19,11 +19,10 @@ ChatGPT ─────────┘ ├──→ PostgreS
1919
The gateway receives MCP JSON-RPC requests from clients and:
2020

2121
1. **Authenticates** the client using its access key
22-
2. **Resolves** which Space the client should use (based on connection mode)
23-
3. **Collects** the client's FeatureSet grants for that Space
24-
4. **Filters** the available tools, resources, and prompts based on permissions
25-
5. **Routes** each request to the correct backend MCP server
26-
6. **Returns** the response to the client
22+
2. **Resolves** the session's folder (its workspace root) to a Space + FeatureSet via the matching [Workspace](/docs/workspaces/) binding — falling back to the active Space when no folder is reported
23+
3. **Filters** the available tools, resources, and prompts to that resolved FeatureSet
24+
4. **Routes** each request to the correct backend MCP server
25+
5. **Returns** the response to the client
2726

2827
## Request Routing
2928

‎docs/guide/getting-started.mdx‎

Lines changed: 55 additions & 89 deletions
Original file line numberDiff line numberDiff line change
@@ -1,79 +1,49 @@
11
---
22
title: Getting Started with McpMux
3-
description: Download McpMux, install your first MCP server, and connect Cursor, Claude, or VS Code in under 5 minutes. Step-by-step setup guide.
3+
description: Download McpMux, install an MCP server, connect Cursor/Claude/VS Code, approve the connection, route each folder to the right tools, and let the AI optimize its own toolset. Full step-by-step setup.
44
---
55

6-
Get McpMux running and connect your first AI client in just a few steps.
6+
Get McpMux running, connect your first AI client, and dial in exactly the tools it sees — in a few minutes.
77

88
## Prerequisites
99

1010
- **Operating System**: Windows 10+, macOS 12+, or Linux (Ubuntu 20.04+, Fedora 38+)
11-
- **AI Client**: At least one MCP-compatible client installed (Cursor, Claude Desktop, VS Code, etc.)
11+
- **AI Client**: At least one MCP-compatible client installed (Cursor, Claude Desktop, VS Code, Windsurf, …)
1212

13-
## Step 1: Download and Install
13+
## Step 1: Download and install
1414

1515
Download McpMux for your platform from the [download page](/download/).
1616

17-
- **Windows**: Run the `.msi` installer
18-
- **macOS**: Open the `.dmg` and drag McpMux to Applications
19-
- **Linux**: Install via `.deb`, `.rpm`, or `.AppImage`
17+
- **Windows**: run the installer (`.msi` or `.exe`)
18+
- **macOS**: open the `.dmg` and drag McpMux to Applications
19+
- **Linux**: install via `.deb`, `.rpm`, or `.AppImage`
2020

21-
McpMux runs in the system tray — look for the McpMux icon after installation.
21+
McpMux runs in the system tray — look for its icon after launch. A default **Space** (an isolated environment for servers + credentials) is created for you; you can add more later for work/personal/per-client separation. See [Spaces](/docs/spaces/).
2222

23-
## Step 2: Create a Space
23+
## Step 2: Install a server from the registry
2424

25-
When you first open McpMux, a default Space is created for you. Spaces are isolated environments with their own server configurations and credentials.
25+
Open **Discover** in McpMux (or browse the [registry](/) on this site) and click **Install** on any of 100+ servers — GitHub, Filesystem, Postgres, Slack, Brave Search, and more. It's added to your active Space.
2626

27-
You can create additional Spaces later for different contexts:
28-
- **Work** — company tools with work credentials
29-
- **Personal** — side projects with personal API keys
30-
- **Client-A** — isolated environment for a specific client
27+
![Discover — browse, search, and install MCP servers from the registry](https://mcpmux.com/screenshots/discover.png)
3128

32-
To create a Space, go to the **Spaces** page and click **Create Space**.
29+
## Step 3: Configure credentials
3330

34-
![Space switcher in the sidebar lets you quickly switch between workspaces](https://mcpmux.com/screenshots/space-switcher.png)
31+
If a server needs authentication, a configuration dialog opens after installation. Fill in the fields and **Save** — the Save/Cancel buttons stay pinned at the bottom no matter how long the form is.
3532

36-
## Step 3: Browse and Install a Server
33+
- Secrets are encrypted with AES-256-GCM and stored in your OS keychain — never in plain-text files.
34+
- Use the **obtain** link (when provided) to jump straight to the service's token page.
3735

38-
Navigate to **Discover Servers** in McpMux or browse the [server registry](/) on this website. You'll find 100+ MCP servers for popular tools.
36+
See [Server Management](/docs/servers/) for all options.
3937

40-
![Discover Servers page — browse, search, and install MCP servers from the registry](https://mcpmux.com/screenshots/discover.png)
38+
## Step 4: Start the gateway
4139

42-
Click **Install** on any server to add it to your active Space. Popular choices to start with:
40+
On the **Home** dashboard, start the gateway. It listens on `localhost:45818` and connects your enabled servers (🟡 connecting → 🟢 connected → 🔴 error).
4341

44-
- **Filesystem** — read and write local files
45-
- **GitHub** — interact with repositories, issues, and PRs
46-
- **Brave Search** — web search capabilities
47-
- **Playwright** — browser automation
42+
![Home — gateway running on localhost:45818 with server stats and one-click client connect](https://mcpmux.com/screenshots/dashboard.png)
4843

49-
## Step 4: Configure Credentials
44+
## Step 5: Connect your AI client
5045

51-
If the server requires authentication (API keys, tokens, etc.), a configuration dialog appears automatically after installation. Fill in the required fields:
52-
53-
- **API keys** are stored encrypted using AES-256-GCM — they never touch disk in plaintext
54-
- Click the **obtain** link (if provided) to go directly to the service's token creation page
55-
- Sensitive fields are masked in the UI and stored in the OS keychain
56-
57-
See [Server Management](/docs/servers/) for details on all configuration options.
58-
59-
## Step 5: Start the Gateway
60-
61-
Go to the **Dashboard** and click **Start Gateway**. The gateway starts on `localhost:45818` and begins connecting to your enabled servers.
62-
63-
![Dashboard with gateway running and connected servers](https://mcpmux.com/screenshots/dashboard.png)
64-
65-
You'll see server status indicators change:
66-
- 🟡 **Connecting** — establishing MCP handshake
67-
- 🟢 **Connected** — ready to serve requests
68-
- 🔴 **Error** — check server logs for details
69-
70-
## Step 6: Connect Your AI Client
71-
72-
Configure your AI client to connect to McpMux's gateway endpoint. The exact setup depends on your client:
73-
74-
### Cursor
75-
76-
Add to your Cursor MCP settings (`.cursor/mcp.json`):
46+
**VS Code** and **Cursor** are one-click from the Home dashboard's *Connect a client* row. For everything else, point the client at the gateway endpoint:
7747

7848
```json
7949
{
@@ -85,53 +55,49 @@ Add to your Cursor MCP settings (`.cursor/mcp.json`):
8555
}
8656
```
8757

88-
### Claude Desktop
58+
- **Cursor** → `.cursor/mcp.json` · **Claude Desktop** → `claude_desktop_config.json` · **Windsurf** → use `"serverUrl"` instead of `"url"`
59+
- **VS Code (Copilot)** → `.vscode/mcp.json` under a `"servers"` key
8960

90-
Add to your Claude Desktop config (`claude_desktop_config.json`):
61+
## Step 6: Approve the connection
9162

92-
```json
93-
{
94-
"mcpServers": {
95-
"mcpmux": {
96-
"url": "http://localhost:45818/mcp"
97-
}
98-
}
99-
}
100-
```
63+
The first time a client connects, McpMux pops a **one-click approval** — *"Allow VS Code to connect?"*. Approve it and the app is registered: it authenticates over OAuth 2.1 + PKCE and gets an access key stored in your OS keychain.
10164

102-
### VS Code (Copilot)
65+
![Approve a new app connecting to the gateway](https://mcpmux.com/screenshots/clients.png)
10366

104-
Add to your VS Code settings (`.vscode/mcp.json`):
67+
You can rename, inspect, or revoke any connected app later from the **Apps** page. See [Clients](/docs/clients/).
10568

106-
```json
107-
{
108-
"servers": {
109-
"mcpmux": {
110-
"url": "http://localhost:45818/mcp"
111-
}
112-
}
113-
}
114-
```
69+
## Step 7: Route the folder to the right tools
11570

116-
### Windsurf
71+
This is the key idea: **McpMux decides which tools a session gets from the folder the client has open** (its workspace root) — not from the app itself. Two IDEs in the same folder see the same tools.
11772

118-
Add to your Windsurf MCP configuration:
73+
- **By default**, a session uses the active Space's FeatureSet.
74+
- **Map a folder** to a specific Space + FeatureSet in the **Workspaces** tab: open your backend repo and the AI sees your database and deploy tools; open a docs folder and it sees only search and filesystem. Matching is per-folder and exact, so nothing leaks across projects.
11975

120-
```json
121-
{
122-
"mcpServers": {
123-
"mcpmux": {
124-
"serverUrl": "http://localhost:45818/mcp"
125-
}
126-
}
127-
}
128-
```
76+
![Workspaces — map a project folder to the Space and FeatureSet it should get](https://mcpmux.com/screenshots/workspaces.png)
77+
78+
See [Workspaces](/docs/workspaces/) for routing and [FeatureSets](/docs/feature-sets/) for building the tool bundles a folder resolves to.
79+
80+
## Step 8: Let your AI curate its own toolset
81+
82+
Don't want to map folders by hand? In your AI client, start a request with **`@mux`**:
83+
84+
> *"@mux optimize this folder."*
85+
86+
The assistant discovers what's available, composes a focused FeatureSet of just the tools it needs, and pins it to the folder — so every future session there resolves to exactly those tools. Read operations run silently; anything that changes your setup pops a **one-click approval** that names the exact Space.
87+
88+
![Tool Optimization — the built-in @mux tools the AI drives, reads silent and writes gated](https://mcpmux.com/screenshots/tool-optimization.png)
89+
90+
See [Tool Optimization](/docs/tool-optimization/).
91+
92+
## You're set
12993

130-
Once connected, your AI client can access all the tools, resources, and prompts from every enabled MCP server — through the single McpMux gateway endpoint.
94+
One gateway for every client, credentials encrypted in your keychain, the **folder** decides the tools, and the AI can tune its own toolset with `@mux`.
13195

13296
## Next Steps
13397

134-
- [Learn about Spaces](/docs/spaces/) to organize your environments
135-
- [Configure FeatureSets](/docs/feature-sets/) to control tool permissions
136-
- [Browse the server registry](/) to find more MCP servers
137-
- [Understand security](/docs/security/) and how McpMux protects your credentials
98+
- [Spaces](/docs/spaces/) — isolate work, personal, and client contexts
99+
- [Workspaces](/docs/workspaces/) — route each folder to its own toolset
100+
- [FeatureSets](/docs/feature-sets/) — curate exactly which tools, prompts, and resources are exposed
101+
- [Tool Optimization](/docs/tool-optimization/) — let the AI keep its toolset lean
102+
- [Clients](/docs/clients/) — manage and revoke connected apps
103+
- [Security](/docs/security/) — how McpMux protects your credentials

‎docs/guide/index.mdx‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -43,13 +43,21 @@ McpMux sits between your AI clients and your MCP servers. It handles:
4343

4444
Isolated workspaces with separate server configurations and credentials. Keep your work GitHub token completely separate from your personal one.
4545

46+
### [Workspaces](/docs/workspaces/)
47+
48+
Folder-based routing. Map a project folder to a Space + FeatureSet so each session resolves to exactly the tools that folder should get — automatically, per folder.
49+
4650
### [FeatureSets](/docs/feature-sets/)
4751

48-
Permission bundles that control which MCP tools, resources, and prompts each AI client can access. Create read-only views, role-based access, or domain-specific bundles.
52+
Permission bundles that control which MCP tools, resources, and prompts a session can access. Create read-only views, role-based access, or domain-specific bundles.
53+
54+
### [Tool Optimization](/docs/tool-optimization/)
55+
56+
Built-in `@mux` meta-tools that let the AI curate its own toolset from chat — discover, compose, and pin a focused set, with writes gated by a one-click approval.
4957

5058
### [Clients](/docs/clients/)
5159

52-
AI applications connected to McpMux. Configure connection modes (follow active Space, lock to a Space, or ask on change) and assign permissions per Space.
60+
AI applications connected to McpMux. Approve each with one click; their tools are decided by the folder they open via workspace-driven routing, not configured per app.
5361

5462
### [Servers](/docs/servers/)
5563

0 commit comments

Comments
 (0)