mcpmux · its-mash · Feb 20, 2026 · Feb 19, 2026 · Feb 20, 2026 · Feb 20, 2026
@@ -0,0 +1,22 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/guide/**'
+
+# Restrict permissions to minimum needed
+permissions: {}
+
+jobs:
+  trigger-deploy:
+    runs-on: ubuntu-latest
+    # Only run for pushes by repo collaborators, not automated merges from unknown sources
+    if: github.repository == 'mcpmux/mcp-mux'
+    steps:
+      - name: Trigger mcpmux.com rebuild
+        run: |
+          curl -s -X POST "$CF_PAGES_DEPLOY_HOOK"
+        env:
+          CF_PAGES_DEPLOY_HOOK: ${{ secrets.CF_PAGES_DEPLOY_HOOK }}
@@ -0,0 +1,101 @@
+---
+title: Clients — AI Application Management
+description: Connect Cursor, Claude Desktop, VS Code, Windsurf, and other AI clients to McpMux. Configure connection modes and per-Space permissions for each client.
+---
+
+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.
+
+## Supported Clients
+
+McpMux works with any MCP-compatible client, including:
+
+| Client | Type | Connection |
+|--------|------|-----------|
+| Cursor | IDE | Streamable HTTP |
+| Claude Desktop | Desktop App | Streamable HTTP |
+| Claude Code | CLI | Streamable HTTP |
+| VS Code (Copilot) | IDE | Streamable HTTP |
+| ChatGPT Desktop | Desktop App | Streamable HTTP |
+| Windsurf | IDE | Streamable HTTP |
+| JetBrains IDEs | IDE | Streamable HTTP |
+| Zed | Editor | Streamable HTTP |
+| Gemini CLI | CLI | Streamable HTTP |
+
+All clients connect to the same endpoint: `http://localhost:45818/mcp`
+
+![Authorization Request dialog — VS Code connecting to McpMux with connection mode selection](/screenshots/clients.png)
+
+## Connection Modes
+
+Each client has a **connection mode** that determines how it interacts with Spaces:
+
+### Follow Active
+
+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.
+
+**Best for:** Your primary development tools that should always match your current context.
+
+### Locked
+
+The client always uses a specific Space, regardless of which Space is active. This is useful for:
+
+- A monitoring tool that should always see production servers
+- A client dedicated to a specific project
+- Background automation that shouldn't change behavior
+
+### Ask on Change
+
+When the active Space changes, McpMux prompts you to confirm whether this client should switch too. This provides a safety net for important clients.
+
+**Best for:** Clients with elevated permissions where an accidental Space switch could be problematic.
+
+## Per-Space Permissions
+
+Each client receives **FeatureSet grants** per Space. This means a single client can have different permissions in different Spaces:
+
+| Client | Work Space | Personal Space |
+|--------|-----------|---------------|
+| Cursor | All tools | Read Only |
+| Claude Desktop | Developer FeatureSet | All tools |
+| Monitoring Bot | Read Only | — (no access) |
+
+This is configured in the **Clients** page by selecting a client and managing its grants for each Space.
+
+![Client detail panel — Cursor with per-Space FeatureSet grants and permission management](/screenshots/client-detail.png)
+
+## Access Keys
+
+Each client authenticates with McpMux using an **access key**. Access keys are:
+
+- Generated automatically when a client registers
+- Stored encrypted in the OS keychain
+- Unique per client
+- Revocable at any time
+
+## Client Lifecycle
+
+### Registration
+
+Clients can be registered in two ways:
+
+1. **Automatic** — when a new client connects to the gateway via OAuth, McpMux prompts you to approve it
+2. **Manual** — add a client through the McpMux UI and copy the access key into your client's configuration
+
+![Effective Features view showing 45 tools, 8 prompts, and 3 resources available to Cursor](/screenshots/client-permissions.png)
+
+### Monitoring
+
+The **Clients** page shows:
+- Each registered client's name and type
+- Connection mode (Follow Active / Locked / Ask on Change)
+- Last seen timestamp
+
+### Disconnecting
+
+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.
+
+## Next Steps
+
+- [Configure FeatureSets](/docs/feature-sets/) to build permission bundles for your clients
+- [Learn about Spaces](/docs/spaces/) to understand how connection modes interact with workspaces
+- [Set up the Gateway](/docs/gateway/) to understand how client requests are routed
@@ -0,0 +1,111 @@
+---
+title: FeatureSets — Permission Control
+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.
+---
+
+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.
+
+## Why FeatureSets
+
+Without permission control, every AI client connected through the gateway can access every tool from every server. This creates risks:
+
+- A junior developer's client could access destructive database tools
+- An experimental AI agent could call deployment tools
+- A read-only analysis tool could accidentally modify production data
+
+FeatureSets solve this by letting you define exactly what each client can do.
+
+![FeatureSets page showing All Features, Default, Custom (Cloudflare Workers, Full Stack Dev, React Development, Read Only)](/screenshots/featuresets.png)
+
+## FeatureSet Types
+
+McpMux creates and manages four types of FeatureSets:
+
+### All
+
+Grants access to **every tool, resource, and prompt** from every connected server in the Space. Use this for fully trusted clients.
+
+### Default
+
+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.
+
+### ServerAll
+
+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.
+
+### Custom
+
+User-defined FeatureSets with manually selected features. This is where you build your own permission bundles.
+
+## Include and Exclude
+
+Each FeatureSet member can be set to **include** or **exclude** mode:
+
+- **Include** — add this tool/resource/prompt to the set
+- **Exclude** — remove this tool/resource/prompt from the set
+
+Exclude rules always win over include rules. This means you can create a permissive base and then remove specific dangerous tools:
+
+**Example:** "All GitHub except delete operations"
+1. Include the **GitHub — All** ServerAll FeatureSet
+2. Exclude `delete_repository`, `delete_branch`, `delete_file`
+
+## Composition
+
+FeatureSets can **contain other FeatureSets**. This lets you build hierarchical permission structures:
+
+- **"Read Only"** = Include tools that only read data from multiple servers
+- **"Android Development"** = Include "GitHub — All" + "Firebase — All" + specific Gradle tools
+- **"Senior Developer"** = Include "All" but exclude deployment and infrastructure tools
+- **"Intern"** = Include "Read Only" + specific write tools for their assigned project
+
+## Common Use Cases
+
+### Role-Based Access
+
+| FeatureSet | Contains |
+|-----------|----------|
+| Read Only | Search, list, and read tools only |
+| Developer | Read Only + code editing + PR management |
+| DevOps | Developer + deployment + infrastructure |
+| Admin | All capabilities |
+
+### Domain Bundles
+
+| FeatureSet | Contains |
+|-----------|----------|
+| Frontend | Browser tools + CSS/JS linting + design system resources |
+| Backend | Database queries + API testing + log analysis |
+| Full Stack | Frontend + Backend |
+
+### Safety Limits
+
+| FeatureSet | Contains |
+|-----------|----------|
+| No Delete | All minus any delete/remove/drop operations |
+| No Deploy | All minus CI/CD and deployment tools |
+| Sandbox | Only filesystem (read) + search + documentation |
+
+## Managing FeatureSets
+
+![React Development FeatureSet — configuring included features from each server](/screenshots/featureset-detail.png)
+
+### Creating a Custom FeatureSet
+
+1. Go to the **FeatureSets** page
+2. Click **Create FeatureSet**
+3. Give it a name and optional description
+4. Add members — select features or other FeatureSets
+5. Set each member to include or exclude mode
+
+### Assigning to Clients
+
+FeatureSets are assigned to clients per Space. Go to the **Clients** page, select a client, and manage its FeatureSet grants for each Space.
+
+A client's effective permissions are the combination of all its granted FeatureSets, with exclude rules taking priority.
+
+## Next Steps
+
+- [Set up Clients](/docs/clients/) and assign FeatureSets per Space
+- [Learn about Spaces](/docs/spaces/) for environment isolation
+- [Understand the Gateway](/docs/gateway/) to see how permissions are enforced at request time
@@ -0,0 +1,97 @@
+---
+title: Gateway — Local MCP Proxy
+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.
+---
+
+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`.
+
+## How It Works
+
+```
+Cursor ──────────┐
+Claude Desktop ──┤
+VS Code ─────────┤──→ McpMux Gateway ──┬──→ GitHub Server
+Windsurf ────────┤    (localhost:45818) ├──→ Slack Server
+ChatGPT ─────────┘                     ├──→ PostgreSQL Server
+                                       └──→ Filesystem Server
+```
+
+The gateway receives MCP JSON-RPC requests from clients and:
+
+1. **Authenticates** the client using its access key
+2. **Resolves** which Space the client should use (based on connection mode)
+3. **Collects** the client's FeatureSet grants for that Space
+4. **Filters** the available tools, resources, and prompts based on permissions
+5. **Routes** each request to the correct backend MCP server
+6. **Returns** the response to the client
+
+## Request Routing
+
+When a client calls a tool (e.g., `github_create_issue`), the gateway:
+
+1. Looks up which server provides that tool
+2. Checks that the client has permission to use it (via FeatureSets)
+3. Forwards the request to the server's active connection
+4. Returns the server's response to the client
+
+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.
+
+## FeatureSet Filtering
+
+The gateway enforces permissions at the protocol level:
+
+- **`tools/list`** — only returns tools the client is permitted to use
+- **`tools/call`** — rejects calls to tools the client doesn't have access to
+- **`resources/list`** — only returns permitted resources
+- **`prompts/list`** — only returns permitted prompts
+
+This means you can have multiple clients connected to the same gateway with different levels of access, all managed through FeatureSets.
+
+## OAuth Token Management
+
+For servers that use OAuth 2.1 + PKCE authentication, the gateway handles the full token lifecycle:
+
+- **Initial authorization** — opens a browser for you to log in and grant permissions
+- **Token storage** — tokens are encrypted and stored in the OS keychain
+- **Automatic refresh** — when a token expires, the gateway refreshes it transparently
+- **Re-authorization** — if a refresh fails, McpMux prompts you to re-authenticate
+
+You never need to manually manage OAuth tokens — the gateway takes care of it.
+
+## Connection Pooling
+
+The gateway maintains a pool of connections to backend MCP servers:
+
+- Each server gets a connection based on its configuration and credentials
+- Connections are reused across clients (when they share the same Space and credentials)
+- The pool key is computed from `server_id + sha256(final_config_with_credentials)`
+- When credentials change (e.g., token refresh), a new connection is created with the updated credentials
+- Idle connections are cleaned up after a configurable timeout
+
+This means if two clients in the same Space both use the GitHub server, they share a single connection to GitHub — reducing resource usage.
+
+![Dashboard showing gateway running on localhost:45818 with server stats and client configuration](/screenshots/dashboard.png)
+
+## Starting and Stopping
+
+Control the gateway from the **Dashboard** in McpMux:
+
+- **Start Gateway** — begins listening on `localhost:45818` and connects to enabled servers
+- **Stop Gateway** — disconnects all servers and stops accepting requests
+
+The gateway also starts automatically when McpMux launches (configurable in Settings).
+
+## Gateway Status
+
+The dashboard shows real-time gateway status:
+
+- **Running** / **Stopped** — whether the gateway is accepting connections
+- **Connected Servers** — count of actively connected backend servers
+- **Registered Clients** — count of AI clients that have connected
+
+## Next Steps
+
+- [Set up Clients](/docs/clients/) to connect your AI applications
+- [Configure FeatureSets](/docs/feature-sets/) to control what each client can access
+- [Manage Servers](/docs/servers/) to add and configure backend MCP servers
+- [Learn about Security](/docs/security/) to understand how the gateway protects your credentials