diff --git a/docs/guide/clients.mdx b/docs/guide/clients.mdx index 7b7e354c..de13136e 100644 --- a/docs/guide/clients.mdx +++ b/docs/guide/clients.mdx @@ -1,11 +1,11 @@ --- -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. +title: Clients — Connected AI Apps +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. --- -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. +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. -## Supported Clients +## Supported clients McpMux works with any MCP-compatible client, including: @@ -23,79 +23,50 @@ McpMux works with any MCP-compatible client, including: All clients connect to the same endpoint: `http://localhost:45818/mcp` -![Authorization Request dialog — VS Code connecting to McpMux with connection mode selection](https://mcpmux.com/screenshots/clients.png) +## Connecting and approval -## Connection Modes +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/).) -Each client has a **connection mode** that determines how it interacts with Spaces: +![Approve a new app connecting to the gateway](https://mcpmux.com/screenshots/clients.png) -### Follow Active +## How routing works — workspace-driven -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. +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: -**Best for:** Your primary development tools that should always match your current context. +- 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. +- 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. +- A session with **no reported folder** falls through to the **active Space's** FeatureSet. -### Locked +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. -The client always uses a specific Space, regardless of which Space is active. This is useful for: +![A connected app — its toolset is decided by the Workspace binding for the folder it reports](https://mcpmux.com/screenshots/client-detail.png) -- A monitoring tool that should always see production servers -- A client dedicated to a specific project -- Background automation that shouldn't change behavior +Open any app to see how it's currently routed and exactly which tools, prompts, and resources resolve for it. -### Ask on Change +![Effective features resolved for a connected app](https://mcpmux.com/screenshots/client-permissions.png) -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](https://mcpmux.com/screenshots/client-detail.png) - -## Access Keys +## Access keys Each client authenticates with McpMux using an **access key**. Access keys are: -- Generated automatically when a client registers +- Issued automatically through the OAuth approval 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](https://mcpmux.com/screenshots/client-permissions.png) - -### Monitoring +## Managing connected apps -The **Clients** page shows: -- Each registered client's name and type -- Connection mode (Follow Active / Locked / Ask on Change) -- Last seen timestamp +The **Apps** page shows every app connected to your gateway in real time: -### Disconnecting +- Each app's name, type, and live status +- How it's routed (which folder → which Space + FeatureSet) +- Last-seen timestamp -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. +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. -## Next Steps +## 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 +- [Workspaces](/docs/workspaces/) — map each folder to the toolset it should get +- [FeatureSets](/docs/feature-sets/) — build the tool bundles a folder resolves to +- [Tool Optimization](/docs/tool-optimization/) — let an app curate its own toolset from chat +- [Gateway](/docs/gateway/) — how client requests are authenticated and routed diff --git a/docs/guide/feature-sets.mdx b/docs/guide/feature-sets.mdx index e7ee156e..04ede2fd 100644 --- a/docs/guide/feature-sets.mdx +++ b/docs/guide/feature-sets.mdx @@ -98,11 +98,13 @@ FeatureSets can **contain other FeatureSets**. This lets you build hierarchical 4. Add members — select features or other FeatureSets 5. Set each member to include or exclude mode -### Assigning to Clients +### Putting a FeatureSet to work -FeatureSets are assigned to clients per Space. Go to the **Clients** page, select a client, and manage its FeatureSet grants for each Space. +A FeatureSet becomes a session's toolset when a folder routes to it — map the folder in the [Workspaces](/docs/workspaces/) tab (or let the AI pin it with [Tool Optimization](/docs/tool-optimization/)). Sessions whose folder isn't mapped fall back to the active Space's FeatureSet. -A client's effective permissions are the combination of all its granted FeatureSets, with exclude rules taking priority. +The effective toolset is the combination of the resolved FeatureSet(s), with exclude rules taking priority. McpMux shows exactly what resolves: + +![Effective features resolved for a session — the tools, prompts, and resources it can actually use](https://mcpmux.com/screenshots/client-permissions.png) ## Next Steps diff --git a/docs/guide/gateway.mdx b/docs/guide/gateway.mdx index c1ce7a1b..1e8cc2a1 100644 --- a/docs/guide/gateway.mdx +++ b/docs/guide/gateway.mdx @@ -19,11 +19,10 @@ ChatGPT ─────────┘ ├──→ PostgreS 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 +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 +3. **Filters** the available tools, resources, and prompts to that resolved FeatureSet +4. **Routes** each request to the correct backend MCP server +5. **Returns** the response to the client ## Request Routing @@ -79,7 +78,9 @@ 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). +The gateway also starts automatically when McpMux launches, and you can change the port it binds to — both from **Settings**. + +![Settings — software updates, startup behavior, and the gateway port](https://mcpmux.com/screenshots/settings.png) ## Gateway Status diff --git a/docs/guide/getting-started.mdx b/docs/guide/getting-started.mdx index ab0d1fd8..b369a105 100644 --- a/docs/guide/getting-started.mdx +++ b/docs/guide/getting-started.mdx @@ -1,79 +1,49 @@ --- title: Getting Started with McpMux -description: Download McpMux, install your first MCP server, and connect Cursor, Claude, or VS Code in under 5 minutes. Step-by-step setup guide. +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. --- -Get McpMux running and connect your first AI client in just a few steps. +Get McpMux running, connect your first AI client, and dial in exactly the tools it sees — in a few minutes. ## Prerequisites - **Operating System**: Windows 10+, macOS 12+, or Linux (Ubuntu 20.04+, Fedora 38+) -- **AI Client**: At least one MCP-compatible client installed (Cursor, Claude Desktop, VS Code, etc.) +- **AI Client**: At least one MCP-compatible client installed (Cursor, Claude Desktop, VS Code, Windsurf, …) -## Step 1: Download and Install +## Step 1: Download and install Download McpMux for your platform from the [download page](/download/). -- **Windows**: Run the `.msi` installer -- **macOS**: Open the `.dmg` and drag McpMux to Applications -- **Linux**: Install via `.deb`, `.rpm`, or `.AppImage` +- **Windows**: run the installer (`.msi` or `.exe`) +- **macOS**: open the `.dmg` and drag McpMux to Applications +- **Linux**: install via `.deb`, `.rpm`, or `.AppImage` -McpMux runs in the system tray — look for the McpMux icon after installation. +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/). -## Step 2: Create a Space +## Step 2: Install a server from the registry -When you first open McpMux, a default Space is created for you. Spaces are isolated environments with their own server configurations and credentials. +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. -You can create additional Spaces later for different contexts: -- **Work** — company tools with work credentials -- **Personal** — side projects with personal API keys -- **Client-A** — isolated environment for a specific client +![Discover — browse, search, and install MCP servers from the registry](https://mcpmux.com/screenshots/discover.png) -To create a Space, go to the **Spaces** page and click **Create Space**. +## Step 3: Configure credentials -![Space switcher in the sidebar lets you quickly switch between workspaces](https://mcpmux.com/screenshots/space-switcher.png) +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. -## Step 3: Browse and Install a Server +- Secrets are encrypted with AES-256-GCM and stored in your OS keychain — never in plain-text files. +- Use the **obtain** link (when provided) to jump straight to the service's token page. -Navigate to **Discover Servers** in McpMux or browse the [server registry](/) on this website. You'll find 100+ MCP servers for popular tools. +See [Server Management](/docs/servers/) for all options. -![Discover Servers page — browse, search, and install MCP servers from the registry](https://mcpmux.com/screenshots/discover.png) +## Step 4: Start the gateway -Click **Install** on any server to add it to your active Space. Popular choices to start with: +On the **Home** dashboard, start the gateway. It listens on `localhost:45818` and connects your enabled servers (🟡 connecting → 🟢 connected → 🔴 error). -- **Filesystem** — read and write local files -- **GitHub** — interact with repositories, issues, and PRs -- **Brave Search** — web search capabilities -- **Playwright** — browser automation +![Home — gateway running on localhost:45818 with server stats and one-click client connect](https://mcpmux.com/screenshots/dashboard.png) -## Step 4: Configure Credentials +## Step 5: Connect your AI client -If the server requires authentication (API keys, tokens, etc.), a configuration dialog appears automatically after installation. Fill in the required fields: - -- **API keys** are stored encrypted using AES-256-GCM — they never touch disk in plaintext -- Click the **obtain** link (if provided) to go directly to the service's token creation page -- Sensitive fields are masked in the UI and stored in the OS keychain - -See [Server Management](/docs/servers/) for details on all configuration options. - -## Step 5: Start the Gateway - -Go to the **Dashboard** and click **Start Gateway**. The gateway starts on `localhost:45818` and begins connecting to your enabled servers. - -![Dashboard with gateway running and connected servers](https://mcpmux.com/screenshots/dashboard.png) - -You'll see server status indicators change: -- 🟡 **Connecting** — establishing MCP handshake -- 🟢 **Connected** — ready to serve requests -- 🔴 **Error** — check server logs for details - -## Step 6: Connect Your AI Client - -Configure your AI client to connect to McpMux's gateway endpoint. The exact setup depends on your client: - -### Cursor - -Add to your Cursor MCP settings (`.cursor/mcp.json`): +**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: ```json { @@ -85,53 +55,49 @@ Add to your Cursor MCP settings (`.cursor/mcp.json`): } ``` -### Claude Desktop +- **Cursor** → `.cursor/mcp.json` · **Claude Desktop** → `claude_desktop_config.json` · **Windsurf** → use `"serverUrl"` instead of `"url"` +- **VS Code (Copilot)** → `.vscode/mcp.json` under a `"servers"` key -Add to your Claude Desktop config (`claude_desktop_config.json`): +## Step 6: Approve the connection -```json -{ - "mcpServers": { - "mcpmux": { - "url": "http://localhost:45818/mcp" - } - } -} -``` +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. -### VS Code (Copilot) +![Approve a new app connecting to the gateway](https://mcpmux.com/screenshots/clients.png) -Add to your VS Code settings (`.vscode/mcp.json`): +You can rename, inspect, or revoke any connected app later from the **Apps** page. See [Clients](/docs/clients/). -```json -{ - "servers": { - "mcpmux": { - "url": "http://localhost:45818/mcp" - } - } -} -``` +## Step 7: Route the folder to the right tools -### Windsurf +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. -Add to your Windsurf MCP configuration: +- **By default**, a session uses the active Space's FeatureSet. +- **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. -```json -{ - "mcpServers": { - "mcpmux": { - "serverUrl": "http://localhost:45818/mcp" - } - } -} -``` +![Workspaces — map a project folder to the Space and FeatureSet it should get](https://mcpmux.com/screenshots/workspaces.png) + +See [Workspaces](/docs/workspaces/) for routing and [FeatureSets](/docs/feature-sets/) for building the tool bundles a folder resolves to. + +## Step 8: Let your AI curate its own toolset + +Don't want to map folders by hand? In your AI client, start a request with **`@mux`**: + +> *"@mux optimize this folder."* + +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. + +![Tool Optimization — the built-in @mux tools the AI drives, reads silent and writes gated](https://mcpmux.com/screenshots/tool-optimization.png) + +See [Tool Optimization](/docs/tool-optimization/). + +## You're set -Once connected, your AI client can access all the tools, resources, and prompts from every enabled MCP server — through the single McpMux gateway endpoint. +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`. ## Next Steps -- [Learn about Spaces](/docs/spaces/) to organize your environments -- [Configure FeatureSets](/docs/feature-sets/) to control tool permissions -- [Browse the server registry](/) to find more MCP servers -- [Understand security](/docs/security/) and how McpMux protects your credentials +- [Spaces](/docs/spaces/) — isolate work, personal, and client contexts +- [Workspaces](/docs/workspaces/) — route each folder to its own toolset +- [FeatureSets](/docs/feature-sets/) — curate exactly which tools, prompts, and resources are exposed +- [Tool Optimization](/docs/tool-optimization/) — let the AI keep its toolset lean +- [Clients](/docs/clients/) — manage and revoke connected apps +- [Security](/docs/security/) — how McpMux protects your credentials diff --git a/docs/guide/index.mdx b/docs/guide/index.mdx index 2583cc62..f539162b 100644 --- a/docs/guide/index.mdx +++ b/docs/guide/index.mdx @@ -43,13 +43,21 @@ McpMux sits between your AI clients and your MCP servers. It handles: Isolated workspaces with separate server configurations and credentials. Keep your work GitHub token completely separate from your personal one. +### [Workspaces](/docs/workspaces/) + +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. + ### [FeatureSets](/docs/feature-sets/) -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. +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. + +### [Tool Optimization](/docs/tool-optimization/) + +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. ### [Clients](/docs/clients/) -AI applications connected to McpMux. Configure connection modes (follow active Space, lock to a Space, or ask on change) and assign permissions per Space. +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. ### [Servers](/docs/servers/) diff --git a/docs/guide/security.mdx b/docs/guide/security.mdx index 7c285ed2..9729f966 100644 --- a/docs/guide/security.mdx +++ b/docs/guide/security.mdx @@ -84,6 +84,8 @@ For servers using OAuth 2.1, McpMux implements the full security specification: - **Encrypted storage** — both access and refresh tokens are encrypted at rest - **Consent UI** — OAuth authorization requests show a consent dialog in the desktop app, ensuring the user explicitly approves each connection +![Consent dialog — every new app connection must be explicitly approved in the desktop app](https://mcpmux.com/screenshots/clients.png) + ## Deep Link Security When McpMux receives an OAuth authorization request via deep link (`mcpmux://authorize?request_id=xxx`): diff --git a/docs/guide/spaces.mdx b/docs/guide/spaces.mdx index 231f773a..370ad08f 100644 --- a/docs/guide/spaces.mdx +++ b/docs/guide/spaces.mdx @@ -25,14 +25,14 @@ Each Space is an independent environment containing: - **Installed servers** — which MCP servers are available in this Space - **Server configurations** — per-Space credentials, environment variables, and settings - **FeatureSets** — permission bundles scoped to this Space -- **Client grants** — which FeatureSets each AI client gets in this Space +- **Workspace bindings** — which project folders route to this Space and the FeatureSet they resolve to (see [Workspaces](/docs/workspaces/)) ### Active Space -Only one Space can be **active** at a time. The active Space determines: +Only one Space can be **active** at a time. The active Space is the **fallback** for any session whose folder isn't mapped to a specific Space via a [Workspace](/docs/workspaces/) binding. It determines: - Which servers the gateway connects to -- Which tools AI clients can see and use (for clients in "Follow Active" mode) +- Which tools an unmapped session sees (its active-Space FeatureSet) - Which credentials are injected into server connections Switching the active Space immediately changes what servers and tools are available — no restart required. @@ -82,7 +82,7 @@ Navigate to **Spaces** in McpMux and click **Create Space**. Give it a name and ### Switching Active Space -Click on any Space to set it as active. The dashboard and server list update immediately to reflect the new context. AI clients using "Follow Active" mode switch automatically. +Click on any Space to set it as active. The dashboard and server list update immediately to reflect the new context. Any session whose folder isn't mapped to a specific Space follows the active Space automatically. ### Deleting a Space @@ -91,5 +91,6 @@ Deleting a Space removes all its server configurations and stored credentials. T ## Next Steps - [Configure FeatureSets](/docs/feature-sets/) to control permissions within a Space -- [Set up Clients](/docs/clients/) with connection modes that interact with Spaces +- [Route folders with Workspaces](/docs/workspaces/) so each project resolves to the right Space +- [Set up Clients](/docs/clients/) and approve the apps that connect - [Manage Servers](/docs/servers/) to install and configure per-Space server instances diff --git a/docs/guide/workspaces.mdx b/docs/guide/workspaces.mdx index e95bec6d..891b8639 100644 --- a/docs/guide/workspaces.mdx +++ b/docs/guide/workspaces.mdx @@ -40,6 +40,10 @@ Open the **Workspaces** tab and click **Add mapping**: Unmapped folders receive no tools until you map them — an explicit, fail-closed default so a new project never silently inherits another's access. +The FeatureSet you pick is the exact toolset the folder resolves to — choose which tools, prompts, and resources from each server it's allowed to use: + +![The FeatureSet a folder resolves to — pick exactly which tools each server contributes](https://mcpmux.com/screenshots/featureset-detail.png) + ## Let the AI map it for you You don't have to open the Workspaces tab at all. With [Tool Optimization](/docs/tool-optimization/), an assistant can compose a FeatureSet and pin the current folder to it from chat: