mixdog 0.9.105 → 0.9.106

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mixdog",
-  "version": "0.9.105",
+  "version": "0.9.106",
   "private": false,
   "type": "module",
   "description": "Standalone mixdog coding-agent CLI/TUI workspace.",

package/src/runtime/agent/orchestrator/agent-runtime/session-builder.mjs

@@ -64,6 +64,7 @@ function normalizeAgentCompactionConfig(value = {}, { memoryEnabled = true } = {
  * @param {number}  [opts.maxLoopIterations]
  * @param {string}  [opts.parentSessionId]
  * @param {string|null} [opts.ownerSessionId] - owning Mixdog MCP instance id for statusline isolation
+ * @param {string|null} [opts.mcpScopeId] - owning session-runtime MCP registry scope
  * @returns {{ session: object, effectiveCwd: string|null }}
  */
 export function prepareAgentSession({
@@ -86,6 +87,7 @@ export function prepareAgentSession({
     cacheKeyOverride,
     schemaAllowedTools,
     sessionId,
+    mcpScopeId,
 }) {
     const effectivePermission = resolveAgentSessionPermission(agent, permission);
     // No per-agent loop caps: sessions either pin maxLoopIterations explicitly
@@ -121,6 +123,7 @@ export function prepareAgentSession({
         ownerSessionId: effectiveOwnerSessionId || null,
         clientHostPid: clientHostPid || null,
         compaction: compaction || undefined,
+        mcpScopeId: mcpScopeId || null,
     };
     if (agentTag) sessionOpts.agentTag = agentTag;
     if (effectivePermission) sessionOpts.permission = effectivePermission;

package/src/runtime/agent/orchestrator/mcp/client.mjs

@@ -28,6 +28,10 @@ const DEFAULT_MCP_STARTUP_TIMEOUT_MS = 10000;
 const servers = new Map();
 const reconnects = createKeyedSingleflight();
 const callAdmissions = new Map();
+const DEFAULT_MCP_SCOPE_ID = 'global';
+const _knownMcpScopes = new Set([DEFAULT_MCP_SCOPE_ID]);
+const _connectAbortGenerations = new Map();
+const _pendingConnects = new Set();
 let mcpSdkPromise = null;
 // Memo for mcpToolHasField(name, field) — keyed by `${toolName}|${field}`.
 // The lookup (regex parse + servers Map get + tools.find + schema property
@@ -39,6 +43,30 @@ const _mcpToolFieldMemo = new Map();
 function _invalidateMcpToolFieldMemo() {
     _mcpToolFieldMemo.clear();
 }
+function normalizeMcpScopeId(value) {
+    const raw = value && typeof value === 'object' ? value.scopeId : value;
+    const scopeId = String(raw || '').trim();
+    return scopeId || DEFAULT_MCP_SCOPE_ID;
+}
+function mcpServerRegistryKey(scopeId, name) {
+    return `${normalizeMcpScopeId(scopeId)}\u0000${String(name || '')}`;
+}
+function scopedServer(scopeId, name) {
+    return servers.get(mcpServerRegistryKey(scopeId, name));
+}
+function scopedServerEntries(scopeId) {
+    const normalized = normalizeMcpScopeId(scopeId);
+    return [...servers.entries()].filter(([, server]) => server?.scopeId === normalized);
+}
+function currentConnectAbortGeneration(scopeId) {
+    return _connectAbortGenerations.get(normalizeMcpScopeId(scopeId)) || 0;
+}
+function bumpConnectAbortGeneration(scopeId) {
+    const normalized = normalizeMcpScopeId(scopeId);
+    const next = currentConnectAbortGeneration(normalized) + 1;
+    _connectAbortGenerations.set(normalized, next);
+    return next;
+}
 function mcpLog(line) {
     if (process.env.MIXDOG_QUIET_MCP_LOG) return;
     process.stderr.write(line);
@@ -106,12 +134,14 @@ export function resolveMcpTransportKind(cfg) {
  * Connect to MCP servers defined in config.
  * Supports stdio (child process) and http (Streamable HTTP) transports.
  */
-export async function connectMcpServers(config) {
+export async function connectMcpServers(config, options = {}) {
+    const scopeId = normalizeMcpScopeId(options);
+    _knownMcpScopes.add(scopeId);
     // Capture the abort generation SYNCHRONOUSLY at entry: the boot path fires
     // this un-awaited, so a runtime close can land while connectServer is still
     // loading the SDK. A capture taken any later would already see the bumped
     // generation and register the server anyway (leaking its stdio child).
-    const genAtStart = _connectAbortGeneration;
+    const genAtStart = currentConnectAbortGeneration(scopeId);
     const failures = [];
     const entries = Object.entries(config).filter(([name, cfg]) => {
         if (cfg?.enabled === false) {
@@ -123,7 +153,7 @@ export async function connectMcpServers(config) {
     // Connect all servers in PARALLEL: a slow/hung server (bounded by its
     // per-server startup timeout) must never delay the others' handshakes.
     const settled = await Promise.allSettled(
-        entries.map(([name, cfg]) => connectServer(name, cfg, genAtStart)),
+        entries.map(([name, cfg]) => connectServer(name, cfg, scopeId, genAtStart)),
     );
     settled.forEach((res, i) => {
         if (res.status !== 'rejected') return;
@@ -143,15 +173,15 @@ export async function connectMcpServers(config) {
  * Get all tool definitions from connected MCP servers.
  * Tool names are prefixed: `mcp__{serverName}__{toolName}`
  */
-export function getMcpTools() {
+export function getMcpTools(scopeId = DEFAULT_MCP_SCOPE_ID) {
     const tools = [];
-    for (const server of servers.values()) {
+    for (const [, server] of scopedServerEntries(scopeId)) {
         tools.push(...server.tools);
     }
     return tools;
 }
-export function getMcpServerStatus() {
-    return [...servers.values()].map((server) => ({
+export function getMcpServerStatus(scopeId = DEFAULT_MCP_SCOPE_ID) {
+    return scopedServerEntries(scopeId).map(([, server]) => ({
         name: server.name,
         connected: true,
         toolCount: Array.isArray(server.tools) ? server.tools.length : 0,
@@ -173,7 +203,8 @@ function positiveInt(value, fallback) {
     return Number.isFinite(parsed) && parsed >= 1 ? parsed : fallback;
 }
 function callAdmissionFor(server) {
-    let gate = callAdmissions.get(server.name);
+    const registryKey = server.registryKey || mcpServerRegistryKey(server.scopeId, server.name);
+    let gate = callAdmissions.get(registryKey);
     if (gate) return gate;
     const cfg = server?.cfg || {};
     gate = createOwnerFairGate({
@@ -192,44 +223,53 @@ function callAdmissionFor(server) {
             30_000,
         ),
     });
-    callAdmissions.set(server.name, gate);
+    gate.mcpServerName = server.name;
+    gate.mcpScopeId = server.scopeId;
+    callAdmissions.set(registryKey, gate);
     return gate;
 }
-function closeCallAdmission(name, reason) {
-    const gate = callAdmissions.get(name);
+function closeCallAdmission(scopeId, name, reason) {
+    const registryKey = mcpServerRegistryKey(scopeId, name);
+    const gate = callAdmissions.get(registryKey);
     if (!gate) return;
-    callAdmissions.delete(name);
+    callAdmissions.delete(registryKey);
     gate.close(reason || `MCP ${name} disconnected`);
 }
-export function getMcpAdmissionSnapshot() {
-    return [...callAdmissions.entries()].map(([name, gate]) => ({
-        name,
+export function getMcpAdmissionSnapshot(options = undefined) {
+    const scoped = options !== undefined;
+    const scopeId = scoped ? normalizeMcpScopeId(options) : null;
+    return [...callAdmissions.values()]
+      .filter((gate) => !scoped || gate.mcpScopeId === scopeId)
+      .map((gate) => ({
+        name: gate.mcpServerName,
+        scopeId: gate.mcpScopeId,
         ...gate.snapshot(),
     }));
 }
 
 /** Snapshot of MCP initialize `instructions` per connected server (handshake time). */
-export function getMcpServerInstructionsMap() {
+export function getMcpServerInstructionsMap(scopeId = DEFAULT_MCP_SCOPE_ID) {
     const out = {};
-    for (const server of servers.values()) {
+    for (const [, server] of scopedServerEntries(scopeId)) {
         const text = typeof server.instructions === 'string' ? server.instructions.trim() : '';
         if (text) out[server.name] = text;
     }
     return out;
 }
 
-async function reconnectMcpServer(serverName, failedServer) {
-    return reconnects.run(serverName, async () => {
-        const current = servers.get(serverName);
+async function reconnectMcpServer(scopeId, serverName, failedServer) {
+    const registryKey = mcpServerRegistryKey(scopeId, serverName);
+    return reconnects.run(registryKey, async () => {
+        const current = servers.get(registryKey);
         // A peer already completed the replacement while this failed call was
         // unwinding. Reuse it immediately instead of closing a fresh transport.
         if (current && current !== failedServer) return current;
         if (current) {
             await _closeServer(current);
-            if (servers.get(serverName) === current) servers.delete(serverName);
+            if (servers.get(registryKey) === current) servers.delete(registryKey);
         }
-        await connectServer(serverName, failedServer.cfg);
-        const replacement = servers.get(serverName);
+        await connectServer(serverName, failedServer.cfg, scopeId);
+        const replacement = servers.get(registryKey);
         if (!replacement) {
             throw new Error(`reconnect succeeded but server "${serverName}" entry is missing from registry`);
         }
@@ -247,7 +287,8 @@ export async function executeMcpTool(name, args, options = {}) {
     if (!match)
         throw new Error(`Not an MCP tool name: ${name}`);
     const [, serverName, toolName] = match;
-    const server = servers.get(serverName);
+    const scopeId = normalizeMcpScopeId(options);
+    const server = scopedServer(scopeId, serverName);
     if (!server)
         throw new Error(`MCP server "${serverName}" not connected`);
     const gate = callAdmissionFor(server);
@@ -264,7 +305,7 @@ export async function executeMcpTool(name, args, options = {}) {
             mcpLog(`[mcp-client] Tool call failed, attempting shared reconnect...\n`);
             let retryServer;
             try {
-                retryServer = await reconnectMcpServer(serverName, server);
+                retryServer = await reconnectMcpServer(scopeId, serverName, server);
             } catch (reconnectErr) {
                 const reconnectMsg = reconnectErr instanceof Error ? reconnectErr.message : String(reconnectErr);
                 throw new Error(`Tool call failed: ${firstMsg}; reconnect also failed: ${reconnectMsg}`);
@@ -415,12 +456,12 @@ export function isMcpTool(name) {
     return name.startsWith('mcp__');
 }
 /** True when the prefixed name exists on a connected MCP server. */
-export function isRegisteredMcpTool(name) {
+export function isRegisteredMcpTool(name, scopeId = DEFAULT_MCP_SCOPE_ID) {
     if (!isMcpTool(name)) return false;
     const match = name.match(/^mcp__(.+?)__(.+)$/);
     if (!match) return false;
     const [, serverName] = match;
-    const server = servers.get(serverName);
+    const server = scopedServer(scopeId, serverName);
     if (!server || !Array.isArray(server.tools)) return false;
     return server.tools.some((t) => t?.name === name);
 }
@@ -430,14 +471,15 @@ export function isRegisteredMcpTool(name) {
  * (e.g. cwd) into the args before dispatch — schemas that don't declare the
  * field would reject the unknown argument.
  */
-export function mcpToolHasField(name, field) {
-    const memoKey = `${name}|${field}`;
+export function mcpToolHasField(name, field, scopeId = DEFAULT_MCP_SCOPE_ID) {
+    const normalizedScopeId = normalizeMcpScopeId(scopeId);
+    const memoKey = `${normalizedScopeId}|${name}|${field}`;
     const memoized = _mcpToolFieldMemo.get(memoKey);
     if (memoized !== undefined) return memoized;
     const match = name.match(/^mcp__(.+?)__(.+)$/);
     if (!match) { _mcpToolFieldMemo.set(memoKey, false); return false; }
     const [, serverName] = match;
-    const server = servers.get(serverName);
+    const server = scopedServer(normalizedScopeId, serverName);
     if (!server) { _mcpToolFieldMemo.set(memoKey, false); return false; }
     const tool = server.tools.find((t) => t.name === name);
     if (!tool) { _mcpToolFieldMemo.set(memoKey, false); return false; }
@@ -449,14 +491,24 @@ export function mcpToolHasField(name, field) {
 /**
  * Disconnect all MCP servers.
  */
-export async function disconnectAll() {
+export async function disconnectAll(options = undefined) {
+    const hasExplicitScope = options && typeof options === 'object'
+        && Object.prototype.hasOwnProperty.call(options, 'scopeId');
+    const scopes = hasExplicitScope
+        ? new Set([normalizeMcpScopeId(options)])
+        : new Set([
+            ..._knownMcpScopes,
+            ...[...servers.values()].map((server) => server.scopeId),
+            ...[..._pendingConnects].map((entry) => entry.scopeId),
+        ]);
     // Abort handshakes still in flight: bump the generation so a connect that
     // completes after this point tears itself down instead of registering, and
     // reap any already-spawned stdio child now so its ref'd ChildProcess handle
     // can't keep the event loop alive (close-during-connect previously leaked
     // the uvx/npx wrapper tree and hung process exit).
-    _connectAbortGeneration++;
+    for (const scopeId of scopes) bumpConnectAbortGeneration(scopeId);
     for (const entry of [..._pendingConnects]) {
+        if (!scopes.has(entry.scopeId)) continue;
         _pendingConnects.delete(entry);
         // Mid-handshake child: nothing to shut down gracefully — hard-kill the
         // tree without holding the event loop (this path runs during process
@@ -466,13 +518,14 @@ export async function disconnectAll() {
         try { void entry.client.close().catch(() => { /* ignore */ }); }
         catch { /* ignore */ }
     }
-    for (const [name, server] of servers) {
+    for (const [registryKey, server] of [...servers]) {
+        if (!scopes.has(server.scopeId)) continue;
         try {
             await _closeServer(server);
         }
         catch { /* ignore */ }
-        servers.delete(name);
-        closeCallAdmission(name, `MCP ${name} disconnected`);
+        servers.delete(registryKey);
+        closeCallAdmission(server.scopeId, server.name, `MCP ${server.name} disconnected`);
     }
     _invalidateMcpToolFieldMemo();
 }
@@ -482,15 +535,17 @@ export async function disconnectAll() {
  * it, and invalidates the tool-field memo. Lets callers toggle one server
  * without a full disconnectAll()/reconnect cycle.
  */
-export async function disconnectMcpServer(name) {
-    const server = servers.get(name);
+export async function disconnectMcpServer(name, options = {}) {
+    const scopeId = normalizeMcpScopeId(options);
+    const registryKey = mcpServerRegistryKey(scopeId, name);
+    const server = servers.get(registryKey);
     if (!server) return false;
     try {
         await _closeServer(server);
     }
     catch { /* ignore */ }
-    servers.delete(name);
-    closeCallAdmission(name, `MCP ${name} disconnected`);
+    servers.delete(registryKey);
+    closeCallAdmission(scopeId, name, `MCP ${name} disconnected`);
     _invalidateMcpToolFieldMemo();
     return true;
 }
@@ -515,9 +570,9 @@ async function _closeServer(server) {
 // to see (and tear down) their transports, because `servers` only lists fully
 // handshaken entries. Generation token aborts a connect that outlives a
 // disconnectAll() issued mid-handshake (runtime close during boot connect).
-let _connectAbortGeneration = 0;
-const _pendingConnects = new Set();
-async function connectServer(name, cfg, genAtStart = _connectAbortGeneration) {
+async function connectServer(name, cfg, scopeId = DEFAULT_MCP_SCOPE_ID, genAtStart = currentConnectAbortGeneration(scopeId)) {
+    scopeId = normalizeMcpScopeId(scopeId);
+    _knownMcpScopes.add(scopeId);
     const {
         Client,
         StdioClientTransport,
@@ -525,7 +580,7 @@ async function connectServer(name, cfg, genAtStart = _connectAbortGeneration) {
         SSEClientTransport,
         WebSocketClientTransport,
     } = await loadMcpSdk();
-    if (genAtStart !== _connectAbortGeneration) {
+    if (genAtStart !== currentConnectAbortGeneration(scopeId)) {
         // disconnectAll() ran while the SDK was loading: nothing spawned yet —
         // abort before creating a transport/child at all.
         throw new Error(`MCP server "${name}" connect aborted by shutdown`);
@@ -623,7 +678,7 @@ async function connectServer(name, cfg, genAtStart = _connectAbortGeneration) {
     else {
         throw new Error(`Invalid config for "${name}": need autoDetect, type (stdio/http/sse/ws), url (http), or command (stdio)`);
     }
-    const pending = { name, client, transport };
+    const pending = { scopeId, name, client, transport };
     _pendingConnects.add(pending);
     try {
         // Bound the connect + listTools handshake so a slow/hung server can't
@@ -682,7 +737,7 @@ async function connectServer(name, cfg, genAtStart = _connectAbortGeneration) {
         if (!toolsResult || !Array.isArray(toolsResult.tools)) {
             throw new Error(`[mcp-client] ListTools returned invalid shape for "${name}": missing or non-array tools field`);
         }
-        if (genAtStart !== _connectAbortGeneration) {
+        if (genAtStart !== currentConnectAbortGeneration(scopeId)) {
             // disconnectAll() ran mid-handshake: never register — tear down.
             try { await _closeServer({ client, transport }); }
             catch { /* ignore */ }
@@ -695,7 +750,18 @@ async function connectServer(name, cfg, genAtStart = _connectAbortGeneration) {
             ...(t.annotations && typeof t.annotations === 'object' ? { annotations: t.annotations } : {}),
         }));
         const toolNames = tools.map(t => t.name);
-        servers.set(name, { name, client, transport, tools, cfg, instructions, generation: genAtStart });
+        const registryKey = mcpServerRegistryKey(scopeId, name);
+        servers.set(registryKey, {
+            scopeId,
+            registryKey,
+            name,
+            client,
+            transport,
+            tools,
+            cfg,
+            instructions,
+            generation: genAtStart,
+        });
         _invalidateMcpToolFieldMemo();
         mcpLog(`[mcp] connected: ${tools.length} tools — ${toolNames.join(', ')}\n`);
     }
@@ -703,3 +769,36 @@ async function connectServer(name, cfg, genAtStart = _connectAbortGeneration) {
         _pendingConnects.delete(pending);
     }
 }
+
+// Test seam for registry scoping without launching an MCP transport.
+export function _registerMcpServerForTest(scopeId, name, rawTools = [], options = {}) {
+    const normalizedScopeId = normalizeMcpScopeId(scopeId);
+    const registryKey = mcpServerRegistryKey(normalizedScopeId, name);
+    const tools = rawTools.map((tool) => ({
+        ...tool,
+        name: String(tool?.name || '').startsWith('mcp__')
+            ? String(tool.name)
+            : `mcp__${name}__${String(tool?.name || '')}`,
+        inputSchema: tool?.inputSchema || { type: 'object', properties: {} },
+    }));
+    const server = {
+        scopeId: normalizedScopeId,
+        registryKey,
+        name,
+        tools,
+        cfg: options.cfg || {},
+        instructions: options.instructions || '',
+        transport: null,
+        client: {
+            callTool: typeof options.callTool === 'function'
+                ? options.callTool
+                : async () => ({ content: [{ type: 'text', text: 'ok' }] }),
+            close: async () => {},
+        },
+        generation: currentConnectAbortGeneration(normalizedScopeId),
+    };
+    _knownMcpScopes.add(normalizedScopeId);
+    servers.set(registryKey, server);
+    _invalidateMcpToolFieldMemo();
+    return server;
+}

package/src/runtime/agent/orchestrator/session/loop/tool-exec.mjs

@@ -178,7 +178,8 @@ async function executeToolOwned(name, args, cwd, callerSessionId, sessionRef, ex
         return viewSkill(cwd, args?.name);
     }
     if (isMcpTool(name)) {
-        if (!isOnDeferredToolSurface(sessionRef, name) && !isRegisteredMcpTool(name)) {
+        const mcpScopeId = sessionRef?.mcpScopeId || null;
+        if (!isOnDeferredToolSurface(sessionRef, name) && !isRegisteredMcpTool(name, mcpScopeId)) {
             return formatUnknownBuiltinToolMessage(name, args, 'tool');
         }
         // 24h trace data shows ~24% of external MCP calls are cwd-sensitive
@@ -187,12 +188,13 @@ async function executeToolOwned(name, args, cwd, callerSessionId, sessionRef, ex
         // inputSchema declares the field — schemas without it would reject
         // an unknown argument.
         const needsCwdInjection = cwd
-            && mcpToolHasField(name, 'cwd')
+            && mcpToolHasField(name, 'cwd', mcpScopeId)
             && (args == null || args.cwd == null);
         const finalArgs = needsCwdInjection ? { ...(args || {}), cwd } : args;
         return executeMcpTool(name, finalArgs, {
             signal: executeOpts.signal || null,
             ownerKey: callerSessionId,
+            scopeId: mcpScopeId,
         });
     }
     if (name === 'code_graph') {

package/src/runtime/agent/orchestrator/session/manager/session-lifecycle.mjs

@@ -249,7 +249,10 @@ export function createSession(opts) {
     const toolSpec = ownerIsAgent
         ? (isReadOnlyAgentBundle ? 'readonly' : 'full')
         : (Array.isArray(profile?.tools) ? profile.tools : toolPreset);
-    let toolsForRouting = resolveSessionTools(toolSpec, skills, { ownerIsAgentSession: ownerIsAgent });
+    let toolsForRouting = resolveSessionTools(toolSpec, skills, {
+        ownerIsAgentSession: ownerIsAgent,
+        mcpScopeId: opts.mcpScopeId || null,
+    });
     // Fail-closed permission intersection: when a session declares an explicit
     // object-form permission, intersect the
     // resolved tool list with the permission's allow/deny lists. If the
@@ -371,6 +374,7 @@ export function createSession(opts) {
         agent: opts.agent,
         owner: opts.owner || 'user',
         mcpPid: process.pid,
+        mcpScopeId: opts.mcpScopeId || null,
         scopeKey: opts.scopeKey || null,
         lane: opts.lane || 'agent',
         cwd: opts.cwd,
@@ -530,7 +534,10 @@ function _prepareResumeTools(session, preset) {
             if (!ownerIsAgent && Array.isArray(profile?.tools)) toolSpec = profile.tools;
         } catch { /* ignore lookup failures, keep preset fallback */ }
     }
-    let toolsForRouting = resolveSessionTools(toolSpec, skills, { ownerIsAgentSession: ownerIsAgent });
+    let toolsForRouting = resolveSessionTools(toolSpec, skills, {
+        ownerIsAgentSession: ownerIsAgent,
+        mcpScopeId: session.mcpScopeId || null,
+    });
     if (ownerIsAgent) {
         toolsForRouting = applyToolPermissionNarrowing(toolsForRouting, session.toolPermission, session.agent || null);
     }
@@ -563,8 +570,10 @@ function _rememberPreparedResume(sessionId, prepared) {
 
 function _preparedResumeForSession(session, preset) {
     const cached = _preparedResumes.get(session.id);
-    if (cached?.session === session && cached?.preset === preset) return cached;
+    if (cached?.session === session && cached?.preset === preset
+        && cached?.mcpScopeId === (session.mcpScopeId || null)) return cached;
     const prepared = _prepareResumeTools(session, preset);
+    prepared.mcpScopeId = session.mcpScopeId || null;
     _rememberPreparedResume(session.id, prepared);
     return prepared;
 }
@@ -745,6 +754,9 @@ export async function resumeSession(sessionId, preset, options = {}) {
         session.desktopSession = expectedDesktop;
     }
     if (!session.owner) session.owner = 'user';
+    if (Object.prototype.hasOwnProperty.call(options, 'mcpScopeId')) {
+        session.mcpScopeId = String(options.mcpScopeId || '').trim() || null;
+    }
     if (_isActivelyOwnedElsewhere(session, sessionId)) {
         // ATTACH (viewer mode, zero ownership): hand back the live transcript
         // under the SAME id, flagged remoteAttached. No tool refresh, no save,
@@ -764,6 +776,7 @@ export async function resumeSession(sessionId, preset, options = {}) {
     const cached = _preparedResumes.get(sessionId);
     _preparedResumes.delete(sessionId);
     const prepared = cached?.session === session && cached?.preset === preset
+        && cached?.mcpScopeId === (session.mcpScopeId || null)
         ? cached
         : _prepareResumeTools(session, preset);
     // Keep the persisted tool mode in sync on resume (see createSession note).

package/src/runtime/agent/orchestrator/session/manager/tool-resolution.mjs

@@ -18,8 +18,8 @@ import { getHiddenAgent, listHiddenAgentNames } from '../../internal-agents.mjs'
 // tools array verbatim, so any reorder rewrites the prefix.
 // No cache: getMcpTools() and getInternalTools() are O(n) in-memory reads;
 // the sort overhead on ~30 tools is negligible.
-function _getMcpTools() {
-    const mcp = getMcpTools() || [];
+function _getMcpTools(mcpScopeId = null) {
+    const mcp = getMcpTools(mcpScopeId) || [];
     // `public:false` tools stay registered in internal-tools for runtime
     // rewrites/dispatch, but must never enter any model-visible schema (Lead
     // full/mcp included). Filter before mapping because the projection below
@@ -229,8 +229,8 @@ const ALL_BUILTIN_SESSION_TOOLS = orderSessionTools(_dedupByName([
     ...CODE_GRAPH_TOOL_DEFS,
 ]));
 
-export function resolveSessionTools(toolSpec, skills, { ownerIsAgentSession = false } = {}) {
-    const mcp = _getMcpTools();
+export function resolveSessionTools(toolSpec, skills, { ownerIsAgentSession = false, mcpScopeId = null } = {}) {
+    const mcp = _getMcpTools(mcpScopeId);
     // Agent sessions freeze the skill meta-tool into the schema
     // unconditionally — concrete skill resolution is cwd-scoped at tool-call
     // time (loop.mjs), so the schema bytes stay bit-identical across roles /

package/src/session-runtime/lifecycle-api.mjs

@@ -40,6 +40,7 @@ export function createLifecycleApi(deps) {
   const cancelBackgroundTasksForLifecycle = deps.cancelBackgroundTasks || cancelBackgroundTasks;
   const {
     getSession, setSession, getRoute, setRoute, getConfig, getMode, getCurrentCwd,
+    getMcpScopeId,
     getDesktopSession, setDesktopSession,
     setCloseRequested, getMemoryModPromise, setMemoryModPromise,
     setSessionNeedsCwdRefresh,
@@ -263,7 +264,7 @@ export function createLifecycleApi(deps) {
       const channelStop = channels.stop(reason, detach ? { waitForExit: false } : undefined);
       try { agentTool.closeAll(reason); } catch {}
       let mcpStop = null;
-      try { mcpStop = mcpClient.disconnectAll?.(); } catch {}
+      try { mcpStop = mcpClient.disconnectAll?.({ scopeId: getMcpScopeId?.() }); } catch {}
       const openaiWsStop = isProcessExit && globalThis.__mixdogOpenaiWsRuntimeLoaded === true
         ? import('../runtime/agent/orchestrator/providers/openai-oauth-ws.mjs')
           .then((mod) => mod?.drainOpenaiWsPool?.(reason))
@@ -520,9 +521,12 @@ export function createLifecycleApi(deps) {
       const activeDesktopSession = typeof getDesktopSession === 'function'
         ? getDesktopSession()
         : desktopSession;
-      const resumeOptions = activeDesktopSession && typeof activeDesktopSession === 'object'
-        ? { desktopSession: activeDesktopSession }
-        : undefined;
+      const resumeOptions = {
+        ...(activeDesktopSession && typeof activeDesktopSession === 'object'
+          ? { desktopSession: activeDesktopSession }
+          : {}),
+        mcpScopeId: getMcpScopeId?.() || null,
+      };
       const resumed = await mgr.resumeSession(id, toolSpecForMode(getMode()), resumeOptions);
       if (!resumed) return null;
       if (previousId && previousId !== resumed.id) {

package/src/session-runtime/mcp-glue.mjs

@@ -33,8 +33,10 @@ export function createMcpGlue({
   mcpClient,
   getConfig,
   getCurrentCwd,
+  getMcpScopeId = () => null,
   state,
 }) {
+  const scopeOptions = () => ({ scopeId: getMcpScopeId() });
   function mcpTransportLabel(cfg = {}) {
     if (cfg.autoDetect) return `autoDetect:${cfg.autoDetect}`;
     try {
@@ -77,7 +79,7 @@ export function createMcpGlue({
       return { servers: [], configuredCount: 0, connectedCount: 0, failedCount: 0 };
     }
     const { servers: configured, sources } = resolveEffectiveMcpServers();
-    const connected = new Map((mcpClient.getMcpServerStatus?.() || []).map((row) => [row.name, row]));
+    const connected = new Map((mcpClient.getMcpServerStatus?.(getMcpScopeId()) || []).map((row) => [row.name, row]));
     const failures = new Map((state.mcpFailures || []).map((row) => [row.name, row]));
     const servers = [];
     for (const [name, cfg] of Object.entries(configured)) {
@@ -125,16 +127,16 @@ export function createMcpGlue({
       state.mcpFailures = state.mcpFailures.filter((row) => row.name !== target);
     }
     if (enabled === false) {
-      await mcpClient.disconnectMcpServer?.(target);
+      await mcpClient.disconnectMcpServer?.(target, scopeOptions());
       return;
     }
     const cfg = servers[target];
     if (!cfg) return;
     // Drop any existing live entry first so connectMcpServers doesn't overwrite
     // the registry Map entry and leak the old transport/process.
-    await mcpClient.disconnectMcpServer?.(target);
+    await mcpClient.disconnectMcpServer?.(target, scopeOptions());
     try {
-      await mcpClient.connectMcpServers({ [target]: cfg });
+      await mcpClient.connectMcpServers({ [target]: cfg }, scopeOptions());
     } catch (error) {
       const failures = Array.isArray(error?.failures)
         ? error.failures
@@ -147,8 +149,8 @@ export function createMcpGlue({
     if (envFlag('MIXDOG_DISABLE_MCP')) {
       ++state.mcpConnectGeneration;
       state.mcpFailures = [];
-      if (only) await mcpClient.disconnectMcpServer?.(only);
-      else await mcpClient.disconnectAll?.();
+      if (only) await mcpClient.disconnectMcpServer?.(only, scopeOptions());
+      else await mcpClient.disconnectAll?.(scopeOptions());
       return mcpStatus();
     }
     // Scoped single-server toggle: non-superseding. It must NEVER cancel a
@@ -192,12 +194,12 @@ export function createMcpGlue({
     }
     if (gen !== state.mcpConnectGeneration) return mcpStatus();
     const run = (async () => {
-      if (reset) await mcpClient.disconnectAll?.();
+      if (reset) await mcpClient.disconnectAll?.(scopeOptions());
       state.mcpFailures = [];
       const { servers } = resolveEffectiveMcpServers();
       if (Object.keys(servers).length === 0) return;
       try {
-        await mcpClient.connectMcpServers(servers);
+        await mcpClient.connectMcpServers(servers, scopeOptions());
       } catch (error) {
         state.mcpFailures = Array.isArray(error?.failures)
           ? error.failures

package/src/session-runtime/runtime-core.mjs

@@ -4,6 +4,7 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSy
 import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
 import { performance } from 'node:perf_hooks';
 import { fileURLToPath } from 'node:url';
+import { randomUUID } from 'node:crypto';
 import keychain from '../lib/keychain-cjs.cjs';
 import './hitch-profile.mjs';
 import { ensureStandaloneEnvironment } from '../standalone/seeds.mjs';
@@ -335,6 +336,7 @@ export async function createMixdogSessionRuntime({
   // Shared mutable runtime state, promoted from closure `let`s so extracted
   // modules can read/write live values through one reference.
   const rt = {};
+  rt.mcpScopeId = randomUUID();
   rt.desktopSession = initialDesktopSession;
   // Agent shard spread: a daemon-hosted worker runtime carries the resolved
   // agent session spec; session creation routes through prepareAgentSession
@@ -656,6 +658,7 @@ export async function createMixdogSessionRuntime({
     mcpClient,
     getConfig: () => rt.config,
     getCurrentCwd: () => rt.currentCwd,
+    getMcpScopeId: () => rt.mcpScopeId,
     getDesktopSession: () => rt.desktopSession,
     setDesktopSession: (v) => { rt.desktopSession = v; },
     state: mcpState,
@@ -750,6 +753,7 @@ export async function createMixdogSessionRuntime({
     mgr,
     dataDir: cfgMod.getPluginData(),
     cwd,
+    mcpScopeId: rt.mcpScopeId,
     awaitKeychainPrewarm,
     isKeychainPrewarmReady: () => rt.keychainPrewarmWaitDone,
     // SubagentStart/SubagentStop: bridge internal worker spawn/finish to the
@@ -843,6 +847,7 @@ export async function createMixdogSessionRuntime({
     getSession: () => rt.session,
     getRoute: () => rt.route,
     getConfig: () => rt.config,
+    getMcpScopeId: () => rt.mcpScopeId,
     cfgMod,
     loadWorkflowPack,
     activeWorkflowId,
@@ -854,6 +859,7 @@ export async function createMixdogSessionRuntime({
     getSession: () => rt.session,
     getRoute: () => rt.route,
     getCurrentCwd: () => rt.currentCwd,
+    getMcpScopeId: () => rt.mcpScopeId,
     getMode: () => rt.mode,
   });
   const computeContextStatusForSession = (session) => {

package/src/session-runtime/session-lifecycle.mjs

@@ -183,6 +183,7 @@ export function createSessionLifecycle({
         if (rt.closeRequested) throw new Error('runtime is closing');
         const { session } = prepareAgentSession({
           ...rt.agentSessionSpec,
+          mcpScopeId: rt.mcpScopeId,
           ...(rt.reservedSessionId ? { sessionId: rt.reservedSessionId } : {}),
         });
         rt.session = session;
@@ -232,6 +233,7 @@ export function createSessionLifecycle({
         sourceType: 'lead',
         sourceName: 'main',
         clientHostPid: process.pid,
+        mcpScopeId: rt.mcpScopeId,
         disallowedTools: [...LEAD_DISALLOWED_TOOLS, ...featureDisallowedTools()],
         cwd: rt.currentCwd,
         ...(rt.desktopSession && typeof rt.desktopSession === 'object' ? { desktopSession: rt.desktopSession } : {}),
@@ -258,7 +260,7 @@ export function createSessionLifecycle({
       // prompt renders. This fold keeps recreate paths (cwd change with MCP
       // already connected) seeding their manifest instead of re-announcing late.
       let connectedMcpTools = [];
-      try { connectedMcpTools = mcpClient.getMcpTools?.() || []; }
+      try { connectedMcpTools = mcpClient.getMcpTools?.(rt.mcpScopeId) || []; }
       catch { connectedMcpTools = []; }
       applyDeferredToolSurface(
         rt.session,

package/src/session-runtime/session-turn-api.mjs

@@ -246,7 +246,7 @@ export function createSessionTurnApi(deps) {
           // Slower servers remain available through the late-tool path.
           try { await awaitTurn(() => awaitMcpGrace()); }
           catch { /* gate must never break the turn */ }
-          try { refreshInitialDeferredMcpSurface(session0, getMcpTools()); }
+          try { refreshInitialDeferredMcpSurface(session0, getMcpTools(session0.mcpScopeId)); }
           catch { /* first-turn MCP fold must never break the turn */ }
         } else {
           // AFTER FIRST TURN: fold in MCP tools whose servers finished their
@@ -263,7 +263,7 @@ export function createSessionTurnApi(deps) {
           try { await awaitTurn(() => awaitMcpGrace()); }
           catch { /* gate must never break the turn */ }
           try {
-            reconcileDeferredMcpToolCatalog(session0, getMcpTools(), {
+            reconcileDeferredMcpToolCatalog(session0, getMcpTools(session0.mcpScopeId), {
               // Deliver the late-tool announcement through the pending-message
               // queue so it rides inside the next real user turn as a persisted
               // system-reminder (no synthetic user + '.' assistant pair).

package/src/session-runtime/tool-catalog.mjs

@@ -311,7 +311,7 @@ export function applyDeferredToolSurface(session, mode, extraTools = [], options
   }
   if (!session.deferredToolBp1Applied && session.messages?.some((m) => m?.role === 'system')) {
     if (!session.mcpServerInstructions || typeof session.mcpServerInstructions !== 'object') {
-      session.mcpServerInstructions = getMcpServerInstructionsMap();
+      session.mcpServerInstructions = getMcpServerInstructionsMap(session.mcpScopeId);
     }
     applyInitialDeferredToolManifestToBp1(session, deferredPoolToolNames(session));
   }
@@ -352,7 +352,7 @@ export function rebuildDeferredToolSurfaceForProvider(session, provider) {
   }
   if (previousMode && previousMode !== session.deferredProviderMode) {
     if (session.deferredProviderMode === 'native') {
-      session.mcpServerInstructions = getMcpServerInstructionsMap();
+      session.mcpServerInstructions = getMcpServerInstructionsMap(session.mcpScopeId);
       applyInitialDeferredToolManifestToBp1(session, deferredPoolToolNames(session), { rebuild: true });
       const rendered = session.messages?.find((message) => message?.role === 'system')?.content;
       session.deferredAnnouncedTools = deferredPoolToolNames(session)
@@ -409,7 +409,7 @@ export function refreshInitialDeferredMcpSurface(session, liveMcpTools) {
   }
   // Refresh MCP server instructions so a newly-connected server's block is
   // included when BP1 is re-rendered below.
-  session.mcpServerInstructions = getMcpServerInstructionsMap();
+  session.mcpServerInstructions = getMcpServerInstructionsMap(session.mcpScopeId);
   const applied = applyInitialDeferredToolManifestToBp1(session, deferredPoolToolNames(session), { rebuild: true });
   if (!applied) return false;
   // Pre-mark ONLY the names that ACTUALLY landed in the rebuilt BP1 manifest as

package/src/session-runtime/tool-surface.mjs

@@ -17,6 +17,7 @@ export function createToolSurface({
   getSession,
   getRoute,
   getConfig,
+  getMcpScopeId = () => null,
   cfgMod,
   loadWorkflowPack,
   activeWorkflowId,
@@ -62,13 +63,13 @@ export function createToolSurface({
 
   function buildPreSessionSurface() {
     const previewTools = typeof mgr.previewSessionTools === 'function'
-      ? mgr.previewSessionTools(toolSpecForMode(mode), [])
+      ? mgr.previewSessionTools(toolSpecForMode(mode), [], { mcpScopeId: getMcpScopeId() })
       : [];
     const tools = filterDisallowedTools(previewTools, [
       ...LEAD_DISALLOWED_TOOLS,
       ...getFeatureDisallowedTools(),
     ]);
-    const surface = { tools: Array.isArray(tools) ? tools.slice() : [] };
+    const surface = { tools: Array.isArray(tools) ? tools.slice() : [], mcpScopeId: getMcpScopeId() };
     applyDeferredToolSurface(surface, deferredSurfaceModeForLead(mode), modelStandaloneTools(), {
       provider: getRoute().provider,
     });

package/src/standalone/agent-tool/spawn-flow.mjs

@@ -25,6 +25,7 @@ export function createSpawnFlow({
   upsertWorkerSessionDeferred,
   refreshTagsFromSessions,
   defaultCwd,
+  mcpScopeId = null,
   nextTag,
   cancelReap,
   bindTag,
@@ -228,6 +229,7 @@ export function createSpawnFlow({
       maxLoopIterations: positiveInt(args.maxLoopIterations) || undefined,
       permission: agentPerm || undefined,
       cacheKeyOverride: args.cacheKey || undefined,
+      mcpScopeId,
     };
   }
 

package/src/standalone/agent-tool.mjs

@@ -89,6 +89,7 @@ export function createStandaloneAgent({
   mgr: baseMgr,
   dataDir,
   cwd: defaultCwd,
+  mcpScopeId = null,
   onSubagentEvent,
   awaitKeychainPrewarm = async () => {},
   isKeychainPrewarmReady = () => true,
@@ -213,6 +214,7 @@ export function createStandaloneAgent({
       refreshTagsFromSessions,
       readWorkerRows,
       defaultCwd,
+      mcpScopeId,
       nextTag,
       cancelReap,
       bindTag,