feat: add managed MCP session support

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: mattdholloway

docs/features/mcp.md

@@ -15,15 +15,86 @@ The Copilot SDK can integrate with **MCP servers** (Model Context Protocol) to e
 * Call external APIs
 * And much more
 
-## Server types
+## Server transports
 
-The SDK supports two types of MCP servers:
+The SDK supports two MCP transport families:
 
 | Type | Description | Use Case |
 |------|-------------|----------|
 | **Local/Stdio** | Runs as a subprocess, communicates via stdin/stdout | Local tools, file access, custom scripts |
 | **HTTP/SSE** | Remote server accessed via HTTP | Shared services, cloud-hosted tools |
 
+Transport and configuration origin are separate concepts. A managed MCP server
+uses the HTTP transport, but its configuration comes from a trusted host catalog
+instead of user or workspace configuration. Session status and loaded-server
+events report this distinction with `source: "managed"` and include the catalog
+display name.
+
+## Managed MCP servers
+
+Managed MCP lets a trusted SDK host inject a catalog of non-secret hosted
+servers for one session. The runtime keeps this catalog separate from
+`mcpServers`, so existing local stdio, HTTP, SSE, and OAuth behavior remains
+unchanged.
+
+The host supplies each server under a stable managed identity:
+
+<!-- docs-validate: skip -->
+
+```typescript
+const session = await client.createSession({
+    managedMcpServers: {
+        "github-enterprise": {
+            displayName: "GitHub Enterprise",
+            url: "https://mcp.example.com/",
+            tools: ["issues", "pull_requests"],
+            timeout: 30_000,
+            headersRefreshTtlMs: 60_000,
+        },
+    },
+    onMcpHeadersRefresh: async ({ serverName, serverUrl, reason }) => {
+        const credential = await broker.getCredential({ serverName, serverUrl, reason });
+        return {
+            headers: { Authorization: credential.authorizationHeader },
+            ttlMs: credential.expiresInMs,
+        };
+    },
+});
+```
+
+The corresponding configuration and callback names are:
+
+| SDK | Managed servers | Header refresh callback |
+| --- | --- | --- |
+| Node.js | `managedMcpServers` | `onMcpHeadersRefresh` |
+| Python | `managed_mcp_servers` | `on_mcp_headers_refresh` |
+| Go | `ManagedMCPServers` | `OnMCPHeadersRefresh` |
+| .NET | `ManagedMcpServers` | `OnMcpHeadersRefresh` |
+| Java | `setManagedMcpServers(...)` | `setOnMcpHeadersRefreshRequest(...)` |
+| Rust | `with_managed_mcp_servers(...)` | `with_mcp_headers_handler(...)` |
+
+### Host responsibilities
+
+Managed MCP hosts must enforce these boundaries:
+
+* **Trusted catalog injection**: Only inject server identities, display metadata,
+  endpoints, and tool policy from a trusted catalog. Do not treat model output
+  or untrusted content as catalog configuration.
+* **Memory-only credentials**: Keep access tokens and derived authorization
+  headers in memory. Do not place credentials in `managedMcpServers`, session
+  history, workspace state, or persistent MCP OAuth storage.
+* **Expiry and revocation**: Set `ttlMs` to the remaining credential lifetime.
+  The runtime clamps it to `headersRefreshTtlMs`. Throw from the callback when
+  the broker denies access, fails, or reports revocation; the SDK forwards an
+  explicit broker error without converting it to a successful empty response.
+* **Cold resume**: Re-supply both the managed catalog and the header refresh
+  callback when cold-resuming a session. Managed configuration and credentials
+  are not recovered from persisted session state.
+
+Returning no result from the callback reports that no dynamic headers are
+available. Existing static `headers`, arbitrary HTTP servers, and MCP OAuth
+handlers continue to use their current behavior.
+
 ## Configuration
 
 ### Node.js / TypeScript

dotnet/src/Client.cs

