@lowdefy/server-dev 6.1.0 → 7.0.0

package/src/routes/endpointsTextAnswer.test.mjs

@@ -0,0 +1,77 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { Hono } from 'hono';
+import { jest } from '@jest/globals';
+
+const mockGetEndpointConfig = jest.fn();
+const mockRunWebhookEndpoint = jest.fn();
+jest.unstable_mockModule('@lowdefy/api', () => ({
+  callEndpoint: jest.fn(),
+  getEndpointConfig: mockGetEndpointConfig,
+  parseRequestBody: jest.fn(),
+  runWebhookEndpoint: mockRunWebhookEndpoint,
+}));
+
+const { default: endpointsHandler } = await import('./endpoints.js');
+
+const logger = { debug: jest.fn(), error: jest.fn(), info: jest.fn(), warn: jest.fn() };
+
+function createApp() {
+  const app = new Hono();
+  app.use('*', async (c, next) => {
+    c.set('lowdefyContext', { logger, handleError: jest.fn() });
+    await next();
+  });
+  app.all('/api/endpoints/*', endpointsHandler);
+  return app;
+}
+
+beforeEach(() => {
+  mockGetEndpointConfig.mockResolvedValue({ webhook: true });
+});
+
+test('a webhook answer with contentType text/plain is sent as the plain-text body', async () => {
+  mockRunWebhookEndpoint.mockResolvedValue({
+    status: 200,
+    body: 'Validation: Testing client application',
+    contentType: 'text/plain',
+  });
+  const res = await createApp().request(
+    '/api/endpoints/graph_notifications?validationToken=Validation%3A+Testing+client+application',
+    { method: 'POST' }
+  );
+  expect(res.status).toBe(200);
+  expect(res.headers.get('content-type')).toMatch(/^text\/plain\b/);
+  expect(res.headers.get('x-content-type-options')).toBe('nosniff');
+  expect(await res.text()).toBe('Validation: Testing client application');
+  expect(mockRunWebhookEndpoint).toHaveBeenCalledWith(
+    expect.anything(),
+    expect.objectContaining({
+      endpointId: 'graph_notifications',
+      query: { validationToken: 'Validation: Testing client application' },
+    })
+  );
+});
+
+test('a webhook answer without contentType is still sent as JSON', async () => {
+  mockRunWebhookEndpoint.mockResolvedValue({ status: 200, body: 'token' });
+  const res = await createApp().request('/api/endpoints/hook', { method: 'POST', body: '{}' });
+  expect(res.status).toBe(200);
+  expect(res.headers.get('content-type')).toMatch(/^application\/json\b/);
+  expect(res.headers.get('x-content-type-options')).toBeNull();
+  expect(await res.json()).toBe('token');
+});

package/src/routes/feedback.js

@@ -14,11 +14,15 @@
   limitations under the License.
 */
 
+import { parseRequestBody } from '@lowdefy/api';
+
 import enrichFeedback from '../../lib/docs/enrichFeedback.js';
 import formatFeedback from '../../lib/docs/formatFeedback.js';
 import createLogger from '../../lib/server/log/createLogger.js';
+import createSameOriginGuard from '../middleware/createSameOriginGuard.js';
 
 const logger = createLogger({ server: 'lowdefy-dev-feedback' });
+const guardSameOrigin = createSameOriginGuard();
 
 // Receives annotation batches from the dev browser overlay (a developer
 // draws on a live page and comments), enriches each annotation with its
@@ -26,22 +30,15 @@ const logger = createLogger({ server: 'lowdefy-dev-feedback' });
 // text. The overlay copies that text to the clipboard — the developer
 // pastes it into whichever agent session they choose, which is also what
 // makes delivery unambiguous when several sessions share one dev server.
