typeclaw 0.21.0 → 0.23.0

package/src/mcp/manager.ts

@@ -0,0 +1,156 @@
+import type { McpServer } from '@/config/config'
+
+import { connectMcpServer, type McpConnection } from './client'
+
+const TOOL_NAMESPACE_SEPARATOR = '__'
+
+export type McpConnectResult =
+  | { ok: true; name: string; connection: McpConnection; toolCount: number }
+  | { ok: false; name: string; error: Error }
+
+export type McpRefreshResult = { ok: true; name: string; toolCount: number } | { ok: false; name: string; error: Error }
+
+export type McpManager = {
+  connectAll(opts?: { signal?: AbortSignal }): Promise<McpConnectResult[]>
+  getConnection(name: string): McpConnection | undefined
+  listServers(): { name: string; description?: string; connected: boolean; toolCount?: number }[]
+  refresh(): Promise<McpRefreshResult[]>
+  closeAll(): Promise<void>
+}
+
+export type ConnectMcpServerFn = (
+  server: McpServer,
+  opts: { env: NodeJS.ProcessEnv; signal?: AbortSignal },
+) => Promise<McpConnection>
+
+export function createMcpManager(
+  servers: McpServer[],
+  opts: { env: NodeJS.ProcessEnv; connect?: ConnectMcpServerFn },
+): McpManager {
+  const activeServers = servers.filter((server) => server.enabled)
+  const connect = opts.connect ?? connectMcpServer
+  const connections = new Map<string, McpConnection>()
+  const toolCounts = new Map<string, number>()
+
+  return {
+    async connectAll(connectOpts: { signal?: AbortSignal } = {}): Promise<McpConnectResult[]> {
+      const firstIndexByName = new Map<string, number>()
+      const results = await Promise.all(
+        activeServers.map((server, index): Promise<McpConnectResult> => {
+          // The name is the tool namespace and the connections key, so a second
+          // server sharing a name would silently shadow the first. Fail the
+          // duplicate fast instead of connecting it, keeping routing unambiguous.
+          const firstIndex = firstIndexByName.get(server.name)
+          if (firstIndex !== undefined) {
+            return Promise.resolve({
+              ok: false,
+              name: server.name,
+              error: new Error(
+                `mcpServers[${index}].name duplicates mcpServers[${firstIndex}].name ('${server.name}')`,
+              ),
+            })
+          }
+          firstIndexByName.set(server.name, index)
+          return connectOne(server, opts.env, connect, connectOpts.signal)
+        }),
+      )
+      for (const result of results) {
+        if (!result.ok) continue
+        connections.set(result.name, result.connection)
+        toolCounts.set(result.name, result.toolCount)
+      }
+      return results
+    },
+    getConnection(name: string): McpConnection | undefined {
+      return connections.get(name)
+    },
+    listServers(): { name: string; description?: string; connected: boolean; toolCount?: number }[] {
+      return activeServers.map((server) => {
+        const toolCount = toolCounts.get(server.name)
+        return {
+          name: server.name,
+          connected: connections.has(server.name),
+          ...(server.description === undefined ? {} : { description: server.description }),
+          ...(toolCount === undefined ? {} : { toolCount }),
+        }
+      })
+    },
+    async refresh(): Promise<McpRefreshResult[]> {
+      // One unhealthy connection must not discard healthy servers' tool-count
+      // updates, so each refresh is isolated and reported per-server instead of
+      // letting a single rejection fail the whole batch.
+      return Promise.all(
+        [...connections.entries()].map(async ([name, connection]): Promise<McpRefreshResult> => {
+          try {
+            const tools = await connection.refresh()
+            toolCounts.set(name, tools.length)
+            return { ok: true, name, toolCount: tools.length }
+          } catch (cause) {
+            return { ok: false, name, error: normalizeError(cause) }
+          }
+        }),
+      )
+    },
+    async closeAll(): Promise<void> {
+      await Promise.allSettled([...connections.values()].map((connection) => connection.close()))
+      connections.clear()
+      toolCounts.clear()
+    },
+  }
+}
+
+export function namespaceToolName(server: string, tool: string): string {
+  return `${server}${TOOL_NAMESPACE_SEPARATOR}${tool}`
+}
+
+export function parseNamespacedTool(namespaced: string): { server: string; tool: string } | undefined {
+  // Config validation reserves `__` out of server names; splitting on the first
+  // separator is therefore unambiguous even when MCP tool names contain it.
+  const separatorIndex = namespaced.indexOf(TOOL_NAMESPACE_SEPARATOR)
+  if (separatorIndex <= 0) return undefined
+
+  const toolStart = separatorIndex + TOOL_NAMESPACE_SEPARATOR.length
+  if (toolStart >= namespaced.length) return undefined
+
+  return { server: namespaced.slice(0, separatorIndex), tool: namespaced.slice(toolStart) }
+}
+
+async function connectOne(
+  server: McpServer,
+  env: NodeJS.ProcessEnv,
+  connect: ConnectMcpServerFn,
+  signal: AbortSignal | undefined,
+): Promise<McpConnectResult> {
+  let connection: McpConnection | undefined
+  try {
+    connection = await connect(server, { env, signal })
+    const tools = await connection.listTools()
+    return { ok: true, name: server.name, connection, toolCount: tools.length }
+  } catch (cause) {
+    const closeError = connection === undefined ? undefined : await closeAfterFailedCatalog(connection)
+    if (closeError !== undefined) {
+      return {
+        ok: false,
+        name: server.name,
+        error: new Error(`MCP server "${server.name}" failed to connect and then failed to close`, {
+          cause: { original: cause, close: closeError },
+        }),
+      }
+    }
+    return { ok: false, name: server.name, error: normalizeError(cause) }
+  }
+}
+
+async function closeAfterFailedCatalog(connection: McpConnection): Promise<Error | undefined> {
+  try {
+    await connection.close()
+    return undefined
+  } catch (cause) {
+    return normalizeError(cause)
+  }
+}
+
+function normalizeError(cause: unknown): Error {
+  if (cause instanceof Error) return cause
+  return new Error(String(cause))
+}

