coder · ibetitsmike · Feb 2, 2026
diff --git a/docs/agents/system-prompt.mdx b/docs/agents/system-prompt.mdx
@@ -140,11 +140,11 @@ function buildMCPContext(mcpServers: MCPServerMap): string {
 
   return `
 <mcp>
-MCP (Model Context Protocol) servers provide additional tools. Configured in user's local project's .mux/mcp.jsonc:
+MCP (Model Context Protocol) servers provide additional tools. Configured in ~/.mux/mcp.jsonc (global) and/or your project's .mux/mcp.jsonc (project):
 
 ${serverList}
 
-Use /mcp add|edit|remove or Settings → Projects to manage servers.
+Use Settings → Projects to manage servers (global or project), or /mcp add|edit|remove for project config.
 </mcp>
 `;
 }

diff --git a/docs/config/mcp-servers.mdx b/docs/config/mcp-servers.mdx
@@ -3,32 +3,67 @@ title: MCP Servers
 description: Extend agent capabilities with Model Context Protocol servers
 ---
 
-MCP (Model Context Protocol) servers provide additional tools to agents. Configure them per-project in `.mux/mcp.jsonc`.
+MCP (Model Context Protocol) servers provide additional tools to agents.
+
+Mux supports two configuration scopes:
+
+- **Global** (`~/.mux/mcp.jsonc`) — shared across all projects on this machine
+- **Project** (`<project>/.mux/mcp.jsonc`) — applies to all workspaces created from that project
+
+If the same server name exists in both files, the **project** definition wins.
 
 ## Configuration
 
-You can either configure the servers in the UI (`Ctrl+,`):
+You can configure servers in the UI (`Ctrl+,`) under **Settings → Projects**:
 
 ![MCP Servers UI](../img/mcp-servers-1.webp)
 
-Or directly in the `.mux/mcp.jsonc` file in your project root:
+Or directly in JSONC (same schema for both global and project files):
 
 ```jsonc
 {
   "servers": {
-    // Knowledge graph for persistent memory
+    // Simple form (stdio)
     "memory": "npx -y @modelcontextprotocol/server-memory",
-    // Browser automation and screenshots
-    "chrome": "npx -y chrome-devtools-mcp@latest --headless",
+
+    // Full form (stdio)
+    "chrome": {
+      "transport": "stdio",
+      "command": "npx -y chrome-devtools-mcp@latest --headless",
+      "disabled": false,
+    },
+
+    // Remote server (http/sse/auto)
+    "my-remote": {
+      "transport": "auto",
+      "url": "http://127.0.0.1:8080/mcp",
+      "headers": {
+        // Header values can come from project secrets
+        "Authorization": { "secret": "MY_TOKEN" },
+      },
+    },
   },
 }
 ```
 
-Each entry maps a server name to its shell command. The command must start a process that speaks MCP over stdio (NDJSON format).
+### Notes
+
+- `transport` can be `stdio`, `http`, `sse`, or `auto` (auto will try HTTP and fall back to SSE when needed).
+- `headers` secret references are resolved from **project secrets** (Settings → Projects → Secrets), even for globally-configured servers.
+- `toolAllowlist` (optional) restricts which tools from a server are exposed.
+
+## Workspace runtime status & restarts
+
+Open **Workspace MCP Configuration** from the workspace header to:
+
+- see per-server runtime status (running / failed / not started)
+- restart a specific server when it's misbehaving
+
+Note: restarts are disabled while a stream is active.
 
 ## Slash Commands
 
-Manage MCP servers directly from chat:
+Manage **project** MCP servers directly from chat (these commands modify `<project>/.mux/mcp.jsonc`):
 
 | Command                      | Description                         |
 | ---------------------------- | ----------------------------------- |
@@ -47,22 +82,22 @@ Examples:
 
 ## Scope
 
-MCP servers have two scopes:
-
-- **Configuration** is per-project — The `.mux/mcp.jsonc` file lives in your project root and applies to all workspaces created from that project
-- **Runtime instances** are per-workspace — Each workspace runs its own server processes, so state in one workspace doesn't affect another
+- **Global configuration** — `~/.mux/mcp.jsonc`
+- **Project configuration** — `<project>/.mux/mcp.jsonc`
+- **Per-workspace overrides** — `.mux/mcp.local.jsonc`
+- **Runtime instances** — Each workspace runs its own server processes, so state in one workspace doesn't affect another
 
 ## Per-workspace overrides
 
-mux supports per-workspace MCP overrides (enable/disable servers and restrict tool allowlists) without modifying the project-level `.mux/mcp.jsonc`.
+mux supports per-workspace MCP overrides (enable/disable servers and restrict tool allowlists) without modifying config files.
 
 These overrides are stored in a workspace-local file: `.mux/mcp.local.jsonc`.
 
 - This file is intended to be **gitignored** (it contains local-only workspace preferences)
 - When Mux writes this file, it also adds it to the workspace's local git excludes (`.git/info/exclude`) so it doesn't get accidentally committed
 - Older mux versions stored these overrides in `~/.mux/config.json`; mux will migrate them into `.mux/mcp.local.jsonc` on first use
 
-This means you configure servers once per project, but each workspace (branch) gets isolated server instances with independent state.
+This means you configure servers once globally / per-project, but each workspace (branch) gets isolated server instances with independent state.
 
 ## Behavior
 
@@ -79,6 +114,8 @@ Browse available servers at [mcp.so](https://mcp.so/) or the [MCP servers reposi
 
 If a server fails to start:
 
-1. **Test the command manually** — Run the command in your terminal to verify it works
-2. **Check dependencies** — Ensure required packages are installed (`npx -y` downloads on first run)
-3. **Use the Test button** — Settings → Projects shows connection errors inline
+1. **Check the warning message in chat** — mux will report MCP server startup failures during message send
+2. **Use the Test button** — Settings → Projects shows connection errors inline
+3. **Restart the server** — Open Workspace MCP Configuration and click Restart
+4. **Test the command manually** — Run the command in your terminal to verify it works
+5. **Check dependencies** — Ensure required packages are installed (`npx -y` downloads on first run)