Skip to content

Commit d77455c

Browse files
its-mashits-mash
committed
docs: add user guide with 9 MDX pages and screenshots
Adds comprehensive documentation covering McpMux concepts (Spaces, FeatureSets, Clients, Gateway, Security), getting started guide, server management, and server definition schema reference. Content is sourced by mcpmux.discover.ui at build time via fetch-docs.mjs and rendered with Fumadocs on mcpmux.com/docs. Includes GitHub Action to trigger Cloudflare Pages rebuild when docs change on main. Signed-off-by: Mohammod Al Amin Ashik <maa.ashik00@gmail.com>
1 parent bec7699 commit d77455c

11 files changed

Lines changed: 1331 additions & 0 deletions

File tree

‎.github/workflows/docs-deploy.yml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
name: Deploy Docs
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- 'docs/guide/**'
8+
9+
# Restrict permissions to minimum needed
10+
permissions: {}
11+
12+
jobs:
13+
trigger-deploy:
14+
runs-on: ubuntu-latest
15+
# Only run for pushes by repo collaborators, not automated merges from unknown sources
16+
if: github.repository == 'mcpmux/mcp-mux'
17+
steps:
18+
- name: Trigger mcpmux.com rebuild
19+
run: |
20+
curl -s -X POST "$CF_PAGES_DEPLOY_HOOK"
21+
env:
22+
CF_PAGES_DEPLOY_HOOK: ${{ secrets.CF_PAGES_DEPLOY_HOOK }}

‎docs/guide/clients.mdx‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
---
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.
4+
---
5+
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.
7+
8+
## Supported Clients
9+
10+
McpMux works with any MCP-compatible client, including:
11+
12+
| Client | Type | Connection |
13+
|--------|------|-----------|
14+
| Cursor | IDE | Streamable HTTP |
15+
| Claude Desktop | Desktop App | Streamable HTTP |
16+
| Claude Code | CLI | Streamable HTTP |
17+
| VS Code (Copilot) | IDE | Streamable HTTP |
18+
| ChatGPT Desktop | Desktop App | Streamable HTTP |
19+
| Windsurf | IDE | Streamable HTTP |
20+
| JetBrains IDEs | IDE | Streamable HTTP |
21+
| Zed | Editor | Streamable HTTP |
22+
| Gemini CLI | CLI | Streamable HTTP |
23+
24+
All clients connect to the same endpoint: `http://localhost:45818/mcp`
25+
26+
![Authorization Request dialog — VS Code connecting to McpMux with connection mode selection](/screenshots/clients.png)
27+
28+
## Connection Modes
29+
30+
Each client has a **connection mode** that determines how it interacts with Spaces:
31+
32+
### Follow Active
33+
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.
35+
36+
**Best for:** Your primary development tools that should always match your current context.
37+
38+
### Locked
39+
40+
The client always uses a specific Space, regardless of which Space is active. This is useful for:
41+
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
45+
46+
### Ask on Change
47+
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](/screenshots/client-detail.png)
65+
66+
## Access Keys
67+
68+
Each client authenticates with McpMux using an **access key**. Access keys are:
69+
70+
- Generated automatically when a client registers
71+
- Stored encrypted in the OS keychain
72+
- Unique per client
73+
- Revocable at any time
74+
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](/screenshots/client-permissions.png)
85+
86+
### Monitoring
87+
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
92+
93+
### Disconnecting
94+
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.
96+
97+
## Next Steps
98+
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

