feat(ai): configurable MCP transport host-allowlist for cloud deploy behind a proxy (#12371) (#12373)

* feat(ai): configurable MCP transport host-allowlist for cloud deploy behind a proxy (#12371)

MCP HTTP/SSE servers (knowledge-base + memory-core) behind a reverse proxy on a real public
hostname were rejected with `-32000 Invalid Host: <host>` for every request: TransportService
called the SDK's `createMcpExpressApp()` with no options, so it defaulted to localhost-only
DNS-rebinding protection. The public Host the proxy forwards was never allowlisted.

`TransportService.computeAllowedHosts(aiConfig)` now builds the list passed to
`createMcpExpressApp({allowedHosts})`:
  ['localhost','127.0.0.1','[::1]'] ∪ (publicUrl hostname) ∪ (NEO_MCP_ALLOWED_HOSTS, comma-split).

- The localhost set is ALWAYS included — the container healthcheck hits `http://127.0.0.1:<port>`;
  dropping it would fail the healthcheck (restart loop). Localhost-only deployments are unchanged
  (the computed list equals the prior default), so zero regression.
- Reuses the existing `NEO_PUBLIC_URL` leaf (derives its hostname).
- New `allowedHosts` leaf -> `NEO_MCP_ALLOWED_HOSTS` (comma-separated) for multi-hostname or
  Host != publicUrl cases, declared in the base + both per-server templates (kb + mc each declare
  their transport block independently).

Both servers share TransportService, so one logic change covers kb + mc.

Tests: 16/16 TransportService unit specs pass (11 existing + 5 new computeAllowedHosts cases:
localhost-always/healthcheck-safe, publicUrl-derived, NEO_MCP_ALLOWED_HOSTS-extra+trim,
de-dup, unparseable-publicUrl-ignored).

Resolves #12371

Co-Authored-By: neo-opus-4-7 <neo-opus-4-7@neomjs.com>

* docs(ai): fix computeAllowedHosts JSDoc — instance method, not static (#12371)

Author: neo-opus-ada

ai/config.template.mjs

@@ -63,6 +63,15 @@ class Config extends BaseConfig {
              * @type {string|null}
              */
             publicUrl: leaf(null, 'NEO_PUBLIC_URL', 'url'),
+            /**
+             * Comma-separated extra hostnames added to the MCP transport's Host-header allowlist
+             * (the SDK's DNS-rebinding protection). localhost/127.0.0.1/[::1] and the `publicUrl`
+             * hostname are always allowed; set this for multi-hostname deployments or where the
+             * client `Host` differs from `publicUrl`. Empty/null → only the implicit localhost +
+             * publicUrl hosts. Consumed by TransportService.computeAllowedHosts.
+             * @type {string|null}
+             */
+            allowedHosts: leaf(null, 'NEO_MCP_ALLOWED_HOSTS', 'string'),
             /**
              * Port the MCP server's HTTP/SSE transport listens on.
              * Sub-servers will typically override this with their own defaultPort.

ai/mcp/server/knowledge-base/config.template.mjs

@@ -65,6 +65,15 @@ class Config extends BaseConfig {
              * @type {string|null}
              */
             publicUrl: leaf(null, 'NEO_PUBLIC_URL', 'url'),
+            /**
+             * Comma-separated extra hostnames added to the MCP transport's Host-header allowlist
+             * (the SDK's DNS-rebinding protection). localhost/127.0.0.1/[::1] and the `publicUrl`
+             * hostname are always allowed; set this for multi-hostname deployments or where the
+             * client `Host` differs from `publicUrl`. Empty/null → only the implicit localhost +
+             * publicUrl hosts. Consumed by TransportService.computeAllowedHosts.
+             * @type {string|null}
+             */
+            allowedHosts: leaf(null, 'NEO_MCP_ALLOWED_HOSTS', 'string'),
             /**
              * Optional Express middleware function for authentication (only used if transport is 'sse').
              * @type {Function|null}

ai/mcp/server/memory-core/config.template.mjs

@@ -82,6 +82,15 @@ class Config extends BaseConfig {
              * @type {string|null}
              */
             publicUrl: leaf(null, 'NEO_PUBLIC_URL', 'url'),
+            /**
+             * Comma-separated extra hostnames added to the MCP transport's Host-header allowlist
+             * (the SDK's DNS-rebinding protection). localhost/127.0.0.1/[::1] and the `publicUrl`
+             * hostname are always allowed; set this for multi-hostname deployments or where the
+             * client `Host` differs from `publicUrl`. Empty/null → only the implicit localhost +
+             * publicUrl hosts. Consumed by TransportService.computeAllowedHosts.
+             * @type {string|null}
+             */
+            allowedHosts: leaf(null, 'NEO_MCP_ALLOWED_HOSTS', 'string'),
             /**
              * Optional Express middleware function for authentication (only used if transport is 'sse').
              * @type {Function|null}

ai/mcp/server/shared/services/TransportService.mjs

@@ -85,6 +85,41 @@ class TransportService extends Base {
      */
     mcpServers = new Map()
 
+    /**
+     * Computes the Host-header allowlist for the SDK's DNS-rebinding protection
+     * (`createMcpExpressApp({allowedHosts})`). Pure + side-effect-free so it is unit-testable
+     * (an instance method on the singleton, callable as `TransportService.computeAllowedHosts(...)`)
+     * without a live transport. The localhost set is ALWAYS included — the container healthcheck hits
+     * `http://127.0.0.1:<port>`, so dropping it would fail the healthcheck (restart loop). The
+     * public hostname is derived from `aiConfig.publicUrl` (the existing `NEO_PUBLIC_URL` leaf) and
+     * augmented by the comma-separated `aiConfig.allowedHosts` (`NEO_MCP_ALLOWED_HOSTS`) for
+     * multi-hostname deployments or where the client `Host` differs from the advertised URL.
+     * @param {Object} [aiConfig={}]
+     * @param {String|null} [aiConfig.publicUrl]
+     * @param {String|null} [aiConfig.allowedHosts] Comma-separated extra hostnames
+     * @returns {String[]} De-duplicated allowlist (hostnames, port-agnostic; IPv6 in brackets)
+     */
+    computeAllowedHosts(aiConfig={}) {
+        const hosts = new Set(['localhost', '127.0.0.1', '[::1]']);
+
+        if (aiConfig.publicUrl) {
+            try {
+                hosts.add(new URL(aiConfig.publicUrl).hostname)
+            } catch {
+                // Unparseable publicUrl is ignored here; an explicit NEO_MCP_ALLOWED_HOSTS entry can still cover it.
+            }
+        }
+
+        if (aiConfig.allowedHosts) {
+            for (const host of String(aiConfig.allowedHosts).split(',')) {
+                const trimmed = host.trim();
+                trimmed && hosts.add(trimmed)
+            }
+        }
+
+        return [...hosts]
+    }
+
     /**
      * Setups the SSE transport for an MCP server.
      * @param {Object} options
@@ -101,7 +136,11 @@ class TransportService extends Base {
         const { StreamableHTTPServerTransport } = await import('@modelcontextprotocol/sdk/server/streamableHttp.js');
         const crypto = await import('crypto');
         const cors = await import('cors');
-        const app = createMcpExpressApp();
+        // Host-allowlist for the SDK's DNS-rebinding protection. Always includes localhost (the
+        // container healthcheck hits 127.0.0.1) plus the publicUrl hostname + NEO_MCP_ALLOWED_HOSTS,
+        // so a cloud deployment behind a reverse proxy on a public hostname is not rejected with
+        // `-32000 Invalid Host`.
+        const app = createMcpExpressApp({allowedHosts: this.computeAllowedHosts(aiConfig)});
 
         this.app = app;
 

test/playwright/unit/ai/mcp/server/shared/services/TransportService.spec.mjs

@@ -93,7 +93,7 @@ test.describe('Neo.ai.mcp.server.shared.services.TransportService', () => {
     });
 
     test('setup() awaits listener accept-state before resolving (#10932)', async () => {
-        // Bind-race regression guard: prior to #10932, TransportService.setup() returned
+        // Bind-race regression guard: prior to the listen-callback fix, TransportService.setup() returned
         // synchronously after `app.listen()` without awaiting the listen-callback. Under load
         // or fullyParallel test interleaving, the calling spec's subsequent `fetch()` could
         // race the bind and observe the response object lacking expected shape (e.g.,
@@ -306,4 +306,39 @@ test.describe('Neo.ai.mcp.server.shared.services.TransportService', () => {
         });
     });
 
+    test.describe('computeAllowedHosts host-allowlist (DNS-rebinding) — #12371', () => {
+        let TransportService;
+
+        test.beforeAll(async () => {
+            TransportService = (await import('../../../../../../../../ai/mcp/server/shared/services/TransportService.mjs')).default;
+        });
+
+        test('always includes the localhost set (empty config) — healthcheck-safe', () => {
+            expect(TransportService.computeAllowedHosts({})).toEqual(['localhost', '127.0.0.1', '[::1]']);
+        });
+
+        test('derives the public hostname from publicUrl, keeping localhost', () => {
+            const hosts = TransportService.computeAllowedHosts({publicUrl: 'https://mcp.example.com/knowledge-base'});
+            expect(hosts).toContain('mcp.example.com');
+            expect(hosts).toContain('localhost');
+            expect(hosts).toContain('127.0.0.1');
+        });
+
+        test('adds comma-separated NEO_MCP_ALLOWED_HOSTS entries, trimmed, dropping blanks', () => {
+            const hosts = TransportService.computeAllowedHosts({allowedHosts: 'a.example.com, b.example.com ,, c.example.com'});
+            expect(hosts).toEqual(expect.arrayContaining(['a.example.com', 'b.example.com', 'c.example.com']));
+            expect(hosts).not.toContain('');
+            expect(hosts).toContain('127.0.0.1');
+        });
+
+        test('de-duplicates when publicUrl host also appears in the explicit list', () => {
+            const hosts = TransportService.computeAllowedHosts({publicUrl: 'https://mcp.example.com', allowedHosts: 'mcp.example.com'});
+            expect(hosts.filter(host => host === 'mcp.example.com')).toHaveLength(1);
+        });
+
+        test('ignores an unparseable publicUrl without throwing', () => {
+            expect(TransportService.computeAllowedHosts({publicUrl: 'not a url'})).toEqual(['localhost', '127.0.0.1', '[::1]']);
+        });
+    });
+
 });