🤖 feat: add per-workspace MCP server and tool configuration (#1180)

## Summary

Adds per-workspace MCP server and tool configuration. Users can now
customize which MCP servers are enabled and which tools are exposed for
each workspace, without modifying the project-level `.mux/mcp.jsonc`.

## Changes

### Backend
- **Types & Schemas**: Added `WorkspaceMCPOverrides` schema with
`disabledServers` and `toolAllowlist` fields
- **Config helpers**: `getWorkspaceMCPOverrides()` and
`setWorkspaceMCPOverrides()` methods in Config class
- **ORPC endpoints**: `workspace.mcp.get` and `workspace.mcp.set` for
frontend access
- **MCPServerManager**: Updated to filter servers and tools based on
workspace overrides
- **AIService**: Fetches and passes overrides when getting MCP tools

### Frontend
- **WorkspaceMCPModal**: New modal component for per-workspace MCP
configuration
- **WorkspaceHeader**: Added Server button (⚙️) to open the modal
- UI features:
  - Toggle servers enabled/disabled for the workspace
  - Fetch tools from each server
  - Checkbox allowlist to select which tools to expose
  - "Allow all" shortcut button

### Tests
- 5 tests for workspace override filtering in MCPServerManager
- 6 tests for workspace MCP override Config helpers

## How it works

1. **Server definitions remain per-project** in `.mux/mcp.jsonc`
2. **Per-workspace overrides** are stored in `~/.mux/config.json` under
each workspace entry
3. Effective servers = (project servers) - (workspace `disabledServers`)
4. Effective tools = filtered by `toolAllowlist[server]` if set

---

<details>
<summary>📋 Implementation Plan</summary>

# Plan: Selective MCP tools + per-workspace configuration

## Goals

1. **Selective MCP tools** — For each workspace, expose only an
allowlisted subset of MCP tools to the model.
2. **Per-workspace MCP configuration** — Allow enabling/disabling MCP
servers (and tool allowlists) **per workspace**, without impacting other
workspaces.
3. **Backwards compatible** — Existing per-project `.mux/mcp.jsonc`
continues to work unchanged.

## Proposed approach (recommended)

### 1) Keep server *definitions* per-project; add per-workspace
*overrides*

- **Per-project** (existing): `PROJECT_ROOT/.mux/mcp.jsonc`
  - Source of truth for **server commands**.
- **Per-workspace** (new, stored in mux global config
`~/.mux/config.json` under each workspace entry):
  - Which servers are enabled for that workspace.
  - Which tools are allowlisted (per server) for that workspace.

This avoids needing to read/write config inside SSH workspaces (remote
filesystem) and keeps the current "configure once per project"
ergonomics, while still enabling workspace-specific behavior.

### 2) Workspace MCP override schema

Add an optional `mcp` field on `WorkspaceConfigSchema`:

```ts
// Stored under each workspace entry in ~/.mux/config.json
export interface WorkspaceMCPOverrides {
  /** If set, these servers are disabled for this workspace (after project config). */
  disabledServers?: string[];

  /**
   * Optional per-server allowlist of tools.
   * Key: server name (from .mux/mcp.jsonc)
   * Value: raw MCP tool names (NOT namespaced)
   *
   * If omitted for a server => expose all tools from that server.
   */
  toolAllowlist?: Record<string, string[]>;
}
```

Semantics:
- Effective servers for a workspace = (project-config enabled servers)
minus `disabledServers`.
- Effective tools for a server:
  - If `toolAllowlist[server]` present => only expose those tool names.
  - Else => expose all tools from that server.

### 3) Runtime behavior changes

- `MCPServerManager.getToolsForWorkspace(...)` filters the returned tool
map using the workspace allowlists *before* it is merged into
`getToolsForModel`.
- `MCPServerManager.listServers(...)` gains a workspace-aware variant so
the system prompt lists **only the servers enabled for that workspace**.
- **No restart required** when only tool allowlists change (servers stay
running; we just filter what we expose).

</details>

---
_Generated with `mux` • Model: `anthropic:claude-opus-4-5` • Thinking:
`high`_

Author: ThomasK33

.storybook/mocks/orpc.ts

@@ -70,6 +70,18 @@ export interface MockORPCClientOptions {
   >;
   /** Session usage data per workspace (for Costs tab) */
   sessionUsage?: Map<string, MockSessionUsage>;
+  /** MCP server configuration per project */
+  mcpServers?: Map<
+    string,
+    Record<string, { command: string; disabled: boolean; toolAllowlist?: string[] }>
+  >;
+  /** MCP workspace overrides per workspace */
+  mcpOverrides?: Map<
+    string,
+    { disabledServers?: string[]; enabledServers?: string[]; toolAllowlist?: Record<string, string[]> }
+  >;
+  /** MCP test results - maps server name to tools list or error */
+  mcpTestResults?: Map<string, { success: true; tools: string[] } | { success: false; error: string }>;
 }
 
 /**
@@ -100,6 +112,9 @@ export function createMockORPCClient(options: MockORPCClientOptions = {}): APICl
     onProjectRemove,
     backgroundProcesses = new Map(),
     sessionUsage = new Map(),
+    mcpServers = new Map(),
+    mcpOverrides = new Map(),
+    mcpTestResults = new Map(),
   } = options;
 
   const workspaceMap = new Map(workspaces.map((w) => [w.id, w]));
@@ -159,6 +174,20 @@ export function createMockORPCClient(options: MockORPCClientOptions = {}): APICl
         get: async () => [],
         update: async () => ({ success: true, data: undefined }),
       },
+      mcp: {
+        list: async (input: { projectPath: string }) => mcpServers.get(input.projectPath) ?? {},
+        add: async () => ({ success: true, data: undefined }),
+        remove: async () => ({ success: true, data: undefined }),
+        test: async (input: { projectPath: string; name?: string }) => {
+          if (input.name && mcpTestResults.has(input.name)) {
+            return mcpTestResults.get(input.name)!;
+          }
+          // Default: return empty tools
+          return { success: true, tools: [] };
+        },
+        setEnabled: async () => ({ success: true, data: undefined }),
+        setToolAllowlist: async () => ({ success: true, data: undefined }),
+      },
     },
     workspace: {
       list: async () => workspaces,
@@ -239,6 +268,10 @@ export function createMockORPCClient(options: MockORPCClientOptions = {}): APICl
         sendToBackground: async () => ({ success: true, data: undefined }),
       },
       getSessionUsage: async (input: { workspaceId: string }) => sessionUsage.get(input.workspaceId),
+      mcp: {
+        get: async (input: { workspaceId: string }) => mcpOverrides.get(input.workspaceId) ?? {},
+        set: async () => ({ success: true, data: undefined }),
+      },
     },
     window: {
       setTitle: async () => undefined,

src/browser/components/AIView.tsx

@@ -540,6 +540,7 @@ const AIViewInner: React.FC<AIViewProps> = ({
         <WorkspaceHeader
           workspaceId={workspaceId}
           projectName={projectName}
+          projectPath={projectPath}
           workspaceName={workspaceName}
           namedWorkspacePath={namedWorkspacePath}
           runtimeConfig={runtimeConfig}

src/browser/components/Settings/sections/ProjectSettingsSection.tsx

@@ -1,4 +1,4 @@
-import React, { useCallback, useEffect, useMemo, useState } from "react";
+import React, { useCallback, useEffect, useState } from "react";
 import { useAPI } from "@/browser/contexts/API";
 import { useProjectContext } from "@/browser/contexts/ProjectContext";
 import {
@@ -12,6 +12,8 @@ import {
   Pencil,
   Check,
   X,
+  ChevronDown,
+  ChevronRight,
 } from "lucide-react";
 import { Button } from "@/browser/components/ui/button";
 import {
@@ -26,57 +28,143 @@ import { Switch } from "@/browser/components/ui/switch";
 import { cn } from "@/common/lib/utils";
 import { formatRelativeTime } from "@/browser/utils/ui/dateTime";
 import type { CachedMCPTestResult, MCPServerInfo } from "@/common/types/mcp";
-import { getMCPTestResultsKey } from "@/common/constants/storage";
-import { readPersistedState, updatePersistedState } from "@/browser/hooks/usePersistedState";
+import { useMCPTestCache } from "@/browser/hooks/useMCPTestCache";
+import { ToolSelector } from "@/browser/components/ToolSelector";
+
+/** Component for managing tool allowlist for a single MCP server */
+const ToolAllowlistSection: React.FC<{
+  serverName: string;
+  availableTools: string[];
+  currentAllowlist?: string[];
+  testedAt: number;
+  projectPath: string;
+}> = ({ serverName, availableTools, currentAllowlist, testedAt, projectPath }) => {
+  const { api } = useAPI();
+  const [expanded, setExpanded] = useState(false);
+  const [saving, setSaving] = useState(false);
+  // Always use an array internally - undefined from props means all tools allowed
+  const [localAllowlist, setLocalAllowlist] = useState<string[]>(
+    () => currentAllowlist ?? [...availableTools]
+  );
 
-type CachedResults = Record<string, CachedMCPTestResult>;
+  // Sync local state when prop changes
+  useEffect(() => {
+    setLocalAllowlist(currentAllowlist ?? [...availableTools]);
+  }, [currentAllowlist, availableTools]);
 
-/** Hook to manage MCP test results with localStorage caching */
-function useMCPTestCache(projectPath: string) {
-  const storageKey = useMemo(
-    () => (projectPath ? getMCPTestResultsKey(projectPath) : ""),
-    [projectPath]
-  );
+  const allAllowed = localAllowlist.length === availableTools.length;
+  const allDisabled = localAllowlist.length === 0;
 
-  const [cache, setCache] = useState<CachedResults>(() =>
-    storageKey ? readPersistedState<CachedResults>(storageKey, {}) : {}
-  );
+  const handleToggleTool = useCallback(
+    async (toolName: string, allowed: boolean) => {
+      if (!api) return;
 
-  // Reload cache when project changes
-  useEffect(() => {
-    if (storageKey) {
-      setCache(readPersistedState<CachedResults>(storageKey, {}));
-    } else {
-      setCache({});
-    }
-  }, [storageKey]);
-
-  const setResult = useCallback(
-    (name: string, result: CachedMCPTestResult["result"]) => {
-      const entry: CachedMCPTestResult = { result, testedAt: Date.now() };
-      setCache((prev) => {
-        const next = { ...prev, [name]: entry };
-        if (storageKey) updatePersistedState(storageKey, next);
-        return next;
-      });
+      const newAllowlist = allowed
+        ? [...localAllowlist, toolName]
+        : localAllowlist.filter((t) => t !== toolName);
+
+      // Optimistic update
+      setLocalAllowlist(newAllowlist);
+      setSaving(true);
+
+      try {
+        const result = await api.projects.mcp.setToolAllowlist({
+          projectPath,
+          name: serverName,
+          toolAllowlist: newAllowlist,
+        });
+        if (!result.success) {
+          setLocalAllowlist(currentAllowlist ?? [...availableTools]);
+          console.error("Failed to update tool allowlist:", result.error);
+        }
+      } catch (err) {
+        setLocalAllowlist(currentAllowlist ?? [...availableTools]);
+        console.error("Failed to update tool allowlist:", err);
+      } finally {
+        setSaving(false);
+      }
     },
-    [storageKey]
+    [api, projectPath, serverName, localAllowlist, currentAllowlist, availableTools]
   );
 
-  const clearResult = useCallback(
-    (name: string) => {
-      setCache((prev) => {
-        const next = { ...prev };
-        delete next[name];
-        if (storageKey) updatePersistedState(storageKey, next);
-        return next;
+  const handleAllowAll = useCallback(async () => {
+    if (!api || allAllowed) return;
+
+    const newAllowlist = [...availableTools];
+    setLocalAllowlist(newAllowlist);
+    setSaving(true);
+
+    try {
+      const result = await api.projects.mcp.setToolAllowlist({
+        projectPath,
+        name: serverName,
+        toolAllowlist: newAllowlist,
       });
-    },
-    [storageKey]
-  );
+      if (!result.success) {
+        setLocalAllowlist(currentAllowlist ?? [...availableTools]);
+        console.error("Failed to clear tool allowlist:", result.error);
+      }
+    } catch (err) {
+      setLocalAllowlist(currentAllowlist ?? [...availableTools]);
+      console.error("Failed to clear tool allowlist:", err);
+    } finally {
+      setSaving(false);
+    }
+  }, [api, projectPath, serverName, allAllowed, currentAllowlist, availableTools]);
+
+  const handleSelectNone = useCallback(async () => {
+    if (!api || allDisabled) return;
 
-  return { cache, setResult, clearResult };
-}
+    setLocalAllowlist([]);
+    setSaving(true);
+
+    try {
+      const result = await api.projects.mcp.setToolAllowlist({
+        projectPath,
+        name: serverName,
+        toolAllowlist: [],
+      });
+      if (!result.success) {
+        setLocalAllowlist(currentAllowlist ?? [...availableTools]);
+        console.error("Failed to set empty tool allowlist:", result.error);
+      }
+    } catch (err) {
+      setLocalAllowlist(currentAllowlist ?? [...availableTools]);
+      console.error("Failed to set empty tool allowlist:", err);
+    } finally {
+      setSaving(false);
+    }
+  }, [api, projectPath, serverName, allDisabled, currentAllowlist, availableTools]);
+
+  return (
+    <div className="mt-2">
+      <button
+        onClick={() => setExpanded(!expanded)}
+        className="text-muted-foreground hover:text-foreground flex items-center gap-1 text-xs"
+      >
+        {expanded ? <ChevronDown className="h-3 w-3" /> : <ChevronRight className="h-3 w-3" />}
+        <span>
+          Tools: {localAllowlist.length}/{availableTools.length}
+        </span>
+        <span className="text-muted-foreground/60 ml-1">({formatRelativeTime(testedAt)})</span>
+        {saving && <Loader2 className="ml-1 h-3 w-3 animate-spin" />}
+      </button>
+
+      {expanded && (
+        <div className="border-border-light mt-2 border-l-2 pl-3">
+          <ToolSelector
+            availableTools={availableTools}
+            allowedTools={localAllowlist}
+            onToggle={(tool, allowed) => void handleToggleTool(tool, allowed)}
+            onSelectAll={() => void handleAllowAll()}
+            onSelectNone={() => void handleSelectNone()}
+            disabled={saving}
+          />
+        </div>
+      )}
+    </div>
+  );
+};
 
 export const ProjectSettingsSection: React.FC = () => {
   const { api } = useAPI();
@@ -478,12 +566,13 @@ export const ProjectSettingsSection: React.FC = () => {
                   </div>
                 )}
                 {cached?.result.success && cached.result.tools.length > 0 && !isEditing && (
-                  <p className="text-muted-foreground mt-2 text-xs">
-                    Tools: {cached.result.tools.join(", ")}
-                    <span className="text-muted-foreground/60 ml-2">
-                      ({formatRelativeTime(cached.testedAt)})
-                    </span>
-                  </p>
+                  <ToolAllowlistSection
+                    serverName={name}
+                    availableTools={cached.result.tools}
+                    currentAllowlist={entry.toolAllowlist}
+                    testedAt={cached.testedAt}
+                    projectPath={selectedProject}
+                  />
                 )}
               </li>
             );

src/browser/components/ToolSelector.tsx

@@ -0,0 +1,76 @@
+import React from "react";
+import { Checkbox } from "@/browser/components/ui/checkbox";
+import { Button } from "@/browser/components/ui/button";
+
+interface ToolSelectorProps {
+  /** All available tools for this server */
+  availableTools: string[];
+  /** Currently allowed tools (empty = none allowed) */
+  allowedTools: string[];
+  /** Called when tool selection changes */
+  onToggle: (toolName: string, allowed: boolean) => void;
+  /** Called to select all tools */
+  onSelectAll: () => void;
+  /** Called to deselect all tools */
+  onSelectNone: () => void;
+  /** Whether controls are disabled */
+  disabled?: boolean;
+}
+
+/**
+ * Reusable tool selector grid with All/None buttons.
+ * Used by both project-level and workspace-level MCP config UIs.
+ */
+export const ToolSelector: React.FC<ToolSelectorProps> = ({
+  availableTools,
+  allowedTools,
+  onToggle,
+  onSelectAll,
+  onSelectNone,
+  disabled = false,
+}) => {
+  const allAllowed = allowedTools.length === availableTools.length;
+  const noneAllowed = allowedTools.length === 0;
+
+  return (
+    <div>
+      <div className="mb-2 flex items-center justify-between">
+        <span className="text-muted-foreground text-xs">Select tools to expose:</span>
+        <div className="flex gap-1">
+          <Button
+            variant="ghost"
+            size="sm"
+            className="h-5 px-2 text-xs"
+            onClick={onSelectAll}
+            disabled={disabled || allAllowed}
+          >
+            All
+          </Button>
+          <Button
+            variant="ghost"
+            size="sm"
+            className="h-5 px-2 text-xs"
+            onClick={onSelectNone}
+            disabled={disabled || noneAllowed}
+          >
+            None
+          </Button>
+        </div>
+      </div>
+      <div className="grid grid-cols-2 gap-1">
+        {availableTools.map((tool) => (
+          <label key={tool} className="flex cursor-pointer items-center gap-2 py-0.5 text-xs">
+            <Checkbox
+              checked={allowedTools.includes(tool)}
+              onCheckedChange={(checked) => onToggle(tool, checked === true)}
+              disabled={disabled}
+            />
+            <span className="truncate font-mono" title={tool}>
+              {tool}
+            </span>
+          </label>
+        ))}
+      </div>
+    </div>
+  );
+};