‎docs/guide/feature-sets.mdx‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
---
2+
title: FeatureSets — Permission Control
3+
description: FeatureSets control which MCP tools, resources, and prompts each AI client can access in McpMux. Create role-based permissions, domain bundles, or read-only views.
4+
---
5+
6+
FeatureSets are permission bundles that control what MCP capabilities (tools, resources, and prompts) each AI client can access. They let you grant fine-grained permissions per client, per Space.
7+
8+
## Why FeatureSets
9+
10+
Without permission control, every AI client connected through the gateway can access every tool from every server. This creates risks:
11+
12+
- A junior developer's client could access destructive database tools
13+
- An experimental AI agent could call deployment tools
14+
- A read-only analysis tool could accidentally modify production data
15+
16+
FeatureSets solve this by letting you define exactly what each client can do.
17+
18+
![FeatureSets page showing All Features, Default, Custom (Cloudflare Workers, Full Stack Dev, React Development, Read Only)](/screenshots/featuresets.png)
19+
20+
## FeatureSet Types
21+
22+
McpMux creates and manages four types of FeatureSets:
23+
24+
### All
25+
26+
Grants access to **every tool, resource, and prompt** from every connected server in the Space. Use this for fully trusted clients.
27+
28+
### Default
29+
30+
Automatically granted to **all clients** in the Space. Define a baseline set of capabilities that every client gets. You can still add more FeatureSets on top for specific clients.
31+
32+
### ServerAll
33+
34+
Automatically created when a server first connects. Grants access to **all features from that specific server**. For example, when you enable the GitHub server, McpMux creates a "GitHub — All" FeatureSet containing all of GitHub's tools and resources.
35+
36+
### Custom
37+
38+
User-defined FeatureSets with manually selected features. This is where you build your own permission bundles.
39+
40+
## Include and Exclude
41+
42+
Each FeatureSet member can be set to **include** or **exclude** mode:
43+
44+
- **Include** — add this tool/resource/prompt to the set
45+
- **Exclude** — remove this tool/resource/prompt from the set
46+
47+
Exclude rules always win over include rules. This means you can create a permissive base and then remove specific dangerous tools:
48+
49+
**Example:** "All GitHub except delete operations"
50+
1. Include the **GitHub — All** ServerAll FeatureSet
51+
2. Exclude `delete_repository`, `delete_branch`, `delete_file`
52+
53+
## Composition
54+
55+
FeatureSets can **contain other FeatureSets**. This lets you build hierarchical permission structures:
56+
57+
- **"Read Only"** = Include tools that only read data from multiple servers
58+
- **"Android Development"** = Include "GitHub — All" + "Firebase — All" + specific Gradle tools
59+
- **"Senior Developer"** = Include "All" but exclude deployment and infrastructure tools
60+
- **"Intern"** = Include "Read Only" + specific write tools for their assigned project
61+
62+
## Common Use Cases
63+
64+
### Role-Based Access
65+
66+
| FeatureSet | Contains |
67+
|-----------|----------|
68+
| Read Only | Search, list, and read tools only |
69+
| Developer | Read Only + code editing + PR management |
70+
| DevOps | Developer + deployment + infrastructure |
71+
| Admin | All capabilities |
72+
73+
### Domain Bundles
74+
75+
| FeatureSet | Contains |
76+
|-----------|----------|
77+
| Frontend | Browser tools + CSS/JS linting + design system resources |
78+
| Backend | Database queries + API testing + log analysis |
79+
| Full Stack | Frontend + Backend |
80+
81+
### Safety Limits
82+
83+
| FeatureSet | Contains |
84+
|-----------|----------|
85+
| No Delete | All minus any delete/remove/drop operations |
86+
| No Deploy | All minus CI/CD and deployment tools |
87+
| Sandbox | Only filesystem (read) + search + documentation |
88+
89+
## Managing FeatureSets
90+
91+
![React Development FeatureSet — configuring included features from each server](/screenshots/featureset-detail.png)
92+
93+
### Creating a Custom FeatureSet
94+
95+
1. Go to the **FeatureSets** page
96+
2. Click **Create FeatureSet**
97+
3. Give it a name and optional description
98+
4. Add members — select features or other FeatureSets
99+
5. Set each member to include or exclude mode
100+
101+
### Assigning to Clients
102+
103+
FeatureSets are assigned to clients per Space. Go to the **Clients** page, select a client, and manage its FeatureSet grants for each Space.
104+
105+
A client's effective permissions are the combination of all its granted FeatureSets, with exclude rules taking priority.
106+
107+
## Next Steps
108+
109+
- [Set up Clients](/docs/clients/) and assign FeatureSets per Space
110+
- [Learn about Spaces](/docs/spaces/) for environment isolation
111+
- [Understand the Gateway](/docs/gateway/) to see how permissions are enforced at request time

