feat(core): add support for admin-forced MCP server installations (#23163)

Author: gsquared94

docs/admin/enterprise-controls.md

@@ -106,6 +106,67 @@ organization.
   ensures users maintain final control over which permitted servers are actually
   active in their environment.
 
+#### Required MCP Servers (preview)
+
+**Default**: empty
+
+Allows administrators to define MCP servers that are **always injected** into
+the user's environment. Unlike the allowlist (which filters user-configured
+servers), required servers are automatically added regardless of the user's
+local configuration.
+
+**Required Servers Format:**
+
+```json
+{
+  "requiredMcpServers": {
+    "corp-compliance-tool": {
+      "url": "https://mcp.corp/compliance",
+      "type": "http",
+      "trust": true,
+      "description": "Corporate compliance tool"
+    },
+    "internal-registry": {
+      "url": "https://registry.corp/mcp",
+      "type": "sse",
+      "authProviderType": "google_credentials",
+      "oauth": {
+        "scopes": ["https://www.googleapis.com/auth/scope"]
+      }
+    }
+  }
+}
+```
+
+**Supported Fields:**
+
+- `url`: (Required) The full URL of the MCP server endpoint.
+- `type`: (Required) The connection type (`sse` or `http`).
+- `trust`: (Optional) If set to `true`, tool execution will not require user
+  approval. Defaults to `true` for required servers.
+- `description`: (Optional) Human-readable description of the server.
+- `authProviderType`: (Optional) Authentication provider (`dynamic_discovery`,
+  `google_credentials`, or `service_account_impersonation`).
+- `oauth`: (Optional) OAuth configuration including `scopes`, `clientId`, and
+  `clientSecret`.
+- `targetAudience`: (Optional) OAuth target audience for service-to-service
+  auth.
+- `targetServiceAccount`: (Optional) Service account email to impersonate.
+- `headers`: (Optional) Additional HTTP headers to send with requests.
+- `includeTools` / `excludeTools`: (Optional) Tool filtering lists.
+- `timeout`: (Optional) Timeout in milliseconds for MCP requests.
+
+**Client Enforcement Logic:**
+
+- Required servers are injected **after** allowlist filtering, so they are
+  always available even if the allowlist is active.
+- If a required server has the **same name** as a locally configured server, the
+  admin configuration **completely overrides** the local one.
+- Required servers only support remote transports (`sse`, `http`). Local
+  execution fields (`command`, `args`, `env`, `cwd`) are not supported.
+- Required servers can coexist with allowlisted servers — both features work
+  independently.
+
 ### Unmanaged Capabilities
 
 **Enabled/Disabled** | Default: disabled

docs/reference/configuration.md

@@ -1728,7 +1728,11 @@ their corresponding top-level category object in your `settings.json` file.
   - **Default:** `true`
 
 - **`admin.mcp.config`** (object):
-  - **Description:** Admin-configured MCP servers.
+  - **Description:** Admin-configured MCP servers (allowlist).
+  - **Default:** `{}`
+
+- **`admin.mcp.requiredConfig`** (object):
+  - **Description:** Admin-required MCP servers that are always injected.
   - **Default:** `{}`
 
 - **`admin.skills.enabled`** (boolean):

packages/cli/src/commands/mcp/list.test.ts

@@ -264,6 +264,7 @@ describe('mcp list command', () => {
         config: {
           'allowed-server': { url: 'http://allowed' },
         },
+        requiredConfig: {},
       },
     };
 

packages/cli/src/config/config.ts

@@ -36,6 +36,7 @@ import {
   Config,
   resolveToRealPath,
   applyAdminAllowlist,
+  applyRequiredServers,
   getAdminBlockedMcpServersMessage,
   type HookDefinition,
   type HookEventName,
@@ -750,6 +751,25 @@ export async function loadCliConfig(
     }
   }
 
