🔐 feat: Add API key authentication support for MCP servers (#10936)

* 🔐 feat: Add API key authentication support for MCP servers

* Chore: Copilot comments fixes

---------

Co-authored-by: Atef Bellaaj <slalom.bellaaj@external.daimlertruck.com>

packages/api/src/mcp/registry/MCPServerInspector.ts

@@ -68,6 +68,12 @@ export class MCPServerInspector {
       return;
     }
 
+    // Admin-provided API key means no OAuth flow is needed
+    if (this.config.apiKey?.source === 'admin') {
+      this.config.requiresOAuth = false;
+      return;
+    }
+
     const result = await detectOAuthRequirement(this.config.url);
     this.config.requiresOAuth = result.requiresOAuth;
     this.config.oauthMetadata = result.metadata;

packages/api/src/mcp/registry/MCPServersRegistry.ts

@@ -95,9 +95,25 @@ export class MCPServersRegistry {
     userId?: string,
   ): Promise<t.ParsedServerConfig> {
     const configRepo = this.getConfigRepository(storageLocation);
+
+    // Merge existing admin API key if not provided in update (needed for inspection)
+    let configForInspection = { ...config };
+    if (config.apiKey?.source === 'admin' && !config.apiKey?.key) {
+      const existingConfig = await configRepo.get(serverName, userId);
+      if (existingConfig?.apiKey?.key) {
+        configForInspection = {
+          ...configForInspection,
+          apiKey: {
+            ...configForInspection.apiKey!,
+            key: existingConfig.apiKey.key,
+          },
+        };
+      }
+    }
+
     let parsedConfig: t.ParsedServerConfig;
     try {
-      parsedConfig = await MCPServerInspector.inspect(serverName, config);
+      parsedConfig = await MCPServerInspector.inspect(serverName, configForInspection);
     } catch (error) {
       logger.error(`[MCPServersRegistry] Failed to inspect server "${serverName}":`, error);
       throw new Error(`MCP_INSPECTION_FAILED: Failed to connect to MCP server "${serverName}"`);

packages/api/src/mcp/registry/__tests__/MCPServerInspector.test.ts

@@ -175,6 +175,55 @@ describe('MCPServerInspector', () => {
       });
     });
 
+    it('should set requiresOAuth to false when apiKey.source is admin', async () => {
+      const rawConfig: t.MCPOptions = {
+        type: 'sse',
+        url: 'https://api.example.com/sse',
+        apiKey: {
+          source: 'admin',
+          authorization_type: 'bearer',
+          key: 'my-api-key',
+        },
+      };
+
+      // OAuth detection should be skipped
+      mockDetectOAuthRequirement.mockResolvedValue({
+        requiresOAuth: true, // This would be returned if called, but it shouldn't be
+        method: 'protected-resource-metadata',
+      });
+
+      const result = await MCPServerInspector.inspect('test_server', rawConfig, mockConnection);
+
+      // Should NOT call OAuth detection
+      expect(mockDetectOAuthRequirement).not.toHaveBeenCalled();
+
+      // requiresOAuth should be false due to admin-provided API key
+      expect(result.requiresOAuth).toBe(false);
+      expect(result.apiKey?.source).toBe('admin');
+    });
+
+    it('should still detect OAuth when apiKey.source is user', async () => {
+      const rawConfig: t.MCPOptions = {
+        type: 'sse',
+        url: 'https://api.example.com/sse',
+        apiKey: {
+          source: 'user',
+          authorization_type: 'bearer',
+        },
+      };
+
+      mockDetectOAuthRequirement.mockResolvedValue({
+        requiresOAuth: true,
+        method: 'protected-resource-metadata',
+      });
+
+      const result = await MCPServerInspector.inspect('test_server', rawConfig, mockConnection);
+
+      // Should call OAuth detection for user-provided API key
+      expect(mockDetectOAuthRequirement).toHaveBeenCalled();
+      expect(result.requiresOAuth).toBe(true);
+    });
+
     it('should fetch capabilities when server has no tools', async () => {
       const rawConfig: t.MCPOptions = {
         type: 'stdio',

packages/api/src/mcp/registry/__tests__/ServerConfigsDB.test.ts

@@ -265,6 +265,250 @@ describe('ServerConfigsDB', () => {
       expect(retrieved?.oauth?.client_id).toBe('my-client-id');
       expect(retrieved?.oauth?.client_secret).toBeUndefined();
     });
+
+    it('should encrypt apiKey.key when saving admin-provided API key', async () => {
+      const config: ParsedServerConfig = {
+        type: 'sse',
+        url: 'https://example.com/mcp',
+        title: 'Admin API Key Server',
+        apiKey: {
+          source: 'admin',
+          authorization_type: 'bearer',
+          key: 'my-secret-api-key',
+        },
+      };
+      const created = await serverConfigsDB.add('temp-name', config, userId);
+
+      // Verify the key is encrypted in DB (not plaintext)
+      const MCPServer = mongoose.models.MCPServer;
+      const server = await MCPServer.findOne({ serverName: created.serverName });
+      expect(server?.config?.apiKey?.key).not.toBe('my-secret-api-key');
+      expect(server?.config?.apiKey?.source).toBe('admin');
+      expect(server?.config?.apiKey?.authorization_type).toBe('bearer');
+
+      // Verify the key is decrypted when accessed via get()
+      const retrieved = await serverConfigsDB.get(created.serverName, userId);
+      expect(retrieved?.apiKey?.key).toBe('my-secret-api-key');
+    });
+
+    it('should preserve apiKey.key when not provided in update (admin mode)', async () => {
+      const config: ParsedServerConfig = {
+        type: 'sse',
+        url: 'https://example.com/mcp',
+        title: 'API Key Preserve Test',
+        apiKey: {
+          source: 'admin',
+          authorization_type: 'bearer',
+          key: 'original-api-key',
+        },
+      };
+      const created = await serverConfigsDB.add('temp-name', config, userId);
+
+      // Update without providing the key
+      const updatedConfig: ParsedServerConfig = {
+        type: 'sse',
+        url: 'https://example.com/mcp',
+        title: 'API Key Preserve Test',
+        description: 'Updated description',
+        apiKey: {
+          source: 'admin',
+          authorization_type: 'bearer',
+          // key not provided - should be preserved
+        },
+      };
+      await serverConfigsDB.update(created.serverName, updatedConfig, userId);
+
+      // Verify the key is still available and decrypted
+      const retrieved = await serverConfigsDB.get(created.serverName, userId);
+      expect(retrieved?.apiKey?.key).toBe('original-api-key');
+      expect(retrieved?.description).toBe('Updated description');
+    });
+
+    it('should allow updating apiKey.key when explicitly provided', async () => {
+      const config: ParsedServerConfig = {
+        type: 'sse',
+        url: 'https://example.com/mcp',
+        title: 'API Key Update Test',
+        apiKey: {
+          source: 'admin',
+          authorization_type: 'bearer',
+          key: 'old-api-key',
+        },
+      };
+      const created = await serverConfigsDB.add('temp-name', config, userId);
+
+      // Update with new key
+      const updatedConfig: ParsedServerConfig = {
+        type: 'sse',
+        url: 'https://example.com/mcp',
+        title: 'API Key Update Test',
+        apiKey: {
+          source: 'admin',
+          authorization_type: 'bearer',
+          key: 'new-api-key',
+        },
+      };
+      await serverConfigsDB.update(created.serverName, updatedConfig, userId);
+
+      // Verify the key is updated
+      const retrieved = await serverConfigsDB.get(created.serverName, userId);
+      expect(retrieved?.apiKey?.key).toBe('new-api-key');
+    });
+
+    it('should preserve apiKey.key when authorization_type changes (bearer to custom)', async () => {
+      const config: ParsedServerConfig = {
+        type: 'sse',
+        url: 'https://example.com/mcp',
+        title: 'API Key Auth Type Change Test',
+        apiKey: {
+          source: 'admin',
+          authorization_type: 'bearer',
+          key: 'my-api-key',
+        },
+      };
+      const created = await serverConfigsDB.add('temp-name', config, userId);
+
+      // Update: change from bearer to custom header, without providing key
+      const updatedConfig: ParsedServerConfig = {
+        type: 'sse',
+        url: 'https://example.com/mcp',
+        title: 'API Key Auth Type Change Test',
+        apiKey: {
+          source: 'admin',
+          authorization_type: 'custom',
+          custom_header: 'X-My-Api-Key',
+          // key not provided - should be preserved
+        },
+      };
+      await serverConfigsDB.update(created.serverName, updatedConfig, userId);
+
+      // Verify the key is preserved and authorization_type/custom_header updated
+      const retrieved = await serverConfigsDB.get(created.serverName, userId);
+      expect(retrieved?.apiKey?.key).toBe('my-api-key');
+      expect(retrieved?.apiKey?.authorization_type).toBe('custom');
+      expect(retrieved?.apiKey?.custom_header).toBe('X-My-Api-Key');
+    });
+
+    it('should NOT preserve apiKey.key when switching from admin to user source', async () => {
+      // Create server with admin-provided API key
+      const config: ParsedServerConfig = {
+        type: 'sse',
+        url: 'https://example.com/mcp',
+        title: 'Source Switch Test',
+        apiKey: {
+          source: 'admin',
+          authorization_type: 'bearer',
+          key: 'admin-secret-key',
+        },
+      };
+      const created = await serverConfigsDB.add('temp-name', config, userId);
+
+      // Update to user-provided mode (no key should be preserved)
+      const updatedConfig: ParsedServerConfig = {
+        type: 'sse',
+        url: 'https://example.com/mcp',
+        title: 'Source Switch Test',
+        apiKey: {
+          source: 'user',
+          authorization_type: 'bearer',
+        },
+      };
+      await serverConfigsDB.update(created.serverName, updatedConfig, userId);
+
+      // Verify the old admin key is NOT preserved (would be a security issue)
+      const retrieved = await serverConfigsDB.get(created.serverName, userId);
+      expect(retrieved?.apiKey?.source).toBe('user');
+      expect(retrieved?.apiKey?.key).toBeUndefined();
+    });
+
+    it('should NOT preserve apiKey.key when switching from user to admin without providing key', async () => {
+      // Create server with user-provided API key mode
+      const config: ParsedServerConfig = {
+        type: 'sse',
+        url: 'https://example.com/mcp',
+        title: 'User to Admin Switch Test',
+        apiKey: {
+          source: 'user',
+          authorization_type: 'bearer',
+        },
+      };
+      const created = await serverConfigsDB.add('temp-name', config, userId);
+
+      // Update to admin mode without providing a key
+      const updatedConfig: ParsedServerConfig = {
+        type: 'sse',
+        url: 'https://example.com/mcp',
+        title: 'User to Admin Switch Test',
+        apiKey: {
+          source: 'admin',
+          authorization_type: 'bearer',
+          // key not provided - should NOT try to preserve from user mode
+        },
+      };
+      await serverConfigsDB.update(created.serverName, updatedConfig, userId);
+
+      // Verify no key is present (user mode doesn't store keys)
+      const retrieved = await serverConfigsDB.get(created.serverName, userId);
+      expect(retrieved?.apiKey?.source).toBe('admin');
+      expect(retrieved?.apiKey?.key).toBeUndefined();
+    });
+
+    it('should transform user-provided API key config with customUserVars and headers', async () => {
+      const config: ParsedServerConfig = {
+        type: 'sse',
+        url: 'https://example.com/mcp',
+        title: 'User API Key Server',
+        apiKey: {
+          source: 'user',
+          authorization_type: 'bearer',
+        },
+      };
+      const created = await serverConfigsDB.add('temp-name', config, userId);
+
+      const retrieved = await serverConfigsDB.get(created.serverName, userId);
+      // Cast to access headers (SSE config has headers)
+      const retrievedWithHeaders = retrieved as ParsedServerConfig & {
+        headers?: Record<string, string>;
+      };
+
+      // Should have customUserVars with MCP_API_KEY
+      expect(retrieved?.customUserVars).toBeDefined();
+      expect(retrieved?.customUserVars?.MCP_API_KEY).toEqual({
+        title: 'API Key',
+        description: 'Your API key for this MCP server',
+      });
+
+      // Should have headers with placeholder
+      expect(retrievedWithHeaders?.headers).toBeDefined();
+      expect(retrievedWithHeaders?.headers?.Authorization).toBe('Bearer {{MCP_API_KEY}}');
+
+      // Key should be undefined (user provides it)
+      expect(retrieved?.apiKey?.key).toBeUndefined();
+    });
+
+    it('should transform user-provided API key with custom header', async () => {
+      const config: ParsedServerConfig = {
+        type: 'sse',
+        url: 'https://example.com/mcp',
+        title: 'Custom Header API Key Server',
+        apiKey: {
+          source: 'user',
+          authorization_type: 'custom',
+          custom_header: 'X-My-Api-Key',
+        },
+      };
+      const created = await serverConfigsDB.add('temp-name', config, userId);
+
+      const retrieved = await serverConfigsDB.get(created.serverName, userId);
+      // Cast to access headers (SSE config has headers)
+      const retrievedWithHeaders = retrieved as ParsedServerConfig & {
+        headers?: Record<string, string>;
+      };
+
+      // Should have headers with custom header name
+      expect(retrievedWithHeaders?.headers?.['X-My-Api-Key']).toBe('{{MCP_API_KEY}}');
+      expect(retrievedWithHeaders?.headers?.Authorization).toBeUndefined();
+    });
   });
 
   describe('remove()', () => {
@@ -997,5 +1241,36 @@ describe('ServerConfigsDB', () => {
       expect(result[created2.serverName]?.oauth?.client_id).toBe('client-2');
       expect(result[created2.serverName]?.oauth?.client_secret).toBeUndefined();
     });
+
+    it('should return config without apiKey.key when decryption fails (graceful degradation)', async () => {
+      const config: ParsedServerConfig = {
+        type: 'sse',
+        url: 'https://example.com/mcp',
+        title: 'API Key Decryption Failure Test',
+        apiKey: {
+          source: 'admin',
+          authorization_type: 'bearer',
+          key: 'test-api-key',
+        },
+      };
+      const created = await serverConfigsDB.add('temp-name', config, userId);
+
+      // Directly corrupt the encrypted key in the database to simulate decryption failure
+      const MCPServer = mongoose.models.MCPServer;
+      await MCPServer.updateOne(
+        { serverName: created.serverName },
+        { $set: { 'config.apiKey.key': 'invalid:corrupted:encrypted:value' } },
+      );
+
+      // Get should return config without the key (graceful degradation)
+      const retrieved = await serverConfigsDB.get(created.serverName, userId);
+
+      expect(retrieved).toBeDefined();
+      expect(retrieved?.title).toBe('API Key Decryption Failure Test');
+      expect(retrieved?.apiKey?.source).toBe('admin');
+      expect(retrieved?.apiKey?.authorization_type).toBe('bearer');
+      // Key should be removed due to decryption failure
+      expect(retrieved?.apiKey?.key).toBeUndefined();
+    });
   });
 });