package/src/mcp/tools.ts

@@ -0,0 +1,190 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js'
+import { z } from 'zod'
+
+import { defineTool } from '@/plugin/define'
+import type { ContentPart, Tool, ToolResult } from '@/plugin/types'
+
+import type { McpConnection, McpToolInfo } from './client'
+import type { McpManager } from './manager'
+import { namespaceToolName, parseNamespacedTool } from './manager'
+
+export const MCP_DISPATCHER_TOOL_NAMES = ['mcp_list_tools', 'mcp_describe', 'mcp_call'] as const
+
+export type McpListToolsArgs = { server: string }
+export type McpDescribeArgs = { server: string; tool: string }
+export type McpCallArgs = { server: string; tool: string; args?: Record<string, unknown> }
+export type McpDispatcherTool = Tool<McpListToolsArgs> | Tool<McpDescribeArgs> | Tool<McpCallArgs>
+export type McpDispatcherTools = [Tool<McpListToolsArgs>, Tool<McpDescribeArgs>, Tool<McpCallArgs>]
+
+export function createMcpDispatcherTools(manager: McpManager): McpDispatcherTools {
+  return [createListToolsTool(manager), createDescribeTool(manager), createCallTool(manager)]
+}
+
+function createListToolsTool(manager: McpManager): Tool<McpListToolsArgs> {
+  return defineTool<McpListToolsArgs>({
+    description: 'List the tools exposed by one connected MCP server. Returns namespaced tool ids and descriptions.',
+    parameters: z.object({
+      server: z.string().describe('The MCP server name from the system prompt catalog.'),
+    }),
+    async execute(args) {
+      const connection = manager.getConnection(args.server)
+      if (connection === undefined) return textResult(unknownServerMessage(manager, args.server))
+
+      const tools = await safeListTools(connection)
+      if (tools.length === 0) return textResult(`MCP server ${JSON.stringify(args.server)} exposes no tools.`)
+
+      const lines = tools.map((tool) => {
+        const description = tool.description.trim() === '' ? 'no description' : tool.description.trim()
+        return `- ${namespaceToolName(args.server, tool.name)} — ${description}`
+      })
+      return textResult(`Tools for MCP server ${JSON.stringify(args.server)}:\n${lines.join('\n')}`)
+    },
+  })
+}
+
+function createDescribeTool(manager: McpManager): Tool<McpDescribeArgs> {
+  return defineTool<McpDescribeArgs>({
+    description: 'Describe one MCP tool. Returns its description and full input JSON Schema.',
+    parameters: z.object({
+      server: z.string().describe('The MCP server name from the system prompt catalog.'),
+      tool: z.string().describe('The bare tool name or namespaced server__tool id.'),
+    }),
+    async execute(args) {
+      const resolved = resolveToolArgs(args.server, args.tool)
+      const connection = manager.getConnection(resolved.server)
+      if (connection === undefined) return textResult(unknownServerMessage(manager, resolved.server))
+
+      const tools = await safeListTools(connection)
+      const tool = tools.find((item) => item.name === resolved.tool)
+      if (tool === undefined) {
+        const available = tools.map((item) => namespaceToolName(resolved.server, item.name)).join(', ')
+        return textResult(
+          `Unknown MCP tool ${JSON.stringify(resolved.tool)} on server ${JSON.stringify(resolved.server)}. Available tools: ${available || 'none'}.`,
+        )
+      }
+
+      const description = tool.description.trim() === '' ? 'no description' : tool.description.trim()
+      return textResult(
+        [
+          `MCP tool ${namespaceToolName(resolved.server, tool.name)}`,
+          `Description: ${description}`,
+          '',
+          'Input schema:',
+          '```json',
+          JSON.stringify(tool.inputSchema, null, 2),
+          '```',
+        ].join('\n'),
+      )
+    },
+  })
+}
+
+function createCallTool(manager: McpManager): Tool<McpCallArgs> {
+  return defineTool<McpCallArgs>({
+    description: 'Call an MCP tool on a connected server. Use mcp_describe first to learn the input schema.',
+    parameters: z.object({
+      server: z.string().describe('The MCP server name from the system prompt catalog.'),
+      tool: z.string().describe('The bare tool name or namespaced server__tool id.'),
+      args: z.record(z.string(), z.unknown()).optional().describe('Arguments matching the tool input schema.'),
+    }),
+    async execute(args) {
+      const resolved = resolveToolArgs(args.server, args.tool)
+      const connection = manager.getConnection(resolved.server)
+      if (connection === undefined) return textResult(unknownServerMessage(manager, resolved.server))
+
+      const result = await safeCallTool(connection, resolved.tool, args.args ?? {})
+      return mapCallToolResult(resolved.server, resolved.tool, result)
+    },
+  })
+}
+
+function resolveToolArgs(server: string, tool: string): { server: string; tool: string } {
+  const parsed = parseNamespacedTool(tool)
+  return parsed ?? { server, tool }
+}
+
+function unknownServerMessage(manager: McpManager, server: string): string {
+  const available = manager
+    .listServers()
+    .filter((entry) => entry.connected)
+    .map((entry) => entry.name)
+    .join(', ')
+  return `Unknown MCP server ${JSON.stringify(server)}. Available servers: ${available || 'none'}.`
+}
+
+async function safeListTools(connection: McpConnection): Promise<McpToolInfo[]> {
+  try {
+    return await connection.listTools()
+  } catch (cause) {
+    throw new Error(`MCP list tools failed: ${sanitizeMcpError(errorMessage(cause))}`)
+  }
+}
+
+async function safeCallTool(
+  connection: McpConnection,
+  tool: string,
+  args: Record<string, unknown>,
+): Promise<CallToolResult> {
+  try {
+    return await connection.callTool(tool, args)
+  } catch (cause) {
+    throw new Error(`MCP call failed: ${sanitizeMcpError(errorMessage(cause))}`)
+  }
+}
+
+function mapCallToolResult(server: string, tool: string, result: CallToolResult): ToolResult {
+  const content = result.content.map(mapMcpContentPart)
+  if (result.isError === true) {
+    return {
+      content: content.map((part) =>
+        part.type === 'text' ? { type: 'text' as const, text: `MCP tool error: ${sanitizeMcpError(part.text)}` } : part,
+      ),
+      details: { server, tool, isError: true },
+    }
+  }
+  return { content, details: { server, tool, isError: false } }
+}
+
+function mapMcpContentPart(part: CallToolResult['content'][number]): ContentPart {
+  if (part.type === 'text' && typeof part.text === 'string') return { type: 'text', text: part.text }
+  if (part.type === 'image' && typeof part.data === 'string' && typeof part.mimeType === 'string') {
+    return { type: 'image', mimeType: part.mimeType, data: part.data }
+  }
+  return { type: 'text', text: summarizeUnsupportedPart(part) }
+}
+
+function summarizeUnsupportedPart(part: CallToolResult['content'][number]): string {
+  const type = typeof part.type === 'string' ? part.type : 'unknown'
+  const uri = readNestedString(part, 'resource', 'uri') ?? readString(part, 'uri')
+  if (uri !== undefined) return `[mcp:${type} ${uri}]`
+  const mimeType = readNestedString(part, 'resource', 'mimeType') ?? readString(part, 'mimeType')
+  if (mimeType !== undefined) return `[mcp:${type} ${mimeType}]`
+  return `[mcp:${type} omitted]`
+}
+
+export function sanitizeMcpError(raw: string): string {
+  const scrubbed = raw
+    .replace(/\b([A-Z_][A-Z0-9_]*)=\S+/g, '$1=<redacted>')
+    .replace(/(?:\/[\w.-]+)+/g, '<path>')
+    .replace(/\b[A-Za-z]:\\[^\s]+/g, '<path>')
+  return scrubbed.length <= 500 ? scrubbed : `${scrubbed.slice(0, 497)}...`
+}
+
+function errorMessage(cause: unknown): string {
+  return cause instanceof Error ? cause.message : String(cause)
+}
+
+function readString(value: unknown, key: string): string | undefined {
+  if (typeof value !== 'object' || value === null) return undefined
+  const found = (value as Record<string, unknown>)[key]
+  return typeof found === 'string' ? found : undefined
+}
+
+function readNestedString(value: unknown, key: string, nestedKey: string): string | undefined {
+  if (typeof value !== 'object' || value === null) return undefined
+  return readString((value as Record<string, unknown>)[key], nestedKey)
+}
+
+function textResult(text: string): ToolResult {
+  return { content: [{ type: 'text', text }] }
+}

