🔒 feat: Add MCP server domain restrictions for remote transports (#11013)

* 🔒 feat: Add MCP server domain restrictions for remote transports

* 🔒 feat: Implement comprehensive MCP error handling and domain validation

- Added `handleMCPError` function to centralize error responses for domain restrictions and inspection failures.
- Introduced custom error classes: `MCPDomainNotAllowedError` and `MCPInspectionFailedError` for better error management.
- Updated MCP server controllers to utilize the new error handling mechanism.
- Enhanced domain validation logic in `createMCPTools` and `createMCPTool` functions to prevent operations on disallowed domains.
- Added tests for runtime domain validation scenarios to ensure correct behavior.

* chore: import order

* 🔒 feat: Enhance domain validation in MCP tools with user role-based restrictions

- Integrated `getAppConfig` to fetch allowed domains based on user roles in `createMCPTools` and `createMCPTool` functions.
- Removed the deprecated `getAllowedDomains` method from `MCPServersRegistry`.
- Updated tests to verify domain restrictions are applied correctly based on user roles.
- Ensured that domain validation logic is consistent and efficient across tool creation processes.

* 🔒 test: Refactor MCP tests to utilize configurable app settings

- Introduced a mock for `getAppConfig` to enhance test flexibility.
- Removed redundant mock definition to streamline test setup.
- Ensured tests are aligned with the latest domain validation logic.

---------

Co-authored-by: Atef Bellaaj <slalom.bellaaj@external.daimlertruck.com>
Co-authored-by: Danny Avila <danny@librechat.ai>

packages/api/src/auth/domain.spec.ts

@@ -1,5 +1,10 @@
 /* eslint-disable @typescript-eslint/ban-ts-comment */
-import { isEmailDomainAllowed, isActionDomainAllowed } from './domain';
+import {
+  isEmailDomainAllowed,
+  isActionDomainAllowed,
+  extractMCPServerDomain,
+  isMCPDomainAllowed,
+} from './domain';
 
 describe('isEmailDomainAllowed', () => {
   afterEach(() => {
@@ -213,3 +218,209 @@ describe('isActionDomainAllowed', () => {
     });
   });
 });
+
+describe('extractMCPServerDomain', () => {
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('URL extraction', () => {
+    it('should extract domain from HTTPS URL', () => {
+      const config = { url: 'https://api.example.com/sse' };
+      expect(extractMCPServerDomain(config)).toBe('api.example.com');
+    });
+
+    it('should extract domain from HTTP URL', () => {
+      const config = { url: 'http://api.example.com/sse' };
+      expect(extractMCPServerDomain(config)).toBe('api.example.com');
+    });
+
+    it('should extract domain from WebSocket URL', () => {
+      const config = { url: 'wss://ws.example.com' };
+      expect(extractMCPServerDomain(config)).toBe('ws.example.com');
+    });
+
+    it('should handle URL with port', () => {
+      const config = { url: 'https://localhost:3001/sse' };
+      expect(extractMCPServerDomain(config)).toBe('localhost');
+    });
+
+    it('should strip www prefix', () => {
+      const config = { url: 'https://www.example.com/api' };
+      expect(extractMCPServerDomain(config)).toBe('example.com');
+    });
+
+    it('should handle URL with path and query parameters', () => {
+      const config = { url: 'https://api.example.com/v1/sse?token=abc' };
+      expect(extractMCPServerDomain(config)).toBe('api.example.com');
+    });
+  });
+
+  describe('stdio transports (no URL)', () => {
+    it('should return null for stdio transport with command only', () => {
+      const config = { command: 'npx', args: ['-y', '@modelcontextprotocol/server-puppeteer'] };
+      expect(extractMCPServerDomain(config)).toBeNull();
+    });
+
+    it('should return null when url is undefined', () => {
+      const config = { command: 'node', args: ['server.js'] };
+      expect(extractMCPServerDomain(config)).toBeNull();
+    });
+
+    it('should return null for empty object', () => {
+      const config = {};
+      expect(extractMCPServerDomain(config)).toBeNull();
+    });
+  });
+
+  describe('invalid URLs', () => {
+    it('should return null for invalid URL format', () => {
+      const config = { url: 'not-a-valid-url' };
+      expect(extractMCPServerDomain(config)).toBeNull();
+    });
+
+    it('should return null for empty URL string', () => {
+      const config = { url: '' };
+      expect(extractMCPServerDomain(config)).toBeNull();
+    });
+
+    it('should return null for non-string url', () => {
+      const config = { url: 12345 };
+      expect(extractMCPServerDomain(config)).toBeNull();
+    });
+
+    it('should return null for null url', () => {
+      const config = { url: null };
+      expect(extractMCPServerDomain(config)).toBeNull();
+    });
+  });
+});
+
+describe('isMCPDomainAllowed', () => {
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('stdio transports (always allowed)', () => {
+    it('should allow stdio transport regardless of allowlist', async () => {
+      const config = { command: 'npx', args: ['-y', '@modelcontextprotocol/server-puppeteer'] };
+      expect(await isMCPDomainAllowed(config, ['example.com'])).toBe(true);
+    });
+
+    it('should allow stdio transport even with empty allowlist', async () => {
+      const config = { command: 'node', args: ['server.js'] };
+      expect(await isMCPDomainAllowed(config, [])).toBe(true);
+    });
+
+    it('should allow stdio transport when no URL present', async () => {
+      const config = {};
+      expect(await isMCPDomainAllowed(config, ['restricted.com'])).toBe(true);
+    });
+  });
+
+  describe('permissive defaults (no restrictions)', () => {
+    it('should allow all domains when allowedDomains is null', async () => {
+      const config = { url: 'https://any-domain.com/sse' };
+      expect(await isMCPDomainAllowed(config, null)).toBe(true);
+    });
+
+    it('should allow all domains when allowedDomains is undefined', async () => {
+      const config = { url: 'https://any-domain.com/sse' };
+      expect(await isMCPDomainAllowed(config, undefined)).toBe(true);
+    });
+
+    it('should allow all domains when allowedDomains is empty array', async () => {
+      const config = { url: 'https://any-domain.com/sse' };
+      expect(await isMCPDomainAllowed(config, [])).toBe(true);
+    });
+  });
+
+  describe('exact domain matching', () => {
+    const allowedDomains = ['example.com', 'localhost', 'trusted-mcp.com'];
+
+    it('should allow exact domain match', async () => {
+      const config = { url: 'https://example.com/api' };
+      expect(await isMCPDomainAllowed(config, allowedDomains)).toBe(true);
+    });
+
+    it('should allow localhost', async () => {
+      const config = { url: 'http://localhost:3001/sse' };
+      expect(await isMCPDomainAllowed(config, allowedDomains)).toBe(true);
+    });
+
+    it('should reject non-allowed domain', async () => {
+      const config = { url: 'https://malicious.com/sse' };
+      expect(await isMCPDomainAllowed(config, allowedDomains)).toBe(false);
+    });
+
+    it('should reject subdomain when only parent is allowed', async () => {
+      const config = { url: 'https://api.example.com/sse' };
+      expect(await isMCPDomainAllowed(config, allowedDomains)).toBe(false);
+    });
+  });
+
+  describe('wildcard domain matching', () => {
+    const allowedDomains = ['*.example.com', 'localhost'];
+
+    it('should allow subdomain with wildcard', async () => {
+      const config = { url: 'https://api.example.com/sse' };
+      expect(await isMCPDomainAllowed(config, allowedDomains)).toBe(true);
+    });
+
+    it('should allow any subdomain with wildcard', async () => {
+      const config = { url: 'https://staging.example.com/sse' };
+      expect(await isMCPDomainAllowed(config, allowedDomains)).toBe(true);
+    });
+
+    it('should allow base domain with wildcard', async () => {
+      const config = { url: 'https://example.com/sse' };
+      expect(await isMCPDomainAllowed(config, allowedDomains)).toBe(true);
+    });
+
+    it('should allow nested subdomain with wildcard', async () => {
+      const config = { url: 'https://deep.nested.example.com/sse' };
+      expect(await isMCPDomainAllowed(config, allowedDomains)).toBe(true);
+    });
+
+    it('should reject different domain even with wildcard', async () => {
+      const config = { url: 'https://api.other.com/sse' };
+      expect(await isMCPDomainAllowed(config, allowedDomains)).toBe(false);
+    });
+  });
+
+  describe('case insensitivity', () => {
+    it('should match domains case-insensitively', async () => {
+      const config = { url: 'https://EXAMPLE.COM/sse' };
+      expect(await isMCPDomainAllowed(config, ['example.com'])).toBe(true);
+    });
+
+    it('should match with uppercase in allowlist', async () => {
+      const config = { url: 'https://example.com/sse' };
+      expect(await isMCPDomainAllowed(config, ['EXAMPLE.COM'])).toBe(true);
+    });
+
+    it('should match with mixed case', async () => {
+      const config = { url: 'https://Api.Example.Com/sse' };
+      expect(await isMCPDomainAllowed(config, ['*.example.com'])).toBe(true);
+    });
+  });
+
+  describe('www prefix handling', () => {
+    it('should strip www prefix from URL before matching', async () => {
+      const config = { url: 'https://www.example.com/sse' };
+      expect(await isMCPDomainAllowed(config, ['example.com'])).toBe(true);
+    });
+
+    it('should match www in allowlist to non-www URL', async () => {
+      const config = { url: 'https://example.com/sse' };
+      expect(await isMCPDomainAllowed(config, ['www.example.com'])).toBe(true);
+    });
+  });
+
+  describe('invalid URL handling', () => {
+    it('should allow config with invalid URL (treated as stdio)', async () => {
+      const config = { url: 'not-a-valid-url' };
+      expect(await isMCPDomainAllowed(config, ['example.com'])).toBe(true);
+    });
+  });
+});

packages/api/src/auth/domain.ts

@@ -96,3 +96,45 @@ export async function isActionDomainAllowed(
 
   return false;
 }
+
+/**
+ * Extracts domain from MCP server config URL.
+ * Returns null for stdio transports (no URL) or invalid URLs.
+ * @param config - MCP server configuration (accepts any config with optional url field)
+ */
+export function extractMCPServerDomain(config: Record<string, unknown>): string | null {
+  const url = config.url;
+  // Stdio transports don't have URLs - always allowed
+  if (!url || typeof url !== 'string') {
+    return null;
+  }
+
+  try {
+    const parsedUrl = new URL(url);
+    return parsedUrl.hostname.replace(/^www\./i, '');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Validates MCP server domain against allowedDomains.
+ * Reuses isActionDomainAllowed for consistent validation logic.
+ * Stdio transports (no URL) are always allowed.
+ * @param config - MCP server configuration with optional url field
+ * @param allowedDomains - List of allowed domains (with wildcard support)
+ */
+export async function isMCPDomainAllowed(
+  config: Record<string, unknown>,
+  allowedDomains?: string[] | null,
+): Promise<boolean> {
+  const domain = extractMCPServerDomain(config);
+
+  // Stdio transports don't have domains - always allowed
+  if (!domain) {
+    return true;
+  }
+
+  // Reuse existing validation logic (includes wildcard support)
+  return isActionDomainAllowed(domain, allowedDomains);
+}