packages/api/src/mcp/registry/db/ServerConfigsDB.ts

@@ -95,8 +95,10 @@ export class ServerConfigsDB implements IServerConfigsRepositoryInterface {
         '[ServerConfigsDB.add] User ID is required to create a database-stored MCP server.',
       );
     }
+    // Transform user-provided API key config (adds customUserVars and headers)
+    const transformedConfig = this.transformUserApiKeyConfig(config);
     // Encrypt sensitive fields before storing in database
-    const encryptedConfig = await this.encryptConfig(config);
+    const encryptedConfig = await this.encryptConfig(transformedConfig);
     const createdServer = await this._dbMethods.createMCPServer({
       config: encryptedConfig,
       author: userId,
@@ -132,25 +134,44 @@ export class ServerConfigsDB implements IServerConfigsRepositoryInterface {
       );
     }
 
-    // Handle secret preservation and encryption
     const existingServer = await this._dbMethods.findMCPServerById(serverName);
-    let configToSave: ParsedServerConfig;
+    let configToSave: ParsedServerConfig = { ...config };
 
+    // Transform user-provided API key config (adds customUserVars and headers)
+    configToSave = this.transformUserApiKeyConfig(configToSave);
+
+    // Encrypt NEW secrets only (secrets provided in this update)
+    // We must do this BEFORE preserving existing encrypted secrets
+    configToSave = await this.encryptConfig(configToSave);
+
+    // Preserve existing OAuth client_secret if not provided in update (already encrypted)
     if (!config.oauth?.client_secret && existingServer?.config?.oauth?.client_secret) {
-      // No new secret provided - preserve the existing encrypted secret from DB (don't re-encrypt)
       configToSave = {
-        ...config,
+        ...configToSave,
         oauth: {
-          ...config.oauth,
+          ...configToSave.oauth,
           client_secret: existingServer.config.oauth.client_secret,
         },
       };
-    } else if (config.oauth?.client_secret) {
-      // New secret provided - encrypt it
-      configToSave = await this.encryptConfig(config);
-    } else {
-      // No secret in config or DB - nothing to encrypt
-      configToSave = config;
+    }
+
+    // Preserve existing API key if not provided in update (already encrypted)
+    // Only preserve if both old and new configs use admin mode to avoid cross-mode key leakage
+    if (
+      config.apiKey?.source === 'admin' &&
+      !config.apiKey?.key &&
+      existingServer?.config?.apiKey?.source === 'admin' &&
+      existingServer?.config?.apiKey?.key
+    ) {
+      configToSave = {
+        ...configToSave,
+        apiKey: {
+          source: configToSave.apiKey!.source,
+          authorization_type: configToSave.apiKey!.authorization_type,
+          custom_header: configToSave.apiKey?.custom_header,
+          key: existingServer.config.apiKey.key,
+        },
+      };
     }
 
     // specific user permissions for action permission will be handled in the controller calling the  update method of the registry
@@ -366,56 +387,149 @@ export class ServerConfigsDB implements IServerConfigsRepositoryInterface {
     return await this.decryptConfig(config);
   }
 
+  /**
+   * Transforms user-provided API key config by auto-generating customUserVars and headers.
+   * This is a config transformation, not encryption.
+   * @param config - The server config to transform
+   * @returns The transformed config with customUserVars and headers set up
+   */
+  private transformUserApiKeyConfig(config: ParsedServerConfig): ParsedServerConfig {
+    if (!config.apiKey || config.apiKey.source !== 'user') {
+      return config;
+    }
+
+    const result = { ...config };
+    const headerName =
+      result.apiKey!.authorization_type === 'custom'
+        ? result.apiKey!.custom_header || 'X-Api-Key'
+        : 'Authorization';
+
+    let headerValue: string;
+    if (result.apiKey!.authorization_type === 'basic') {
+      headerValue = 'Basic {{MCP_API_KEY}}';
+    } else if (result.apiKey!.authorization_type === 'bearer') {
+      headerValue = 'Bearer {{MCP_API_KEY}}';
+    } else {
+      headerValue = '{{MCP_API_KEY}}';
+    }
+
+    result.customUserVars = {
+      ...result.customUserVars,
+      MCP_API_KEY: {
+        title: 'API Key',
+        description: 'Your API key for this MCP server',
+      },
+    };
+
+    // Cast to access headers property (not available on Stdio type)
+    const resultWithHeaders = result as ParsedServerConfig & {
+      headers?: Record<string, string>;
+    };
+    resultWithHeaders.headers = {
+      ...resultWithHeaders.headers,
+      [headerName]: headerValue,
+    };
+
+    // Remove key field since it's user-provided (destructure to omit, not set to undefined)
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const { key: _removed, ...apiKeyWithoutKey } = result.apiKey!;
+    result.apiKey = apiKeyWithoutKey;
+
+    return result;
+  }
+
   /**
    * Encrypts sensitive fields in config before database storage.
-   * Currently encrypts only oauth.client_secret.
+   * Encrypts oauth.client_secret and apiKey.key (when source === 'admin').
    * Throws on failure to prevent storing plaintext secrets.
    */
   private async encryptConfig(config: ParsedServerConfig): Promise<ParsedServerConfig> {
-    if (!config.oauth?.client_secret) {
-      return config;
+    let result = { ...config };
+
+    // Encrypt admin-provided API key
+    if (result.apiKey?.source === 'admin' && result.apiKey.key) {
+      try {
+        result.apiKey = {
+          ...result.apiKey,
+          key: await encryptV2(result.apiKey.key),
+        };
+      } catch (error) {
+        logger.error('[ServerConfigsDB.encryptConfig] Failed to encrypt apiKey.key', error);
+        throw new Error('Failed to encrypt MCP server configuration');
+      }
     }
-    try {
-      return {
-        ...config,
-        oauth: {
-          ...config.oauth,
-          client_secret: await encryptV2(config.oauth.client_secret),
-        },
-      };
-    } catch (error) {
-      logger.error('[ServerConfigsDB.encryptConfig] Failed to encrypt client_secret', error);
-      throw new Error('Failed to encrypt MCP server configuration');
+
+    // Encrypt OAuth client_secret
+    if (result.oauth?.client_secret) {
+      try {
+        result = {
+          ...result,
+          oauth: {
+            ...result.oauth,
+            client_secret: await encryptV2(result.oauth.client_secret),
+          },
+        };
+      } catch (error) {
+        logger.error('[ServerConfigsDB.encryptConfig] Failed to encrypt client_secret', error);
+        throw new Error('Failed to encrypt MCP server configuration');
+      }
     }
+
+    return result;
   }
 
   /**
    * Decrypts sensitive fields in config after database retrieval.
+   * Decrypts oauth.client_secret and apiKey.key (when source === 'admin').
    * Returns config without secret on failure (graceful degradation).
    */
   private async decryptConfig(config: ParsedServerConfig): Promise<ParsedServerConfig> {
-    if (!config.oauth?.client_secret) {
-      return config;
+    let result = { ...config };
+
+    // Handle API key decryption (admin-provided only)
+    if (result.apiKey?.source === 'admin' && result.apiKey.key) {
+      try {
+        result.apiKey = {
+          ...result.apiKey,
+          key: await decryptV2(result.apiKey.key),
+        };
+      } catch (error) {
+        logger.warn(
+          '[ServerConfigsDB.decryptConfig] Failed to decrypt apiKey.key, returning config without key',
+          error,
+        );
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const { key: _removedKey, ...apiKeyWithoutKey } = result.apiKey;
+        result.apiKey = apiKeyWithoutKey;
+      }
     }
-    try {
-      return {
-        ...config,
-        oauth: {
-          ...config.oauth,
-          client_secret: await decryptV2(config.oauth.client_secret),
-        },
-      };
-    } catch (error) {
-      logger.warn(
-        '[ServerConfigsDB.decryptConfig] Failed to decrypt client_secret, returning config without secret',
-        error,
-      );
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
-      const { client_secret: _removed, ...oauthWithoutSecret } = config.oauth;
-      return {
-        ...config,
-        oauth: oauthWithoutSecret,
-      };
+
+    // Handle OAuth client_secret decryption
+    if (result.oauth?.client_secret) {
+      // Cast oauth to type with client_secret since we've verified it exists
+      const oauthConfig = result.oauth as { client_secret: string } & typeof result.oauth;
+      try {
+        result = {
+          ...result,
+          oauth: {
+            ...oauthConfig,
+            client_secret: await decryptV2(oauthConfig.client_secret),
+          },
+        };
+      } catch (error) {
+        logger.warn(
+          '[ServerConfigsDB.decryptConfig] Failed to decrypt client_secret, returning config without secret',
+          error,
+        );
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const { client_secret: _removed, ...oauthWithoutSecret } = oauthConfig;
+        result = {
+          ...result,
+          oauth: oauthWithoutSecret,
+        };
+      }
     }
+
+    return result;
   }
 }