package/src/permissions/builtins.ts

@@ -16,6 +16,13 @@ export const CORE_PERMISSIONS = {
   // an operator may grant guest channelRespond to let strangers drive masked
   // turns, but session lifecycle control stays member-and-up.
   sessionControl: 'session.control',
+  // Operate-the-agent tier: gates the /reload and /restart channel commands
+  // (both the text-prefix and native-slash paths in the router). Strictly
+  // above sessionControl — reloading config or restarting the container
+  // mutates global agent state and drops every in-flight session, so it is
+  // owner+trusted only (NOT member). A member who can /stop a turn must not
+  // be able to bounce the whole container.
+  sessionAdmin: 'session.admin',
   cronSchedule: 'cron.schedule',
   cronModify: 'cron.modify',
   subagentSpawn: 'subagent.spawn',
@@ -70,6 +77,7 @@ export const BUILTIN_ROLES: Readonly<Record<BuiltinRoleName, BuiltinRoleSpec>> =
     permissions: [
       CORE_PERMISSIONS.channelRespond,
       CORE_PERMISSIONS.sessionControl,
+      CORE_PERMISSIONS.sessionAdmin,
       CORE_PERMISSIONS.cronSchedule,
       CORE_PERMISSIONS.cronModify,
       CORE_PERMISSIONS.subagentSpawn,
@@ -89,6 +97,7 @@ export const BUILTIN_ROLES: Readonly<Record<BuiltinRoleName, BuiltinRoleSpec>> =
     permissions: [
       CORE_PERMISSIONS.channelRespond,
       CORE_PERMISSIONS.sessionControl,
+      CORE_PERMISSIONS.sessionAdmin,
       CORE_PERMISSIONS.cronSchedule,
       CORE_PERMISSIONS.subagentSpawn,
       CORE_PERMISSIONS.subagentCancel,

package/src/reload/format.ts

@@ -0,0 +1,14 @@
+import type { ReloadResult } from './types'
+
+// Human-facing /reload reply for Slack/Discord. Separate from reload-tool.ts's
+// model-facing formatter on purpose — different audience, different shape.
+export function formatChannelReloadSummary(results: readonly ReloadResult[]): string {
+  if (results.length === 0) return 'Nothing to reload.'
+  const failed = results.filter((r) => !r.ok).length
+  const header =
+    failed === 0
+      ? `Reloaded ${results.length} subsystem(s).`
+      : `Reloaded ${results.length} subsystem(s); ${failed} failed.`
+  const lines = results.map((r) => (r.ok ? `• ${r.scope}: ${r.summary}` : `• ${r.scope}: failed — ${r.reason}`))
+  return [header, ...lines].join('\n')
+}

package/src/reload/index.ts

@@ -1,3 +1,4 @@
 export { requestReload, type RequestReloadOptions } from './client'
+export { formatChannelReloadSummary } from './format'
 export { ReloadRegistry } from './registry'
 export type { Reloadable, ReloadAllResult, ReloadResult } from './types'

package/src/run/bundled-plugins.ts

@@ -1,5 +1,6 @@
 import agentBrowserPlugin from '@/bundled-plugins/agent-browser'
 import backupPlugin from '@/bundled-plugins/backup'
+import bunHygienePlugin from '@/bundled-plugins/bun-hygiene'
 import explorerPlugin from '@/bundled-plugins/explorer'
 import githubCliAuthPlugin from '@/bundled-plugins/github-cli-auth'
 import guardPlugin from '@/bundled-plugins/guard'
@@ -29,6 +30,11 @@ import type { ResolvedPlugin } from '@/plugin'
 // Reversing this order would make guard advise on the full oversized payload
 // and then tool-result-cap would clobber the advice text along with the rest.
 //
+// `bun-hygiene` is registered after `guard` and guards a disjoint surface
+// (package-manager bash commands: global installs and non-bun managers), so its
+// position relative to security/guard only matters for precedence — keeping it
+// after the two general guards means a security/guard block always wins first.
+//
 // `github-cli-auth` is registered AFTER `security` so security's `tool.before`
 // runs its exfil/secret scanners on the bash command first. github-cli-auth
 // injects the minted token via an env overlay (TYPECLAW_INTERNAL_BASH_ENV), not
@@ -45,6 +51,7 @@ export const BUNDLED_PLUGINS: ResolvedPlugin[] = [
   { name: 'security', version: undefined, source: '<bundled>', defined: securityPlugin },
   { name: 'tool-result-cap', version: undefined, source: '<bundled>', defined: toolResultCapPlugin },
   { name: 'guard', version: undefined, source: '<bundled>', defined: guardPlugin },
+  { name: 'bun-hygiene', version: undefined, source: '<bundled>', defined: bunHygienePlugin },
   { name: 'github-cli-auth', version: undefined, source: '<bundled>', defined: githubCliAuthPlugin },
   { name: 'memory', version: undefined, source: '<bundled>', defined: memoryPlugin },
   { name: 'backup', version: undefined, source: '<bundled>', defined: backupPlugin },

package/src/run/channel-session-factory.ts

@@ -7,6 +7,7 @@ import type { CreateSessionForSubagent, SubagentRegistry } from '@/agent/subagen
 import { capJsonlFileInPlace } from '@/bundled-plugins/tool-result-cap/cap-jsonl'
 import type { CapOptions } from '@/bundled-plugins/tool-result-cap/cap-result'
 import type { CreateSessionForChannel, ChannelRouter } from '@/channels'
+import type { McpManager } from '@/mcp'
 import type { PermissionService, RolesConfig } from '@/permissions'
 import type { ReloadRegistry } from '@/reload'
 import type { SessionFactory } from '@/sessions'
@@ -35,6 +36,7 @@ export type BuildChannelSessionFactoryDeps = {
   // cycle while still ensuring the factory's sessions get the same router
   // their inbound messages came from.
   getChannelRouter: () => ChannelRouter
+  mcpManager?: McpManager
   containerName?: string
   runtimeVersion?: string
   // When set, rehydrating a session JSONL caps oversized tool results in the
@@ -113,6 +115,7 @@ export function buildChannelSessionFactory(deps: BuildChannelSessionFactoryDeps)
       sessionManager,
       stream: deps.stream,
       channelRouter: deps.getChannelRouter(),
+      ...(deps.mcpManager !== undefined ? { mcpManager: deps.mcpManager } : {}),
       origin,
       originRef,
       ...(snap.hasAnyPluginContent

package/src/run/index.ts

@@ -3,6 +3,7 @@ import { SessionManager } from '@mariozechner/pi-coding-agent'
 import { createSession, createSessionWithDispose } from '@/agent'
 import { LiveSessionRegistry } from '@/agent/live-sessions'
 import { LiveSubagentRegistry } from '@/agent/live-subagents'
+import { requestContainerRestart } from '@/agent/restart'
 import type { SessionOrigin } from '@/agent/session-origin'
 import {
   awaitWithSubagentTimeout,
@@ -38,11 +39,12 @@ import {
   type Scheduler,
 } from '@/cron'
 import { CLI_VERSION } from '@/init/cli-version'
+import { createMcpManager } from '@/mcp'
 import { loadPlugins, type LoadPluginsResult, pluginCronJobs, type PluginRegistry, summarizeLoaded } from '@/plugin'
 import { createPluginLogger } from '@/plugin/context'
 import type { CronHandlerContext } from '@/plugin/types'
 import { createContainerBroker, publishForwardResult } from '@/portbroker'
-import { ReloadRegistry } from '@/reload'
+import { formatChannelReloadSummary, ReloadRegistry } from '@/reload'
 import { createClaimController } from '@/role-claim'
 import {
   exportClaudeCredentialsFileForAgent,
@@ -140,6 +142,15 @@ export async function startAgent({
   const pluginConfigsByName = loadPluginConfigsSync(cwd)
   const cwdConfig = loadConfigSync(cwd)
   const githubTokenBridge = createGithubTokenBridge()
+  const mcpManager =
+    cwdConfig.mcpServers.length > 0 ? createMcpManager(cwdConfig.mcpServers, { env: process.env }) : null
+  if (mcpManager !== null) {
+    const results = await mcpManager.connectAll()
+    for (const result of results) {
+      if (!result.ok) console.warn(`[mcp] ${result.name} failed to connect: ${result.error.message}`)
+    }
+  }
+  const mcpManagerOpt = mcpManager !== null ? { mcpManager } : {}
   const pluginsLoaded = await loadPlugins({
     entries: cwdConfig.plugins,
     agentDir: cwd,
@@ -255,11 +266,32 @@ export async function startAgent({
       getCreateSessionForSubagent: () => createSessionForSubagent,
       ...containerNameOpt,
       ...runtimeVersionOpt,
+      ...mcpManagerOpt,
     }),
     permissions: pluginsLoaded.permissions,
     claimHandler: claimController.claimHandler,
     githubTokenBridge,
     stream,
+    onReload: async () => {
+      const { results } = await reloadRegistry.reloadAll()
+      return formatChannelReloadSummary(results)
+    },
+    // Always registered so /restart's presence in /help, the Slack manifest,
+    // and the Discord declarations is environment-independent. When there is no
+    // container to bounce (TYPECLAW_CONTAINER_NAME unset — tests, ad-hoc
+    // `typeclaw run` outside Docker), the handler reports that instead of the
+    // command resolving as unknown, which would make the advertised contract
+    // depend on the runtime environment.
+    onRestart: async (): Promise<string> => {
+      if (containerName === undefined) {
+        return 'Restart is unavailable: this agent is not running inside a typeclaw container.'
+      }
+      // No originatingSessionId/stream/handoff: a channel-invoked restart must
+      // not write a resume hint or fire the "I'm back" broadcast that a TUI
+      // restart does (issue #291 scoping — only TUI origins resume).
+      const result = await requestContainerRestart({ containerName })
+      return result.ok ? 'Restart scheduled; the container will bounce shortly.' : `Restart denied: ${result.reason}`
+    },
   })
 
   const createSessionForSubagent: import('@/agent/subagents').CreateSessionForSubagent = async (
@@ -376,6 +408,7 @@ export async function startAgent({
             containerName: containerNameOpt.containerName,
             sessionFactory,
             channelRouter: channelManager.router,
+            ...mcpManagerOpt,
           }),
         subagent: (subName: string, payload?: unknown) =>
           dispatchSpawnSubagent(subName, payload, {
@@ -424,6 +457,7 @@ export async function startAgent({
         createSessionForSubagent,
         ...containerNameOpt,
         ...runtimeVersionOpt,
+        ...mcpManagerOpt,
       })
       liveSessionRegistry.register({ sessionId, session })
       return {
@@ -591,6 +625,7 @@ export async function startAgent({
       outbound,
       sessionFactory,
       channelRouter: channelManager.router,
+      ...mcpManagerOpt,
     })
 
   const server = createServer({
@@ -600,6 +635,7 @@ export async function startAgent({
     sessionFactory,
     stream,
     channelRouter: channelManager.router,
+    ...mcpManagerOpt,
     agentDir: cwd,
     pluginRuntime,
     claimController,
@@ -634,6 +670,7 @@ export async function startAgent({
     subagentCompletionBridge.stop()
     await tunnelManager.stop()
     await channelManager.stop()
+    await mcpManager?.closeAll()
     uninstallCodexFetchObserver()
   }
 

package/src/server/command-runner.ts

@@ -6,6 +6,7 @@ import {
   type SessionOrigin,
 } from '@/agent'
 import type { ChannelRouter } from '@/channels/router'
+import type { McpManager } from '@/mcp'
 import type { PermissionService } from '@/permissions'
 import type {
   CommandExecResult,
@@ -53,6 +54,7 @@ export type CommandRunnerOptions = {
   // `channelManager.router` via `createSessionForCron`; this is the matching
   // wire for the handler/command path.
   channelRouter: ChannelRouter | undefined
+  mcpManager?: McpManager
 }
 
 type CommandHandle = {
@@ -192,6 +194,7 @@ export function createCommandRunner(opts: CommandRunnerOptions): CommandRunner {
               signal: abortController.signal,
               sessionFactory: opts.sessionFactory,
               channelRouter: opts.channelRouter,
+              ...(opts.mcpManager !== undefined ? { mcpManager: opts.mcpManager } : {}),
             }),
           subagent: (subName, payload) =>
             opts.spawnSubagent(subName, payload, {
@@ -376,6 +379,7 @@ export async function runPromptForCommand(args: {
   // See CommandRunnerOptions.channelRouter. Threaded to createSessionWithDispose
   // so the spawned session exposes `channel_send`.
   channelRouter?: ChannelRouter
+  mcpManager?: McpManager
   // Test seam for the agent-session boundary. Production passes the real
   // `createSessionWithDispose`; tests inject a fake to verify wiring
   // (specifically: the sessionManager handed off must be persisted, not
@@ -402,6 +406,7 @@ export async function runPromptForCommand(args: {
       agentDir: args.agentDir,
     },
     ...(args.channelRouter !== undefined ? { channelRouter: args.channelRouter } : {}),
+    ...(args.mcpManager !== undefined ? { mcpManager: args.mcpManager } : {}),
     ...(args.runtimeVersion !== undefined ? { runtimeVersion: args.runtimeVersion } : {}),
     ...(args.containerName !== undefined ? { containerName: args.containerName } : {}),
   })

package/src/server/index.ts

@@ -19,6 +19,7 @@ import { parseSubagentCompletedPayload, renderSubagentCompletionReminder } from
 import type { CreateSessionForSubagent } from '@/agent/subagents'
 import type { ChannelRouter } from '@/channels/router'
 import { aggregateCronList, type CronListEntry, loadCron } from '@/cron'
+import type { McpManager } from '@/mcp'
 import type { HookBus } from '@/plugin'
 import type { BrokerWsData, ContainerBroker } from '@/portbroker'
 import type { ReloadAllResult, ReloadRegistry } from '@/reload'
@@ -61,6 +62,7 @@ export type ServerOptions = {
   sessionFactory?: SessionFactory
   stream?: Stream
   channelRouter?: ChannelRouter
+  mcpManager?: McpManager
   agentDir?: string
   pluginRuntime?: PluginRuntime
   containerName?: string
@@ -221,6 +223,7 @@ export function createServer({
   sessionFactory,
   stream,
   channelRouter,
+  mcpManager,
   agentDir,
   pluginRuntime,
   containerName,
@@ -471,6 +474,7 @@ export function createServer({
               origin,
               ...(stream ? { stream } : {}),
               ...(channelRouter ? { channelRouter } : {}),
+              ...(mcpManager ? { mcpManager } : {}),
               ...(pluginsWiring ? { plugins: pluginsWiring } : {}),
               ...(containerName !== undefined ? { containerName } : {}),
               ...(runtimeVersion !== undefined ? { runtimeVersion } : {}),