+  // Apply admin-required MCP servers (injected regardless of allowlist)
+  if (mcpEnabled) {
+    const requiredMcpConfig = settings.admin?.mcp?.requiredConfig;
+    if (requiredMcpConfig && Object.keys(requiredMcpConfig).length > 0) {
+      const requiredResult = applyRequiredServers(
+        mcpServers ?? {},
+        requiredMcpConfig,
+      );
+      mcpServers = requiredResult.mcpServers;
+
+      if (requiredResult.requiredServerNames.length > 0) {
+        coreEvents.emitConsoleLog(
+          'info',
+          `Admin-required MCP servers injected: ${requiredResult.requiredServerNames.join(', ')}`,
+        );
+      }
+    }
+  }
+
   const isAcpMode = !!argv.acp || !!argv.experimentalAcp;
   let clientName: string | undefined = undefined;
   if (isAcpMode) {

packages/cli/src/config/settings.test.ts

@@ -2751,6 +2751,28 @@ describe('Settings Loading and Merging', () => {
       expect(loadedSettings.merged.admin?.mcp?.config).toEqual(mcpServers);
     });
 
+    it('should map requiredMcpConfig from remote settings', () => {
+      const loadedSettings = loadSettings(MOCK_WORKSPACE_DIR);
+      const requiredMcpConfig = {
+        'corp-tool': {
+          url: 'https://mcp.corp/tool',
+          type: 'http' as const,
+          trust: true,
+        },
+      };
+
+      loadedSettings.setRemoteAdminSettings({
+        mcpSetting: {
+          mcpEnabled: true,
+          requiredMcpConfig,
+        },
+      });
+
+      expect(loadedSettings.merged.admin?.mcp?.requiredConfig).toEqual(
+        requiredMcpConfig,
+      );
+    });
+
     it('should set skills based on unmanagedCapabilitiesEnabled', () => {
       const loadedSettings = loadSettings();
       loadedSettings.setRemoteAdminSettings({

packages/cli/src/config/settings.ts

@@ -480,6 +480,7 @@ export class LoadedSettings {
     admin.mcp = {
       enabled: mcpSetting?.mcpEnabled,
       config: mcpSetting?.mcpConfig?.mcpServers,
+      requiredConfig: mcpSetting?.requiredMcpConfig,
     };
     admin.extensions = {
       enabled: cliFeatureSetting?.extensionsSetting?.extensionsEnabled,

packages/cli/src/config/settingsSchema.ts

@@ -12,7 +12,9 @@
 import {
   DEFAULT_TRUNCATE_TOOL_OUTPUT_THRESHOLD,
   DEFAULT_MODEL_CONFIGS,
+  AuthProviderType,
   type MCPServerConfig,
+  type RequiredMcpServerConfig,
   type BugCommandSettings,
   type TelemetrySettings,
   type AuthType,
@@ -2435,14 +2437,28 @@ const SETTINGS_SCHEMA = {
             category: 'Admin',
             requiresRestart: false,
             default: {} as Record<string, MCPServerConfig>,
-            description: 'Admin-configured MCP servers.',
+            description: 'Admin-configured MCP servers (allowlist).',
             showInDialog: false,
             mergeStrategy: MergeStrategy.REPLACE,
             additionalProperties: {
               type: 'object',
               ref: 'MCPServerConfig',
             },
           },
+          requiredConfig: {
+            type: 'object',
+            label: 'Required MCP Config',
+            category: 'Admin',
+            requiresRestart: false,
+            default: {} as Record<string, RequiredMcpServerConfig>,
+            description: 'Admin-required MCP servers that are always injected.',
+            showInDialog: false,
+            mergeStrategy: MergeStrategy.REPLACE,
+            additionalProperties: {
+              type: 'object',
+              ref: 'RequiredMcpServerConfig',
+            },
+          },
         },
       },
       skills: {
@@ -2567,11 +2583,72 @@ export const SETTINGS_SCHEMA_DEFINITIONS: Record<
         type: 'string',
         description:
           'Authentication provider used for acquiring credentials (for example `dynamic_discovery`).',
-        enum: [
-          'dynamic_discovery',
-          'google_credentials',
-          'service_account_impersonation',
-        ],
+        enum: Object.values(AuthProviderType),
+      },
+      targetAudience: {
+        type: 'string',
+        description:
+          'OAuth target audience (CLIENT_ID.apps.googleusercontent.com).',
+      },
+      targetServiceAccount: {
+        type: 'string',
+        description:
+          'Service account email to impersonate (name@project.iam.gserviceaccount.com).',
+      },
+    },
+  },
+  RequiredMcpServerConfig: {
+    type: 'object',
+    description:
+      'Admin-required MCP server configuration (remote transports only).',
+    additionalProperties: false,
+    properties: {
+      url: {
+        type: 'string',
+        description: 'URL for the required MCP server.',
+      },
+      type: {
+        type: 'string',
+        description: 'Transport type for the required server.',
+        enum: ['sse', 'http'],
+      },
+      headers: {
+        type: 'object',
+        description: 'Additional HTTP headers sent to the server.',
+        additionalProperties: { type: 'string' },
+      },
+      timeout: {
+        type: 'number',
+        description: 'Timeout in milliseconds for MCP requests.',
+      },
+      trust: {
+        type: 'boolean',
+        description:
+          'Marks the server as trusted. Defaults to true for admin-required servers.',
+      },
+      description: {
+        type: 'string',
+        description: 'Human-readable description of the server.',
+      },
+      includeTools: {
+        type: 'array',
+        description: 'Subset of tools enabled for this server.',
+        items: { type: 'string' },
+      },
+      excludeTools: {
+        type: 'array',
+        description: 'Tools disabled for this server.',
+        items: { type: 'string' },
+      },
+      oauth: {
+        type: 'object',
+        description: 'OAuth configuration for authenticating with the server.',
+        additionalProperties: true,
+      },
+      authProviderType: {
+        type: 'string',
+        description: 'Authentication provider used for acquiring credentials.',
+        enum: Object.values(AuthProviderType),
       },
       targetAudience: {
         type: 'string',

packages/core/src/code_assist/admin/admin_controls.test.ts

@@ -224,6 +224,89 @@ describe('Admin Controls', () => {
       const result = sanitizeAdminSettings(input);
       expect(result.strictModeDisabled).toBe(true);
     });
+
+    it('should parse requiredMcpServers from mcpConfigJson', () => {
+      const mcpConfig = {
+        mcpServers: {
+          'allowed-server': {
+            url: 'http://allowed.com',
+            type: 'sse' as const,
+          },
+        },
+        requiredMcpServers: {
+          'corp-tool': {
+            url: 'https://mcp.corp/tool',
+            type: 'http' as const,
+            trust: true,
+            description: 'Corp compliance tool',
+          },
+        },
+      };
+
+      const input: FetchAdminControlsResponse = {
+        mcpSetting: {
+          mcpEnabled: true,
+          mcpConfigJson: JSON.stringify(mcpConfig),
+        },
+      };
+
+      const result = sanitizeAdminSettings(input);
+      expect(result.mcpSetting?.mcpConfig?.mcpServers).toEqual(
+        mcpConfig.mcpServers,
+      );
+      expect(result.mcpSetting?.requiredMcpConfig).toEqual(
+        mcpConfig.requiredMcpServers,
+      );
+    });
+
+    it('should sort requiredMcpServers tool lists for stable comparison', () => {
+      const mcpConfig = {
+        requiredMcpServers: {
+          'corp-tool': {
+            url: 'https://mcp.corp/tool',
+            type: 'http' as const,
+            includeTools: ['toolC', 'toolA', 'toolB'],
+            excludeTools: ['toolZ', 'toolX'],
+          },
+        },
+      };
+
+      const input: FetchAdminControlsResponse = {
+        mcpSetting: {
+          mcpEnabled: true,
+          mcpConfigJson: JSON.stringify(mcpConfig),
+        },
+      };
+
+      const result = sanitizeAdminSettings(input);
+      const corpTool = result.mcpSetting?.requiredMcpConfig?.['corp-tool'];
+      expect(corpTool?.includeTools).toEqual(['toolA', 'toolB', 'toolC']);
+      expect(corpTool?.excludeTools).toEqual(['toolX', 'toolZ']);
+    });
+
+    it('should handle mcpConfigJson with only requiredMcpServers and no mcpServers', () => {
+      const mcpConfig = {
+        requiredMcpServers: {
+          'required-only': {
+            url: 'https://required.corp/tool',
+            type: 'http' as const,
+          },
+        },
+      };
+
+      const input: FetchAdminControlsResponse = {
+        mcpSetting: {
+          mcpEnabled: true,
+          mcpConfigJson: JSON.stringify(mcpConfig),
+        },
+      };
+
+      const result = sanitizeAdminSettings(input);
+      expect(result.mcpSetting?.mcpConfig?.mcpServers).toBeUndefined();
+      expect(result.mcpSetting?.requiredMcpConfig).toEqual(
+        mcpConfig.requiredMcpServers,
+      );
+    });
   });
 
   describe('isDeepStrictEqual verification', () => {

packages/core/src/code_assist/admin/admin_controls.ts

@@ -48,6 +48,16 @@ export function sanitizeAdminSettings(
             }
           }
         }
+        if (mcpConfig.requiredMcpServers) {
+          for (const server of Object.values(mcpConfig.requiredMcpServers)) {
+            if (server.includeTools) {
+              server.includeTools.sort();
+            }
+            if (server.excludeTools) {
+              server.excludeTools.sort();
+            }
+          }
+        }
       }
     } catch (_e) {
       // Ignore parsing errors
@@ -77,6 +87,7 @@ export function sanitizeAdminSettings(
     mcpSetting: {
       mcpEnabled: sanitized.mcpSetting?.mcpEnabled ?? false,
       mcpConfig: mcpConfig ?? {},
+      requiredMcpConfig: mcpConfig?.requiredMcpServers,
     },
   };
 }