@lowdefy/server 6.1.0 → 7.0.0

package/src/routes/detached.js

@@ -14,23 +14,34 @@
   limitations under the License.
 */
 
-import { runDetachedEndpoint } from '@lowdefy/api';
+import { acceptDetachedEndpoint, parseRequestBody } from '@lowdefy/api';
 
 import getPathSegments from '../lib/getPathSegments.js';
 
 // Target of a CallApi step with `detached: true`: the calling invocation
 // fire-and-forgets a POST here, so the endpoint runs in its OWN function
 // invocation with a fresh duration budget (chainable bounded work without a
-// queue). Same transport auth as cron (CRON_SECRET, fails closed) and the same
-// system execution context — InternalApi endpoints are callable, `_user` is
-// undefined. Delivery is at-most-once with no retry: targets must be
-// idempotent.
+// queue). Transport auth is CRON_SECRET (fails closed), which proves the
+// request originated from the deployment. The run carries the DISPATCHER'S
+// identity (Decision 4): the request body carries a server-built principal
+// snapshot that runDetachedEndpoint rehydrates, so nested calls authorize
+// against the dispatcher, not a forced system context. Delivery is at-most-once
+// with no retry: targets must be idempotent.
+//
+// The route answers 202 as soon as the call is authorized and parsed; the
+// endpoint runs after the response under this invocation's waitUntil
+// (acceptDetachedEndpoint). The dispatcher is therefore released at once
+// instead of staying alive - and billed - until the target's routine ends.
 async function detachedHandler(c) {
   if (c.req.method !== 'POST') {
-    throw new Error('Only POST requests are supported.');
+    // A wrong-method request is client-caused: answer 405 rather than raising a
+    // fault that would be logged at error level and answered with a 500.
+    return c.json({ error: 'Method not allowed.' }, 405);
   }
   const context = c.get('lowdefyContext');
 
+  // The secret gate stays first: an external POST without the secret is
+  // rejected before the body (and its principal assertion) is ever read.
   const secret = process.env.CRON_SECRET;
   if (!secret || c.req.header('authorization') !== `Bearer ${secret}`) {
     context.logger.warn({ event: 'detached_unauthorized' });
@@ -38,10 +49,12 @@ async function detachedHandler(c) {
   }
 
   const endpointId = getPathSegments(c, '/api/detached/').join('/');
-  const { payload } = await c.req.json();
+  const { credentials, payload, principal } = parseRequestBody({ text: await c.req.text() });
   context.logger.info({ event: 'call_detached_endpoint', endpointId });
-  const response = await runDetachedEndpoint(context, { endpointId, payload });
-  return c.json(response);
+  return c.json(
+    acceptDetachedEndpoint(context, { credentials, endpointId, payload, principal }),
+    202
+  );
 }
 
 export default detachedHandler;

package/src/routes/endpoints.js

@@ -14,55 +14,56 @@
   limitations under the License.
 */
 
-import { callEndpoint, getEndpointConfig, runWebhookEndpoint } from '@lowdefy/api';
+import {
+  callEndpoint,
+  getEndpointConfig,
+  parseRequestBody,
+  runWebhookEndpoint,
+} from '@lowdefy/api';
 
 import getPathSegments from '../lib/getPathSegments.js';
 
 async function endpointsHandler(c) {
   if (c.req.method !== 'POST') {
-    throw new Error('Only POST requests are supported.');
+    // A wrong-method request is client-caused: answer 405 rather than raising a
+    // fault that would be logged at error level and answered with a 500.
+    return c.json({ error: 'Method not allowed.' }, 405);
   }
   const context = c.get('lowdefyContext');
   const endpointId = getPathSegments(c, '/api/endpoints/').join('/');
 
-  // Endpoints opting in with `webhook: true` are third-party webhook receivers
-  // (SNS, Event Grid, Stripe, ...): they take the request RAW — body in the
-  // caller's own format (not the { payload } envelope), plus query + headers —
-  // and their return value is sent back verbatim, because webhook handshakes
-  // (e.g. Event Grid's validationResponse) require exact response shapes.
-  // The config lookup is a cached file read; an unknown endpoint falls through
-  // to the standard path so its error shape is unchanged. Everything about
-  // non-webhook endpoints is untouched.
+  // Endpoints opting in with `webhook` (true or a { verify } object) are
+  // third-party webhook receivers (SNS, Event Grid, Stripe, ...): they take the
+  // request RAW — body in the caller's own format (not the { payload }
+  // envelope), plus query + headers — and their return value is sent back
+  // verbatim, because webhook handshakes (e.g. Event Grid's validationResponse)
+  // require exact response shapes. The config lookup is a cached file read; an
+  // unknown endpoint falls through to the standard path so its error shape is
+  // unchanged. Everything about non-webhook endpoints is untouched.
   let endpointConfig = null;
   try {
     endpointConfig = await getEndpointConfig(context, { endpointId });
   } catch {
     /* unknown endpoint — the standard path below reports it exactly as before */
   }
-  if (endpointConfig?.webhook === true) {
-    // SNS posts JSON as text/plain — parse regardless of content-type; an
-    // unparseable body arrives as the raw string.
-    const raw = await c.req.text();
-    let body = raw;
-    try {
-      body = JSON.parse(raw);
-    } catch {
-      /* non-JSON body — raw string passthrough */
-    }
+  if (endpointConfig?.webhook) {
     context.logger.info({ event: 'call_webhook_endpoint', endpointId });
-    const result = await runWebhookEndpoint(context, {
+    const { status, body, contentType } = await runWebhookEndpoint(context, {
       endpointId,
-      body,
+      rawBody: await c.req.text(),
       query: c.req.query(),
       headers: c.req.header(),
     });
-    if (!result.success) {
-      return c.json({ error: 'Webhook failed.' }, 500);
+    if (contentType === 'text/plain') {
+      // A text answer often echoes a value from the request (a handshake token), so the browser
+      // must not sniff it into HTML.
+      c.header('X-Content-Type-Options', 'nosniff');
+      return c.text(body, status);
     }
-    return c.json(result.response ?? { ok: true });
+    return c.json(body, status);
   }
 
-  const { blockId, payload, pageId } = await c.req.json();
+  const { blockId, payload, pageId } = parseRequestBody({ text: await c.req.text() });
   context.logger.info({ event: 'call_api_endpoint', blockId, endpointId, pageId });
   const response = await callEndpoint(context, { blockId, endpointId, pageId, payload });
   return c.json(response);

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/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);

package/src/routes/mcp.test.mjs

@@ -0,0 +1,215 @@
+/*
+  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';
+
+// The real URI helpers drive the challenge strings, so the header assertions
+// below exercise the actual BETTER_AUTH_URL derivation - only createMcpServer
+// is stubbed out.
+const uriHelpers = await import('@lowdefy/api/routes/mcp/getMcpUri.js');
+
+const mockCreateMcpServer = jest.fn();
+jest.unstable_mockModule('@lowdefy/api', () => ({
+  ...uriHelpers,
+  createMcpServer: mockCreateMcpServer,
+}));
+
+jest.unstable_mockModule('@hono/mcp', () => ({
+  StreamableHTTPTransport: class {
+    handleRequest() {
+      return new Response(JSON.stringify({ served: true }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      });
+    }
+  },
+}));
+
+const mockAuthJson = { configured: true, oauthProvider: { consentPage: '/oauth/consent' } };
+jest.unstable_mockModule('../../lib/build/auth.js', () => ({
+  default: mockAuthJson,
+}));
+
+const { default: mcpHandler } = await import('./mcp.js');
+
+const originalBetterAuthUrl = process.env.BETTER_AUTH_URL;
+
+const mockReadConfigFile = jest.fn();
+
+let contextOverrides;
+
+function createApp() {
+  const app = new Hono();
+  app.use('*', async (c, next) => {
+    c.set('lowdefyContext', {
+      config: { basePath: '' },
+      logger: { debug: jest.fn(), info: jest.fn(), warn: jest.fn(), error: jest.fn() },
+      readConfigFile: mockReadConfigFile,
+      ...contextOverrides,
+    });
+    await next();
+  });
+  app.all('/api/mcp', mcpHandler);
+  return app;
+}
+
+beforeEach(() => {
+  process.env.BETTER_AUTH_URL = 'https://app.test.com';
+  mockAuthJson.oauthProvider = { consentPage: '/oauth/consent' };
+  contextOverrides = {};
+  mockReadConfigFile.mockReset();
+  mockCreateMcpServer.mockReset();
+  mockCreateMcpServer.mockResolvedValue({ connect: jest.fn() });
+  mockReadConfigFile.mockResolvedValue({ configured: true, hasPublicTool: true, endpoints: [] });
+});
+
+afterAll(() => {
+  if (originalBetterAuthUrl === undefined) {
+    delete process.env.BETTER_AUTH_URL;
+  } else {
+    process.env.BETTER_AUTH_URL = originalBetterAuthUrl;
+  }
+});
+
+test('mcpHandler returns 404 when mcp is not configured', async () => {
+  mockReadConfigFile.mockResolvedValue({ configured: false });
+  const res = await createApp().request('/api/mcp', { method: 'POST' });
+  expect(res.status).toEqual(404);
+  expect(await res.json()).toEqual({ error: 'MCP is not configured.' });
+  expect(mockCreateMcpServer).not.toHaveBeenCalled();
+});
+
+test('mcpHandler challenges an invalid token with the resource metadata pointer', async () => {
+  contextOverrides.mcpAuth = { tokenStatus: 'invalid', parseableJwt: true };
+  const res = await createApp().request('/api/mcp', { method: 'POST' });
+  expect(res.status).toEqual(401);
+  expect(res.headers.get('WWW-Authenticate')).toEqual(
+    'Bearer resource_metadata="https://app.test.com/.well-known/oauth-protected-resource/api/mcp"'
+  );
+  expect(mockCreateMcpServer).not.toHaveBeenCalled();
+});
+
+test('mcpHandler extends the challenge with invalid_token when the bearer is not a JWT', async () => {
+  contextOverrides.mcpAuth = { tokenStatus: 'invalid', parseableJwt: false };
+  const res = await createApp().request('/api/mcp', { method: 'POST' });
+  expect(res.status).toEqual(401);
+  expect(res.headers.get('WWW-Authenticate')).toEqual(
+    '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="https://app.test.com/.well-known/oauth-protected-resource/api/mcp"'
+  );
+});
+
+test('mcpHandler tells a revoked grant to reconnect and choose an organization', async () => {
+  contextOverrides.mcpAuth = {
+    clientId: 'client_1',
+    organizationId: 'org_1',
+    tokenStatus: 'invalid',
+    parseableJwt: true,
+    revoked: true,
+  };
+  const res = await createApp().request('/api/mcp', { method: 'POST' });
+  expect(res.status).toEqual(401);
+  expect(res.headers.get('WWW-Authenticate')).toEqual(
+    'Bearer error="invalid_token", error_description="This connection was disconnected. Reconnect to choose the organization to work in.", resource_metadata="https://app.test.com/.well-known/oauth-protected-resource/api/mcp"'
+  );
+  expect(mockCreateMcpServer).not.toHaveBeenCalled();
+});
+
+test('mcpHandler gives a token without membership the same challenge as an invalid token', async () => {
+  contextOverrides.mcpAuth = {
+    clientId: 'client_1',
+    organizationId: 'org_1',
+    tokenStatus: 'invalid',
+    parseableJwt: true,
+    noMembership: true,
+  };
+  const res = await createApp().request('/api/mcp', { method: 'POST' });
+  expect(res.status).toEqual(401);
+  expect(res.headers.get('WWW-Authenticate')).toEqual(
+    'Bearer resource_metadata="https://app.test.com/.well-known/oauth-protected-resource/api/mcp"'
+  );
+  expect(mockCreateMcpServer).not.toHaveBeenCalled();
+});
+
+test('mcpHandler challenges an anonymous request when the surface has no public tool', async () => {
+  mockReadConfigFile.mockResolvedValue({ configured: true, hasPublicTool: false, endpoints: [] });
+  contextOverrides.mcpAuth = { tokenStatus: 'none', parseableJwt: true };
+  const res = await createApp().request('/api/mcp', { method: 'POST' });
+  expect(res.status).toEqual(401);
+  expect(res.headers.get('WWW-Authenticate')).toEqual(
+    'Bearer resource_metadata="https://app.test.com/.well-known/oauth-protected-resource/api/mcp"'
+  );
+});
+
+test('mcpHandler serves an anonymous request when the surface has a public tool', async () => {
+  contextOverrides.mcpAuth = { tokenStatus: 'none', parseableJwt: true };
+  const res = await createApp().request('/api/mcp', { method: 'POST' });
+  expect(res.status).toEqual(200);
+  expect(await res.json()).toEqual({ served: true });
+});
+
+test('mcpHandler serves a valid-token request and never challenges past the boundary', async () => {
+  mockReadConfigFile.mockResolvedValue({ configured: true, hasPublicTool: false, endpoints: [] });
+  contextOverrides.mcpAuth = {
+    tokenStatus: 'valid',
+    parseableJwt: true,
+    grantedScopes: ['mcp:read'],
+  };
+  const res = await createApp().request('/api/mcp', { method: 'POST' });
+  expect(res.status).toEqual(200);
+  expect(await res.json()).toEqual({ served: true });
+});
+
+test('mcpHandler refuses a foreign Origin with a 403', async () => {
+  contextOverrides.mcpAuth = { tokenStatus: 'none', parseableJwt: true };
+  const res = await createApp().request('/api/mcp', {
+    method: 'POST',
+    headers: { Origin: 'https://evil.test' },
+  });
+  expect(res.status).toEqual(403);
+  expect(await res.json()).toEqual({ error: 'Origin not allowed.' });
+  expect(mockCreateMcpServer).not.toHaveBeenCalled();
+});
+
+test('mcpHandler accepts the pinned canonical origin', async () => {
+  contextOverrides.mcpAuth = { tokenStatus: 'none', parseableJwt: true };
+  const res = await createApp().request('/api/mcp', {
+    method: 'POST',
+    headers: { Origin: 'https://app.test.com' },
+  });
+  expect(res.status).toEqual(200);
+});
+
+test('mcpHandler accepts an origin registered on BetterAuth trustedOrigins', async () => {
+  contextOverrides.mcpAuth = { tokenStatus: 'none', parseableJwt: true };
+  contextOverrides.auth = { options: { trustedOrigins: ['https://studio.test.com'] } };
+  const res = await createApp().request('/api/mcp', {
+    method: 'POST',
+    headers: { Origin: 'https://studio.test.com' },
+  });
+  expect(res.status).toEqual(200);
+});
+
+test('mcpHandler serves openly with no envelope when oauthProvider is not configured', async () => {
+  delete mockAuthJson.oauthProvider;
+  contextOverrides.mcpAuth = { tokenStatus: 'invalid', parseableJwt: false };
+  const res = await createApp().request('/api/mcp', {
+    method: 'POST',
+    headers: { Origin: 'https://evil.test' },
+  });
+  expect(res.status).toEqual(200);
+  expect(await res.json()).toEqual({ served: true });
+});

package/src/routes/mcpMemberToken.test.mjs

@@ -0,0 +1,125 @@
+/*
+  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';
+
+// The real URI helpers drive the challenge strings, so the header assertions
+// below exercise the actual BETTER_AUTH_URL derivation - only createMcpServer
+// is stubbed out.
+const uriHelpers = await import('@lowdefy/api/routes/mcp/getMcpUri.js');
+
+const mockCreateMcpServer = jest.fn();
+jest.unstable_mockModule('@lowdefy/api', () => ({
+  ...uriHelpers,
+  createMcpServer: mockCreateMcpServer,
+}));
+
+jest.unstable_mockModule('@hono/mcp', () => ({
+  StreamableHTTPTransport: class {
+    handleRequest() {
+      return new Response(JSON.stringify({ served: true }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      });
+    }
+  },
+}));
+
+const mockAuthJson = { configured: true, oauthProvider: { consentPage: '/oauth/consent' } };
+jest.unstable_mockModule('../../lib/build/auth.js', () => ({
+  default: mockAuthJson,
+}));
+
+const { default: mcpHandler } = await import('./mcp.js');
+
+const originalBetterAuthUrl = process.env.BETTER_AUTH_URL;
+
+const mockReadConfigFile = jest.fn();
+
+let contextOverrides;
+
+function createApp() {
+  const app = new Hono();
+  app.use('*', async (c, next) => {
+    c.set('lowdefyContext', {
+      config: { basePath: '' },
+      logger: { debug: jest.fn(), info: jest.fn(), warn: jest.fn(), error: jest.fn() },
+      readConfigFile: mockReadConfigFile,
+      ...contextOverrides,
+    });
+    await next();
+  });
+  app.all('/api/mcp', mcpHandler);
+  return app;
+}
+
+beforeEach(() => {
+  process.env.BETTER_AUTH_URL = 'https://app.test.com';
+  mockAuthJson.oauthProvider = { consentPage: '/oauth/consent' };
+  contextOverrides = {};
+  mockReadConfigFile.mockReset();
+  mockCreateMcpServer.mockReset();
+  mockCreateMcpServer.mockResolvedValue({ connect: jest.fn() });
+  mockReadConfigFile.mockResolvedValue({ configured: true, hasPublicTool: true, endpoints: [] });
+});
+
+afterAll(() => {
+  if (originalBetterAuthUrl === undefined) {
+    delete process.env.BETTER_AUTH_URL;
+  } else {
+    process.env.BETTER_AUTH_URL = originalBetterAuthUrl;
+  }
+});
+
+test('mcpHandler answers a refused member token with its reason and no resource metadata', async () => {
+  contextOverrides.mcpAuth = {
+    tokenStatus: 'invalid',
+    memberToken: true,
+    description: 'This token has expired.',
+  };
+  const res = await createApp().request('/api/mcp', { method: 'POST' });
+  expect(res.status).toEqual(401);
+  expect(res.headers.get('WWW-Authenticate')).toEqual(
+    'Bearer error="invalid_token", error_description="This token has expired."'
+  );
+  expect(mockCreateMcpServer).not.toHaveBeenCalled();
+});
+
+test('mcpHandler answers a member token whose member is gone with that reason', async () => {
+  contextOverrides.mcpAuth = {
+    tokenStatus: 'invalid',
+    memberToken: true,
+    description: "This token's member can no longer use it.",
+  };
+  const res = await createApp().request('/api/mcp', { method: 'POST' });
+  expect(res.status).toEqual(401);
+  expect(res.headers.get('WWW-Authenticate')).toEqual(
+    'Bearer error="invalid_token", error_description="This token\'s member can no longer use it."'
+  );
+});
+
+test('mcpHandler serves a valid member token caller', async () => {
+  contextOverrides.mcpAuth = {
+    tokenStatus: 'valid',
+    tokenId: 'token_1',
+    organizationId: 'org_1',
+    grantedScopes: ['mcp:read', 'mcp:write'],
+  };
+  const res = await createApp().request('/api/mcp', { method: 'POST' });
+  expect(res.status).toEqual(200);
+  expect(mockCreateMcpServer).toHaveBeenCalledTimes(1);
+});