‎docs/guide/gateway.mdx‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
---
2+
title: Gateway — Local MCP Proxy
3+
description: The McpMux Gateway runs on localhost:45818 and routes MCP requests from AI clients to the correct servers with automatic authentication and permission filtering.
4+
---
5+
6+
The **Gateway** is the core of McpMux — a local HTTP server that acts as a single entry point for all your AI clients. Instead of configuring each client to connect to each MCP server individually, every client connects to the gateway at `http://localhost:45818/mcp`.
7+
8+
## How It Works
9+
10+
```
11+
Cursor ──────────┐
12+
Claude Desktop ──┤
13+
VS Code ─────────┤──→ McpMux Gateway ──┬──→ GitHub Server
14+
Windsurf ────────┤ (localhost:45818) ├──→ Slack Server
15+
ChatGPT ─────────┘ ├──→ PostgreSQL Server
16+
└──→ Filesystem Server
17+
```
18+
19+
The gateway receives MCP JSON-RPC requests from clients and:
20+
21+
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
27+
28+
## Request Routing
29+
30+
When a client calls a tool (e.g., `github_create_issue`), the gateway:
31+
32+
1. Looks up which server provides that tool
33+
2. Checks that the client has permission to use it (via FeatureSets)
34+
3. Forwards the request to the server's active connection
35+
4. Returns the server's response to the client
36+
37+
Clients only see tools they have permission to use. If a FeatureSet excludes a tool, the client doesn't even know it exists — it won't appear in `tools/list` responses.
38+
39+
## FeatureSet Filtering
40+
41+
The gateway enforces permissions at the protocol level:
42+
43+
- **`tools/list`** — only returns tools the client is permitted to use
44+
- **`tools/call`** — rejects calls to tools the client doesn't have access to
45+
- **`resources/list`** — only returns permitted resources
46+
- **`prompts/list`** — only returns permitted prompts
47+
48+
This means you can have multiple clients connected to the same gateway with different levels of access, all managed through FeatureSets.
49+
50+
## OAuth Token Management
51+
52+
For servers that use OAuth 2.1 + PKCE authentication, the gateway handles the full token lifecycle:
53+
54+
- **Initial authorization** — opens a browser for you to log in and grant permissions
55+
- **Token storage** — tokens are encrypted and stored in the OS keychain
56+
- **Automatic refresh** — when a token expires, the gateway refreshes it transparently
57+
- **Re-authorization** — if a refresh fails, McpMux prompts you to re-authenticate
58+
59+
You never need to manually manage OAuth tokens — the gateway takes care of it.
60+
61+
## Connection Pooling
62+
63+
The gateway maintains a pool of connections to backend MCP servers:
64+
65+
- Each server gets a connection based on its configuration and credentials
66+
- Connections are reused across clients (when they share the same Space and credentials)
67+
- The pool key is computed from `server_id + sha256(final_config_with_credentials)`
68+
- When credentials change (e.g., token refresh), a new connection is created with the updated credentials
69+
- Idle connections are cleaned up after a configurable timeout
70+
71+
This means if two clients in the same Space both use the GitHub server, they share a single connection to GitHub — reducing resource usage.
72+
73+
![Dashboard showing gateway running on localhost:45818 with server stats and client configuration](/screenshots/dashboard.png)
74+
75+
## Starting and Stopping
76+
77+
Control the gateway from the **Dashboard** in McpMux:
78+
79+
- **Start Gateway** — begins listening on `localhost:45818` and connects to enabled servers
80+
- **Stop Gateway** — disconnects all servers and stops accepting requests
81+
82+
The gateway also starts automatically when McpMux launches (configurable in Settings).
83+
84+
## Gateway Status
85+
86+
The dashboard shows real-time gateway status:
87+
88+
- **Running** / **Stopped** — whether the gateway is accepting connections
89+
- **Connected Servers** — count of actively connected backend servers
90+
- **Registered Clients** — count of AI clients that have connected
91+
92+
## Next Steps
93+
94+
- [Set up Clients](/docs/clients/) to connect your AI applications
95+
- [Configure FeatureSets](/docs/feature-sets/) to control what each client can access
96+
- [Manage Servers](/docs/servers/) to add and configure backend MCP servers
97+
- [Learn about Security](/docs/security/) to understand how the gateway protects your credentials

0 commit comments

Comments
 (0)