fix(agents): make injected MCP launch requirements explicit

Optional injected servers must survive persistence and reload without turning missing transport support into launch refusal. Required external and plugin servers keep their existing refusal. Advertise the optional MCP contract so older hosts retain established strict launch behavior.

packages/protocol/src/agent-types.ts

@@ -515,6 +515,8 @@ export interface ToolPolicy {
 }
 
 export interface AgentSessionConfig {
+  /** Per-server launch requirement; unspecified servers are required. */
+  mcpServerRequirements?: Record<string, "optional" | "required">;
   provider: AgentProvider;
   cwd: string;
   /**

packages/protocol/src/messages.ts

@@ -494,6 +494,7 @@ const AgentSessionConfigSchema = z.object({
     enforcement: z.enum(["required", "if-supported"]).optional(),
   }).optional(),
   systemPrompt: z.string().optional(),
+  mcpServerRequirements: z.record(z.string(), z.enum(["optional", "required"])).optional(),
   mcpServers: z.record(z.string(), McpServerConfigSchema).optional(),
 });
 
@@ -3673,6 +3674,7 @@ export const ServerInfoStatusPayloadSchema = z
         internalWorkspaces: z.boolean().optional(),
         backgroundWorkspaces: z.boolean().optional(),
         providersSnapshot: z.boolean().optional(),
+        optionalMcpSupport: z.boolean().optional(),
         connectedHosts: z.boolean().optional(),
         hostMultiplexing: z.boolean().optional(),
         usageSources: z.boolean().optional(),

packages/server/src/server/agent/agent-manager.test.ts

@@ -3822,60 +3822,71 @@ test("resumeAgentFromPersistence drops stored internal paseo MCP when runtime in
   expect(snapshot.config.mcpServers).toBeUndefined();
 });
 
-test("createAgent preserves injected MCP when optional approval is unavailable", async () => {
-  const workdir = mkdtempSync(join(tmpdir(), "agent-manager-test-"));
-  const storagePath = join(workdir, "agents");
-  const storage = new AgentStorage(storagePath, logger);
+test.each([true, false])(
+  "createAgent permits optional approval with MCP capability %s",
+  async (supportsMcp) => {
+    const workdir = mkdtempSync(join(tmpdir(), "agent-manager-test-"));
+    const storagePath = join(workdir, "agents");
+    const storage = new AgentStorage(storagePath, logger);
 
-  class CaptureClient extends TestAgentClient {
-    lastConfig: AgentSessionConfig | null = null;
+    class CaptureClient extends TestAgentClient {
+      lastConfig: AgentSessionConfig | null = null;
 
-    override async createSession(config: AgentSessionConfig): Promise<AgentSession> {
-      this.lastConfig = config;
-      return new McpCapableTestAgentSession(config);
+      override async createSession(config: AgentSessionConfig): Promise<AgentSession> {
+        this.lastConfig = config;
+        return supportsMcp ? new McpCapableTestAgentSession(config) : new TestAgentSession(config);
+      }
     }
-  }
 
-  const client = new CaptureClient();
-  const manager = new AgentManager({
-    clients: {
-      codex: client,
-    },
-    registry: storage,
-    logger,
-    mcpBaseUrl: "http://127.0.0.1:6767/mcp/agents",
-    idFactory: () => "00000000-0000-4000-8000-000000000104",
-  });
-
-  const snapshot = await manager.createAgent(
-    {
-      provider: "codex",
-      cwd: workdir,
-      toolPolicy: {
-        enforcement: "if-supported",
-        preapproved: [{ kind: "mcp", server: "paseo", tool: "finish_execution" }],
+    const client = new CaptureClient();
+    const manager = new AgentManager({
+      clients: {
+        codex: client,
       },
-      mcpServers: {
-        paseo: {
-          type: "http",
-          url: "https://example.com/custom-paseo",
+      registry: storage,
+      logger,
+      mcpBaseUrl: "http://127.0.0.1:6767/mcp/agents",
+      idFactory: () => "00000000-0000-4000-8000-000000000104",
+    });
+
+    const snapshot = await manager.createAgent(
+      {
+        provider: "codex",
+        mcpServerRequirements: { paseo: "optional" },
+        cwd: workdir,
+        toolPolicy: {
+          enforcement: "if-supported",
+          preapproved: [{ kind: "mcp", server: "paseo", tool: "finish_execution" }],
+        },
+        mcpServers: {
+          paseo: {
+            type: "http",
+            url: "https://example.com/custom-paseo",
+          },
         },
       },
-    },
-    undefined,
-    { workspaceId: undefined },
-  );
+      undefined,
+      { workspaceId: undefined },
+    );
 
-  expect(snapshot.config.mcpServers).toEqual({
-    paseo: {
-      type: "http",
-      url: "https://example.com/custom-paseo",
-    },
-  });
-  expect(snapshot.config.toolPolicy).toBeUndefined();
-  expect(client.lastConfig?.toolPolicy).toBeUndefined();
-  expect(client.lastConfig?.mcpServers).toEqual(snapshot.config.mcpServers);
-});
+    expect(snapshot.config.mcpServers).toEqual({
+      paseo: {
+        type: "http",
+        url: "https://example.com/custom-paseo",
+      },
+    });
+    expect((await storage.get(snapshot.id))?.config?.mcpServerRequirements).toEqual({
+      paseo: "optional",
+    });
+    await manager.reloadAgentSession(snapshot.id);
+    expect(manager.getAgent(snapshot.id)?.config.mcpServerRequirements).toEqual({
+      paseo: "optional",
+    });
+    expect(snapshot.config.toolPolicy).toBeUndefined();
+    expect(client.lastConfig?.toolPolicy).toBeUndefined();
+    expect(client.lastConfig?.mcpServers).toEqual(snapshot.config.mcpServers);
+  },
+);
 
 test("createAgent fails when cwd does not exist", async () => {
   const workdir = mkdtempSync(join(tmpdir(), "agent-manager-test-"));

packages/server/src/server/agent/agent-manager.ts

@@ -216,6 +216,8 @@ function buildStoredAgentConfig(record: StoredAgentRecord): AgentSessionConfig {
   if (record.config.providerOptions != null) {
     config.providerOptions = record.config.providerOptions;
   }
+  if (record.config.mcpServerRequirements != null)
+    config.mcpServerRequirements = record.config.mcpServerRequirements;
   if (record.config.toolPolicy != null) config.toolPolicy = record.config.toolPolicy;
   if (record.config.systemPrompt != null) {
     config.systemPrompt = record.config.systemPrompt;
@@ -1686,7 +1688,7 @@ export class AgentManager {
     );
     const providerLaunchConfig = this.resolveProviderLaunchConfig(launchConfig, launchContext);
     if (
-      Object.keys(stripInternalPaseoMcpServer(providerLaunchConfig).mcpServers ?? {}).length > 0 &&
+      this.hasRequiredExternalMcpServers(providerLaunchConfig) &&
       existing.session.capabilities.supportsMcpServers !== true
     ) {
       throw this.unsupportedMcpError(providerLaunchConfig, launchContext);
@@ -3888,13 +3890,19 @@ export class AgentManager {
     }
   }
 
+  private hasRequiredExternalMcpServers(config: AgentSessionConfig): boolean {
+    return Object.keys(stripInternalPaseoMcpServer(config).mcpServers ?? {}).some(
+      (name) => config.mcpServerRequirements?.[name] !== "optional",
+    );
+  }
+
   private async requireExternalMcpSupport(
     session: AgentSession,
     launchConfig: AgentSessionConfig,
     launchContext: AgentLaunchContext,
   ): Promise<void> {
     if (
-      Object.keys(stripInternalPaseoMcpServer(launchConfig).mcpServers ?? {}).length === 0 ||
+      !this.hasRequiredExternalMcpServers(launchConfig) ||
       session.capabilities.supportsMcpServers === true
     ) {
       return;

packages/server/src/server/agent/agent-projections.ts

@@ -395,6 +395,9 @@ function buildSerializableConfig(config: AgentSessionConfig): SerializableAgentC
   if (config.systemPrompt) {
     serializable.systemPrompt = config.systemPrompt;
   }
+  if (config.mcpServerRequirements) {
+    serializable.mcpServerRequirements = config.mcpServerRequirements;
+  }
   if (config.mcpServers) {
     serializable.mcpServers = config.mcpServers;
   }

packages/server/src/server/agent/agent-sdk-types.ts

@@ -607,6 +607,7 @@ export interface AgentSessionConfig {
   title?: string | null;
   providerOptions?: ProviderOptions;
   toolPolicy?: ToolPolicy;
+  mcpServerRequirements?: Record<string, "optional" | "required">;
   mcpServers?: Record<string, McpServerConfig>;
   /**
    * Internal agents are hidden from listings and don't trigger notifications.

packages/server/src/server/agent/agent-storage.ts

@@ -27,6 +27,10 @@ const SERIALIZABLE_CONFIG_SCHEMA = z
       .nullable()
       .optional(),
     systemPrompt: z.string().nullable().optional(),
+    mcpServerRequirements: z
+      .record(z.string(), z.enum(["optional", "required"]))
+      .nullable()
+      .optional(),
     mcpServers: z.record(z.string(), z.any()).nullable().optional(),
   })
   .nullable()
@@ -89,6 +93,7 @@ export type SerializableAgentConfig = Pick<
   | "toolPolicy"
   | "systemPrompt"
   | "mcpServers"
+  | "mcpServerRequirements"
 >;
 
 export type StoredAgentRecord = z.infer<typeof STORED_AGENT_SCHEMA>;

packages/server/src/server/websocket-server.ts

@@ -1966,6 +1966,7 @@ export class VoiceAssistantWebSocketServer {
         workspaceSortTimes: true,
         // COMPAT(providersSnapshot): keep optional until all clients rely on snapshot flow.
         providersSnapshot: true,
+        optionalMcpSupport: true,
         // COMPAT(providersSnapshotCwd): added in v0.3.2, remove gate after 2027-02-10.
         providersSnapshotCwd: true,
         // COMPAT(checkoutForgeSetAutoMerge): added in v0.2.0-beta.1. Remove the