Session-level setMcpConfig for per-session MCP server configuration

[marcus-sa]

Problem

setMcpConfig is only available on the SandboxAgent (SDK) class, not on individual Session instances. The SDK method keys configs by (directory, mcpName), which means all sessions sharing the same cwd get the same MCP config.

This breaks the use case where each session needs its own MCP server credentials (e.g., a unique auth token per session).

Current behavior

// SDK-level — shared across all sessions with same cwd
await sdk.setMcpConfig(
  { directory: "/workspace", mcpName: "brain" },
  { type: "remote", url: "https://brain.example.com/mcp/agent/session-1", headers: { "X-Auth": "token-for-session-1" } },
);

// This overwrites the config for ALL sessions in /workspace
await sdk.setMcpConfig(
  { directory: "/workspace", mcpName: "brain" },
  { type: "remote", url: "https://brain.example.com/mcp/agent/session-2", headers: { "X-Auth": "token-for-session-2" } },
);

Expected behavior

const session1 = await sdk.createSession({ agent: "claude", cwd: "/workspace" });
const session2 = await sdk.createSession({ agent: "claude", cwd: "/workspace" });

// Per-session MCP config — each session gets its own credentials
await session1.setMcpConfig(
  { directory: "/workspace", mcpName: "brain" },
  { type: "remote", url: "https://brain.example.com/mcp/agent/session-1", headers: { "X-Auth": "token-for-session-1" } },
);

await session2.setMcpConfig(
  { directory: "/workspace", mcpName: "brain" },
  { type: "remote", url: "https://brain.example.com/mcp/agent/session-2", headers: { "X-Auth": "token-for-session-2" } },
);

Use case

We're building a governance layer (Brain) that provides each sandbox agent session with a dynamic MCP endpoint scoped to that session's authorization context. Each session gets a unique proxy token and endpoint URL. Without session-level setMcpConfig, we can't run concurrent sessions with different MCP credentials.

Workaround

Currently using unique cwd paths per session to avoid config collisions, but this is fragile and doesn't work when sessions genuinely need the same working directory.

Type reference

The Session class (in index.d.ts) currently has these config methods but NOT setMcpConfig:

declare class Session {
  setConfigOption(configId: string, value: string): Promise<SetSessionConfigOptionResponse>;
  setModel(model: string): Promise<SetSessionConfigOptionResponse>;
  setThoughtLevel(thoughtLevel: string): Promise<SetSessionConfigOptionResponse>;
  getConfigOptions(): Promise<SessionConfigOption[]>;
  // Missing: getMcpConfig, setMcpConfig, deleteMcpConfig
}

While SandboxAgent has them:

declare class SandboxAgent {
  getMcpConfig(query: McpConfigQuery): Promise<McpServerConfig>;
  setMcpConfig(query: McpConfigQuery, config: McpServerConfig): Promise<void>;
  deleteMcpConfig(query: McpConfigQuery): Promise<void>;
}

[linear]

RVT-6125