@@ -825,6 +825,7 @@ private CopilotSession InitializeSession(
             config.OnPermissionRequest,
             config.EnableManaged设置 is true || config.Managed设置 is not null);
         session.RegisterMcpAuthHandler(config.OnMcpAuthRequest);
+        session.RegisterMcpHeadersRefreshHandler(config.OnMcpHeadersRefresh);
         session.RegisterCommands(config.Commands);
         session.RegisterElicitationHandler(config.OnElicitationRequest);
         session.RegisterExitPlanModeHandler(config.OnExitPlanModeRequest);
@@ -1206,6 +1207,7 @@ public async Task<CopilotSession> CreateSessionAsync(SessionConfig config, Cance
                 config.Streaming is true ? true : null,
                 config.IncludeSubAgentStreamingEvents,
                 config.McpServers,
+                config.ManagedMcpServers,
                 config.McpOAuthTokenStorage,
                 "direct",
                 config.CustomAgents,
@@ -1307,6 +1309,10 @@ public async Task<CopilotSession> CreateSessionAsync(SessionConfig config, Cance
             {
                 await session.Rpc.EventLog.RegisterInterestAsync("mcp.oauth_required", cancellationToken);
             }
+            if (config.OnMcpHeadersRefresh is not null)
+            {
+                await session.Rpc.EventLog.RegisterInterestAsync("mcp.headers_refresh_required", cancellationToken);
+            }
 
             session.WorkspacePath = response.WorkspacePath;
             session.SetCapabilities(response.Capabilities);
@@ -1456,6 +1462,7 @@ public async Task<CopilotSession> ResumeSessionAsync(string sessionId, ResumeSes
                 config.Streaming is true ? true : null,
                 config.IncludeSubAgentStreamingEvents,
                 config.McpServers,
+                config.ManagedMcpServers,
                 config.McpOAuthTokenStorage,
                 "direct",
                 config.CustomAgents,
@@ -1514,6 +1521,10 @@ public async Task<CopilotSession> ResumeSessionAsync(string sessionId, ResumeSes
             {
                 await session.Rpc.EventLog.RegisterInterestAsync("mcp.oauth_required", cancellationToken);
             }
+            if (config.OnMcpHeadersRefresh is not null)
+            {
+                await session.Rpc.EventLog.RegisterInterestAsync("mcp.headers_refresh_required", cancellationToken);
+            }
 
             await UpdateSessionOptionsForModeAsync(session, config, cancellationToken).ConfigureAwait(false);
             if (registrationId is not null)
@@ -2884,6 +2895,7 @@ internal record CreateSessionRequest(
         bool? Streaming,
         bool? IncludeSubAgentStreamingEvents,
         IDictionary<string, McpServerConfig>? McpServers,
+        [property: JsonPropertyName("managedMcpServers")] IDictionary<string, ManagedMcpServerConfig>? ManagedMcpServers,
         McpOAuthTokenStorageMode? McpOAuthTokenStorage,
         string? EnvValueMode,
         IList<CustomAgentConfig>? CustomAgents,
@@ -3011,6 +3023,7 @@ internal record ResumeSessionRequest(
         bool? Streaming,
         bool? IncludeSubAgentStreamingEvents,
         IDictionary<string, McpServerConfig>? McpServers,
+        [property: JsonPropertyName("managedMcpServers")] IDictionary<string, ManagedMcpServerConfig>? ManagedMcpServers,
         McpOAuthTokenStorageMode? McpOAuthTokenStorage,
         string? EnvValueMode,
         IList<CustomAgentConfig>? CustomAgents,

dotnet/src/Generated/Rpc.cs

@@ -65,6 +65,7 @@ public sealed partial class CopilotSession : IAsyncDisposable
     private volatile Func<PermissionRequest, PermissionInvocation, Task<PermissionDecision>>? _permissionHandler;
     private bool _managed设置Enabled;
     private volatile Func<McpAuthContext, Task<McpAuthResult?>>? _mcpAuthHandler;
+    private volatile Func<McpHeadersRefreshContext, Task<McpHeadersRefreshResult?>>? _mcpHeadersRefreshHandler;
     private volatile Func<UserInputRequest, UserInputInvocation, Task<UserInputResponse>>? _userInputHandler;
     private volatile Func<ElicitationContext, Task<ElicitationResult>>? _elicitationHandler;
     private volatile Func<ExitPlanModeRequest, ExitPlanModeInvocation, Task<ExitPlanModeResult>>? _exitPlanModeHandler;
@@ -590,6 +591,11 @@ internal void RegisterMcpAuthHandler(Func<McpAuthContext, Task<McpAuthResult?>>?
         _mcpAuthHandler = handler;
     }
 
+    internal void RegisterMcpHeadersRefreshHandler(Func<McpHeadersRefreshContext, Task<McpHeadersRefreshResult?>>? handler)
+    {
+        _mcpHeadersRefreshHandler = handler;
+    }
+
     /// <summary>
     /// Handles a permission request from the Copilot CLI.
     /// </summary>
@@ -699,6 +705,26 @@ private async Task HandleBroadcastEventAsync(SessionEvent sessionEvent)
                         break;
                     }
 
+                case McpHeadersRefreshRequiredEvent refreshEvent:
+                    {
+                        var data = refreshEvent.Data;
+                        var handler = _mcpHeadersRefreshHandler;
+                        if (string.IsNullOrEmpty(data.RequestId) || handler is null)
+                            return;
+
+                        await ExecuteMcpHeadersRefreshAndRespondAsync(
+                            data.RequestId,
+                            new McpHeadersRefreshContext
+                            {
+                                SessionId = SessionId,
+                                ServerName = data.ServerName,
+                                ServerUrl = data.ServerUrl,
+                                Reason = data.Reason
+                            },
+                            handler);
+                        break;
+                    }
+
                 case CommandExecuteEvent cmdEvent:
                     {
                         var data = cmdEvent.Data;
@@ -826,6 +852,56 @@ private async Task ExecuteMcpAuthAndRespondAsync(
         }
     }
 
+    private async Task ExecuteMcpHeadersRefreshAndRespondAsync(
+        string requestId,
+        McpHeadersRefreshContext context,
+        Func<McpHeadersRefreshContext, Task<McpHeadersRefreshResult?>> handler)
+    {
+        McpHeadersHandlePendingHeadersRefreshRequest response;
+        try
+        {
+            var result = await handler(context);
+            response = result is null
+                ? new McpHeadersHandlePendingHeadersRefreshRequestNone()
+                : new McpHeadersHandlePendingHeadersRefreshRequestHeaders
+                {
+                    Headers = result.Headers,
+                    TtlMs = result.TtlMs
+                };
+        }
+        catch (OperationCanceledException ex)
+        {
+            response = new McpHeadersHandlePendingHeadersRefreshRequestError
+            {
+                Message = ex.Message
+            };
+        }
+        catch (Exception ex) when (IsRecoverableMcpAuthFailure(ex))
+        {
+            response = new McpHeadersHandlePendingHeadersRefreshRequestError
+            {
+                Message = ex.Message
+            };
+        }
+
+        try
+        {
+            await Rpc.Mcp.Headers.HandlePendingHeadersRefreshRequestAsync(requestId, response);
+        }
+        catch (IOException)
+        {
+            // Connection lost — nothing we can do.
+        }
+        catch (ObjectDisposedException)
+        {
+            // Connection already disposed — nothing we can do.
+        }
+        catch (RemoteRpcException)
+        {
+            // The pending request may already be gone — nothing we can do.
+        }
+    }
+
     private static bool IsRecoverableMcpAuthFailure(Exception exception)
         => exception is not OperationCanceledException
             and not OutOfMemoryException