-// Same-origin check cloned from routes/clientError.js: only a page served
-// by this dev server (not an arbitrary site) should be able to use it.
+// The same-origin guard the browser POST routes share: only a page served by
+// this dev server (not an arbitrary site) should be able to use it.
 async function feedbackHandler(c) {
-  const origin = c.req.header('origin');
-  if (!origin) {
-    return c.json({ error: 'Forbidden' }, 403);
-  }
-  try {
-    if (new URL(origin).host !== c.req.header('host')) {
-      return c.json({ error: 'Forbidden' }, 403);
-    }
-  } catch {
-    return c.json({ error: 'Forbidden' }, 403);
+  const forbidden = guardSameOrigin(c);
+  if (forbidden) {
+    return forbidden;
   }
 
-  const batch = await c.req.json();
+  const batch = parseRequestBody({ text: await c.req.text() });
   if (!Array.isArray(batch?.annotations)) {
     return c.json(
       {

package/src/routes/jitPage.js

@@ -15,49 +15,69 @@
 */
 
 import { getPageConfig } from '@lowdefy/api';
+import { matchPagePath } from '@lowdefy/node-utils';
 
-import buildPageIfNeeded, { getPageJitEnrichment } from '../../lib/server/jitPageBuilder.js';
-import getPathSegments from '../lib/getPathSegments.js';
+import authJson from '../../lib/build/auth.js';
+import { buildPageWithContext, getPageJitEnrichment } from '../../lib/server/jitPageBuilder.js';
+import getBuildId from '../../lib/docs/getBuildId.js';
+import getRequestPath from '../lib/getRequestPath.js';
+import lowdefyConfig from '../../lib/build/config.js';
+import servedBuilds from '../../lib/server/recording/servedBuilds.js';
+
+const basePath = lowdefyConfig.basePath ?? '';
 
 // JIT page build + config response. The response shapes are a frozen contract
 // with the dev client:
 //   200 { installing: true, packages }  — plugin install in progress, client polls
 //   500 { buildError: true, errors, message, source }  — build failed
+//   401 { redirect }  — logged-out navigation to a protected page
+//   403 { redirect }  — authorised but second factor not yet enrolled
 //   404 'Page not found.'
-//   200 pageConfig (+ _warnings, + _jsEntries module text, + _dynamicIcons data)
+//   200 { pageId, pathParams, matchedPath, pageConfig } (pageConfig + _buildId,
+//       + _warnings, + _jsEntries module text, + _dynamicIcons data)
+//
+// The request path is matched against the skeleton build's route table, and
+// the matched page is built before getPageConfig reads its file.
 async function jitPageHandler(c) {
   const context = c.get('lowdefyContext');
-  const pageId = getPathSegments(c, '/api/page/').join('/');
+  const { path, matchedPath } = getRequestPath({ c, basePath, prefix: '/api/page/' });
+  // The callbackUrl of the sign-in and enrolment redirects: the requested page,
+  // query included.
+  const callbackUrl = `${basePath}/${path}${new URL(c.req.url).search}`;
+  const match = matchPagePath({ routes: await context.readConfigFile('routes.json'), path });
 
   let buildResult;
-  try {
-    buildResult = await buildPageIfNeeded({
-      pageId,
-      buildDirectory: context.buildDirectory,
-      configDirectory: context.configDirectory,
-    });
-  } catch (error) {
-    const rawErrors = error.buildErrors ?? [error];
-    const errors = [];
-    for (const err of rawErrors) {
-      await context.handleError(err);
-      errors.push({
-        type: err.name ?? 'Error',
-        message: err.message,
-        source: err.source ?? null,
-        stack: err.stack ?? null,
-      });
+  let buildContext;
+  if (match !== null) {
+    try {
+      ({ result: buildResult, buildContext } = await buildPageWithContext({
+        pageId: match.pageId,
+        buildDirectory: context.buildDirectory,
+        configDirectory: context.configDirectory,
+      }));
+    } catch (error) {
+      const rawErrors = error.buildErrors ?? [error];
+      const errors = [];
+      for (const err of rawErrors) {
+        await context.handleError(err);
+        errors.push({
+          type: err.name ?? 'Error',
+          message: err.message,
+          source: err.source ?? null,
+          stack: err.stack ?? null,
+        });
+      }
+      return c.json(
+        {
+          buildError: true,
+          errors,
+          // Keep top-level message/source for backward compatibility
+          message: error.message,
+          source: error.source ?? null,
+        },
+        500
+      );
     }
-    return c.json(
-      {
-        buildError: true,
-        errors,
-        // Keep top-level message/source for backward compatibility
-        message: error.message,
-        source: error.source ?? null,
-      },
-      500
-    );
   }
 
   if (buildResult && buildResult.installing) {
@@ -67,20 +87,64 @@ async function jitPageHandler(c) {
     });
   }
 
-  const pageConfig = await getPageConfig(context, { pageId, urlQuery: c.req.query() });
-  if (pageConfig === null) {
+  const result = await getPageConfig(context, { path, urlQuery: c.req.query() });
+  if (result.status === 'unauthenticated') {
+    // The client follows this redirect with a full page load, so the login
+    // page can return to the requested page after sign-in.
+    context.logger.debug(
+      `Page config request for "/${path}" resolved unauthenticated - returning a sign-in redirect.`
+    );
+    return c.json(
+      {
+        redirect: `${basePath}${authJson.authPages.signIn}?callbackUrl=${encodeURIComponent(
+          callbackUrl
+        )}`,
+      },
+      401
+    );
+  }
+  if (result.status === 'enrol_required') {
+    // 403, not the 401 the signed-out branch above uses: a 401 is the client's
+    // dead-session signal and would bounce the user to sign-in, which is the loop
+    // the enrolment gate exists to avoid.
+    context.logger.debug(
+      `Page config request for "/${path}" resolved enrol_required - returning a two-factor enrolment redirect.`
+    );
+    return c.json(
+      {
+        redirect: `${basePath}${authJson.authPages.twoFactorEnrol}?callbackUrl=${encodeURIComponent(
+          callbackUrl
+        )}`,
+      },
+      403
+    );
+  }
+  if (result.status !== 'ok') {
     return c.text('Page not found.', 404);
   }
+  const pageConfig = result.pageConfig;
+  // The build this config was served under. The dev recorder stamps it on each
+  // record, and the recording route trusts only a build it finds in
+  // servedBuilds.
+  pageConfig._buildId = getBuildId();
+  servedBuilds.add(pageConfig._buildId);
   if (buildResult?.warnings?.length > 0) {
     pageConfig._warnings = buildResult.warnings;
   }
   // Fold this page's JIT-discovered _js entries and dynamic icons into the
   // response the client already awaits, so first paint has everything it needs
   // without the two secondary fetches that stalled in Vite's transform window.
-  const { jsEntries, dynamicIcons } = getPageJitEnrichment({ pageConfig });
+  // Read from the context the page was built on: another request can discard
+  // it while getPageConfig runs.
+  const { jsEntries, dynamicIcons } = getPageJitEnrichment({ pageConfig, buildContext });
   if (jsEntries) pageConfig._jsEntries = jsEntries;
   if (dynamicIcons) pageConfig._dynamicIcons = dynamicIcons;
-  return c.json(pageConfig);
+  return c.json({
+    pageId: result.pageId,
+    pathParams: result.pathParams,
+    matchedPath,
+    pageConfig,
+  });
 }
 
 export default jitPageHandler;

package/src/routes/jitPage.test.mjs

@@ -0,0 +1,248 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { Hono } from 'hono';
+import { jest } from '@jest/globals';
+
+const BUILD_A = '2026-10-03T14:02:00.000Z';
+const BUILD_B = '2026-10-03T14:05:00.000Z';
+let mockBuildId = BUILD_A;
+jest.unstable_mockModule('../../lib/docs/getBuildId.js', () => ({
+  default: () => mockBuildId,
+}));
+
+const mockGetPageConfig = jest.fn();
+jest.unstable_mockModule('@lowdefy/api', () => ({
+  getPageConfig: mockGetPageConfig,
+}));
+
+// No JIT build work in these tests — the route's build branch is exercised
+// elsewhere; here we only drive the getPageConfig status fork.
+const mockGetPageJitEnrichment = jest.fn(() => ({}));
+const mockBuildContext = { jsMap: { client: {} } };
+const mockBuildPageWithContext = jest.fn(async () => ({
+  result: true,
+  buildContext: mockBuildContext,
+}));
+jest.unstable_mockModule('../../lib/server/jitPageBuilder.js', () => ({
+  buildPageWithContext: mockBuildPageWithContext,
+  getPageJitEnrichment: mockGetPageJitEnrichment,
+}));
+
+jest.unstable_mockModule('../../lib/build/auth.js', () => ({
+  default: { authPages: { signIn: '/auth/login', twoFactorEnrol: '/two-factor-enrol' } },
+}));
+
+jest.unstable_mockModule('../../lib/build/config.js', () => ({
+  default: { basePath: '' },
+}));
+
+const { default: jitPageHandler } = await import('./jitPage.js');
+const { default: devRecordingHandler } = await import('./devRecording.js');
+const { default: servedBuilds } = await import('../../lib/server/recording/servedBuilds.js');
+
+const routes = [
+  { pageId: 'dashboard', path: 'dashboard' },
+  { pageId: 'ticket', path: '{space}/tickets/{ticket_id}' },
+];
+
+function createApp() {
+  const app = new Hono();
+  app.use('*', async (c, next) => {
+    c.set('lowdefyContext', {
+      buildDirectory: '/build',
+      configDirectory: '/config',
+      readConfigFile: async (file) => (file === 'routes.json' ? routes : null),
+      logger: { debug: jest.fn(), info: jest.fn(), error: jest.fn() },
+      handleError: jest.fn(),
+    });
+    await next();
+  });
+  app.all('/api/page/*', jitPageHandler);
+  app.post('/api/dev-recording', devRecordingHandler);
+  return app;
+}
+
+afterEach(() => {
+  mockGetPageConfig.mockReset();
+  mockBuildPageWithContext.mockClear();
+  mockBuildId = BUILD_A;
+});
+
+test('jitPageHandler redirects to the two-factor enrolment page with a 403 when enrol_required', async () => {
+  mockGetPageConfig.mockResolvedValue({ status: 'enrol_required' });
+  const res = await createApp().request('/api/page/dashboard');
+  expect(res.status).toEqual(403);
+  const body = await res.json();
+  expect(body).toEqual({ redirect: '/two-factor-enrol?callbackUrl=%2Fdashboard' });
+});
+
+test('jitPageHandler still returns a 401 sign-in redirect when unauthenticated', async () => {
+  mockGetPageConfig.mockResolvedValue({ status: 'unauthenticated' });
+  const res = await createApp().request('/api/page/dashboard');
+  expect(res.status).toEqual(401);
+  const body = await res.json();
+  expect(body).toEqual({ redirect: '/auth/login?callbackUrl=%2Fdashboard' });
+});
+
+test('jitPageHandler still returns a 404 when the page is not found', async () => {
+  mockGetPageConfig.mockResolvedValue({ status: 'not_found' });
+  const res = await createApp().request('/api/page/dashboard');
+  expect(res.status).toEqual(404);
+  expect(await res.text()).toEqual('Page not found.');
+});
+
+test('jitPageHandler returns the pageConfig when status is ok', async () => {
+  mockGetPageConfig.mockResolvedValue({
+    status: 'ok',
+    pageId: 'dashboard',
+    pathParams: {},
+    pageConfig: { id: 'dashboard' },
+  });
+  const res = await createApp().request('/api/page/dashboard');
+  expect(res.status).toEqual(200);
+  const body = await res.json();
+  expect(body).toEqual({
+    pageId: 'dashboard',
+    pathParams: {},
+    matchedPath: 'dashboard',
+    pageConfig: { id: 'dashboard', _buildId: BUILD_A },
+  });
+});
+
+test('jitPageHandler builds the page a patterned path matches and returns its path values', async () => {
+  mockGetPageConfig.mockResolvedValue({
+    status: 'ok',
+    pageId: 'ticket',
+    pathParams: { space: 'support', ticket_id: '1234' },
+    pageConfig: { id: 'ticket' },
+  });
+  const res = await createApp().request('/api/page/support/tickets/1234/?tab=2');
+  expect(mockBuildPageWithContext).toHaveBeenCalledWith({
+    pageId: 'ticket',
+    buildDirectory: '/build',
+    configDirectory: '/config',
+  });
+  expect(mockGetPageConfig.mock.calls[0][1]).toEqual({
+    path: 'support/tickets/1234/',
+    urlQuery: { tab: '2' },
+  });
+  expect(res.status).toEqual(200);
+  const body = await res.json();
+  expect(body).toEqual({
+    pageId: 'ticket',
+    pathParams: { space: 'support', ticket_id: '1234' },
+    matchedPath: 'support/tickets/1234',
+    pageConfig: { id: 'ticket', _buildId: BUILD_A },
+  });
+});
+
+test('jitPageHandler builds nothing for a path no page matches', async () => {
+  mockGetPageConfig.mockResolvedValue({ status: 'not_found' });
+  const res = await createApp().request('/api/page/support/tickets');
+  expect(mockBuildPageWithContext).not.toHaveBeenCalled();
+  expect(res.status).toEqual(404);
+});
+
+test('jitPageHandler sign-in redirect carries the request path and query on callbackUrl', async () => {
+  mockGetPageConfig.mockResolvedValue({ status: 'unauthenticated' });
+  const res = await createApp().request('/api/page/support/tickets?tab=2');
+  expect(res.status).toEqual(401);
+  expect(await res.json()).toEqual({
+    redirect: `/auth/login?callbackUrl=${encodeURIComponent('/support/tickets?tab=2')}`,
+  });
+});
+
+test('jitPageHandler folds _jsEntries and _dynamicIcons onto the ok response', async () => {
+  mockGetPageConfig.mockResolvedValue({ status: 'ok', pageConfig: { id: 'dashboard' } });
+  mockGetPageJitEnrichment.mockReturnValueOnce({
+    jsEntries: 'export default {};',
+    dynamicIcons: { Zap: { node: [['path', { d: 'M0 0' }]] } },
+  });
+  const res = await createApp().request('/api/page/dashboard');
+  expect(res.status).toEqual(200);
+  const body = await res.json();
+  expect(body.pageConfig).toEqual({
+    id: 'dashboard',
+    _buildId: BUILD_A,
+    _jsEntries: 'export default {};',
+    _dynamicIcons: { Zap: { node: [['path', { d: 'M0 0' }]] } },
+  });
+});
+
+test('jitPageHandler reads the enrichment from the context the page was built on', async () => {
+  const pageConfig = { id: 'dashboard' };
+  mockGetPageConfig.mockResolvedValue({ status: 'ok', pageConfig });
+  await createApp().request('/api/page/dashboard');
+  expect(mockGetPageJitEnrichment).toHaveBeenLastCalledWith({
+    pageConfig,
+    buildContext: mockBuildContext,
+  });
+});
+
+test('jitPageHandler names the build it served, and the recording route keeps that build after a rebuild', async () => {
+  const configDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-jit-page-build-'));
+  process.env.LOWDEFY_DIRECTORY_CONFIG = configDirectory;
+  try {
+    mockGetPageConfig.mockResolvedValue({ status: 'ok', pageConfig: { id: 'dashboard' } });
+    const app = createApp();
+    const { pageConfig: page } = await (await app.request('/api/page/dashboard')).json();
+    expect(page._buildId).toBe(BUILD_A);
+    expect(servedBuilds.has(BUILD_A)).toBe(true);
+
+    mockBuildId = BUILD_B;
+    const session = '20261003T140311Z-k3x9qa';
+    const res = await app.request('/api/dev-recording', {
+      method: 'POST',
+      headers: {
+        host: 'localhost:3001',
+        origin: 'http://localhost:3001',
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({
+        session,
+        records: [
+          {
+            v: 1,
+            session,
+            t: '2026-10-03T14:04:00.000Z',
+            kind: 'click',
+            scope: 'page',
+            page_id: 'dashboard',
+            event: null,
+            build: page._buildId,
+          },
+        ],
+      }),
+    });
+    expect(res.status).toBe(204);
+    const file = path.join(
+      configDirectory,
+      '.lowdefy',
+      'traces',
+      'dev',
+      '2026-10-03',
+      `${session}.jsonl`
+    );
+    expect(JSON.parse(fs.readFileSync(file, 'utf8').trim()).build).toBe(BUILD_A);
+  } finally {
+    fs.rmSync(configDirectory, { recursive: true, force: true });
+    delete process.env.LOWDEFY_DIRECTORY_CONFIG;
+  }
+});

package/src/routes/mcp.js

@@ -15,17 +15,94 @@
 */
 
 import { StreamableHTTPTransport } from '@hono/mcp';
-import { createMcpServer } from '@lowdefy/api';
+import { createMcpServer, getMcpResourceMetadataUri, getMcpResourceUri } from '@lowdefy/api';
+import { type } from '@lowdefy/helpers';
+
+import authJson from '../../lib/build/auth.js';
+import normalizeMcpProtocolVersionHeader from './normalizeMcpProtocolVersionHeader.js';
+
+// The RFC 6750 challenge for the MCP resource, pointing at its RFC 9728
+// metadata. The invalid_token extension exists for the two failures a client
+// can act on: BetterAuth mints opaque tokens when a client omits the RFC 8707
+// resource parameter, and those can never verify here - the description names
+// the parameter, never app state. A revoked grant (the member switched
+// organization or disconnected the assistant) is told to reconnect, which
+// re-runs the authorization and its organization choice. A refused member
+// token gets its reason and no resource_metadata: a script cannot sign in, so
+// pointing it at the authorization server would only mislead it.
+function getChallengeHeader({ context, description, memberToken, parseableJwt, revoked }) {
+  if (memberToken === true) {
+    return `Bearer error="invalid_token", error_description="${description}"`;
+  }
+  const metadataUri = getMcpResourceMetadataUri({ config: context.config });
+  if (parseableJwt === false) {
+    return `Bearer error="invalid_token", error_description="The access token is not a JWT. Connect with a client that sends the RFC 8707 resource parameter.", resource_metadata="${metadataUri}"`;
+  }
+  if (revoked === true) {
+    return `Bearer error="invalid_token", error_description="This connection was disconnected. Reconnect to choose the organization to work in.", resource_metadata="${metadataUri}"`;
+  }
+  return `Bearer resource_metadata="${metadataUri}"`;
+}
+
+// Browser cross-site defence: an Origin that is neither the pinned canonical
+// origin nor one the app registered on BetterAuth's trustedOrigins is
+// refused. Non-browser MCP clients send no Origin and pass.
+function isOriginAllowed({ c, context }) {
+  const origin = c.req.header('origin');
+  if (type.isNone(origin)) {
+    return true;
+  }
+  const canonicalOrigin = new URL(getMcpResourceUri({ config: context.config })).origin;
+  if (origin === canonicalOrigin) {
+    return true;
+  }
+  // Exact strings only - a trustedOrigins function or wildcard entry is not
+  // consulted here.
+  const trustedOrigins = context.auth?.options?.trustedOrigins;
+  return type.isArray(trustedOrigins) && trustedOrigins.includes(origin);
+}
 
 // Stateless per-request MCP server over the app's configured endpoints. The
-// apiContext middleware has already resolved the caller's session, so tool
-// listing and calls are authorized per request.
+// apiContext middleware has already resolved the caller from the bearer token
+// (context.mcpAuth), so tool listing and calls are authorized per request.
+//
+// The 401 challenge is decided here, before the transport runs -
+// transport.handleRequest writes tool results over HTTP 200, so past this
+// boundary a role or scope shortfall stays opaque inside the tool surface,
+// never a 403 or insufficient_scope.
 async function mcpHandler(c) {
+  normalizeMcpProtocolVersionHeader({ request: c.req.raw });
   const context = c.get('lowdefyContext');
-  const server = await createMcpServer({ context });
-  if (!server) {
+  const mcpConfig = await context.readConfigFile('mcp.json');
+  if (type.isNone(mcpConfig) || mcpConfig.configured !== true) {
     return c.json({ error: 'MCP is not configured.' }, 404);
   }
+  // Without an authorization server the build guaranteed an all-public tool
+  // surface, so the route serves openly - no challenge envelope at all.
+  if (!type.isNone(authJson.oauthProvider)) {
+    if (!isOriginAllowed({ c, context })) {
+      return c.json({ error: 'Origin not allowed.' }, 403);
+    }
+    const { tokenStatus, description, memberToken, parseableJwt, revoked } = context.mcpAuth ?? {};
+    if (tokenStatus === 'invalid') {
+      return c.json({ error: 'Unauthorized.' }, 401, {
+        'WWW-Authenticate': getChallengeHeader({
+          context,
+          description,
+          memberToken,
+          parseableJwt,
+          revoked,
+        }),
+      });
+    }
+    // Nothing to serve anonymously - challenge instead of an empty tool list.
+    if (tokenStatus === 'none' && mcpConfig.hasPublicTool === false) {
+      return c.json({ error: 'Unauthorized.' }, 401, {
+        'WWW-Authenticate': getChallengeHeader({ context, parseableJwt: true }),
+      });
+    }
+  }
+  const server = await createMcpServer({ context });
   const transport = new StreamableHTTPTransport();
   await server.connect(transport);
   return transport.handleRequest(c);