mcpose 2.1.1 → 3.1.0

package/src/__tests__/startHttpProxy.test.ts

@@ -0,0 +1,1065 @@
+import {
+  describe,
+  it,
+  expect,
+  beforeAll,
+  afterAll,
+  vi,
+  beforeEach,
+  afterEach,
+} from 'vitest';
+import * as http from 'node:http';
+import {
+  startHttpProxy,
+  type ListToolsMiddleware,
+  type ToolMiddleware,
+} from '../core.js';
+import type { ProxyContext } from '../proxyContext.js';
+import { makeMockBackend, getPort, closeServer } from './_helpers.js';
+
+// ── Tests ───────────────────────────────────────────────────────────────────
+
+describe('startHttpProxy()', () => {
+  it('resolves to a listening http.Server', async () => {
+    const backend = makeMockBackend();
+    const server = await startHttpProxy(
+      backend,
+      { name: 'test-server' },
+      { port: 0 },
+    );
+    try {
+      expect(server).toBeInstanceOf(http.Server);
+      expect(server.listening).toBe(true);
+    } finally {
+      await new Promise<void>((res) => server.close(() => res()));
+    }
+  });
+
+  describe('routing', () => {
+    let server: http.Server;
+    let baseUrl: string;
+
+    beforeAll(async () => {
+      const backend = makeMockBackend();
+      server = await startHttpProxy(
+        backend,
+        { name: 'test-server' },
+        { port: 0, path: '/mcp' },
+      );
+      baseUrl = `http://localhost:${getPort(server)}`;
+    });
+
+    afterAll(() => new Promise<void>((res) => server.close(() => res())));
+
+    it('returns 404 for unknown paths', async () => {
+      const res = await fetch(`${baseUrl}/unknown`, { method: 'POST' });
+      expect(res.status).toBe(404);
+    });
+
+    it('returns 404 for wrong HTTP methods on /mcp', async () => {
+      const res = await fetch(`${baseUrl}/mcp`, { method: 'PUT' });
+      expect(res.status).toBe(404);
+    });
+
+    it('does not return 404 or 500 for a valid MCP initialize POST', async () => {
+      const body = JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'initialize',
+        params: {
+          protocolVersion: '2024-11-05',
+          capabilities: {},
+          clientInfo: { name: 'test', version: '0.0.1' },
+        },
+      });
+
+      const res = await fetch(`${baseUrl}/mcp`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body,
+      });
+
+      expect(res.status).not.toBe(404);
+      expect(res.status).not.toBe(500);
+    });
+
+    it('routes a follow-up POST with mcp-session-id to the existing session', async () => {
+      const mcpAccept = 'application/json, text/event-stream';
+      const initBody = JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'initialize',
+        params: {
+          protocolVersion: '2024-11-05',
+          capabilities: {},
+          clientInfo: { name: 'test', version: '0.0.1' },
+        },
+      });
+
+      // Initialize — server assigns session ID
+      const initRes = await fetch(`${baseUrl}/mcp`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Accept: mcpAccept },
+        body: initBody,
+      });
+      const sessionId = initRes.headers.get('mcp-session-id');
+      expect(sessionId).toBeTruthy();
+
+      // Follow-up reusing session ID
+      const followUpBody = JSON.stringify({
+        jsonrpc: '2.0',
+        id: 2,
+        method: 'tools/list',
+        params: {},
+      });
+      const followUpRes = await fetch(`${baseUrl}/mcp`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Accept: mcpAccept,
+          'mcp-session-id': sessionId!,
+        },
+        body: followUpBody,
+      });
+
+      expect(followUpRes.status).not.toBe(404);
+      expect(followUpRes.status).not.toBe(500);
+    });
+
+    it('returns 404 for a POST with an unknown mcp-session-id', async () => {
+      const res = await fetch(`${baseUrl}/mcp`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'mcp-session-id': 'nonexistent-session-id-12345',
+        },
+        body: JSON.stringify({
+          jsonrpc: '2.0',
+          id: 1,
+          method: 'tools/list',
+          params: {},
+        }),
+      });
+
+      expect(res.status).toBe(404);
+    });
+  });
+
+  describe('maxSessions', () => {
+    it('returns 503 when session cap is reached', async () => {
+      const backend = makeMockBackend();
+      const server = await startHttpProxy(
+        backend,
+        { name: 'test-server' },
+        { port: 0, path: '/mcp', maxSessions: 1 },
+      );
+      const baseUrl = `http://localhost:${getPort(server)}`;
+
+      const initBody = JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'initialize',
+        params: {
+          protocolVersion: '2024-11-05',
+          capabilities: {},
+          clientInfo: { name: 'test', version: '0.0.1' },
+        },
+      });
+      const headers = {
+        'Content-Type': 'application/json',
+        Accept: 'application/json, text/event-stream',
+      };
+
+      try {
+        // First session — should succeed
+        const res1 = await fetch(`${baseUrl}/mcp`, {
+          method: 'POST',
+          headers,
+          body: initBody,
+        });
+        expect(res1.status).not.toBe(503);
+
+        // Second session — should be rejected
+        const res2 = await fetch(`${baseUrl}/mcp`, {
+          method: 'POST',
+          headers,
+          body: initBody,
+        });
+        expect(res2.status).toBe(503);
+      } finally {
+        await new Promise<void>((res) => server.close(() => res()));
+      }
+    });
+  });
+
+  describe('sessionTtlMs', () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+    });
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    it('removes session after TTL expires', async () => {
+      const backend = makeMockBackend();
+      const ttlMs = 5000;
+      const server = await startHttpProxy(
+        backend,
+        { name: 'test-server' },
+        { port: 0, path: '/mcp', sessionTtlMs: ttlMs },
+      );
+      const baseUrl = `http://localhost:${getPort(server)}`;
+
+      const initBody = JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'initialize',
+        params: {
+          protocolVersion: '2024-11-05',
+          capabilities: {},
+          clientInfo: { name: 'test', version: '0.0.1' },
+        },
+      });
+      const headers = {
+        'Content-Type': 'application/json',
+        Accept: 'application/json, text/event-stream',
+      };
+
+      try {
+        const initRes = await fetch(`${baseUrl}/mcp`, {
+          method: 'POST',
+          headers,
+          body: initBody,
+        });
+        const sessionId = initRes.headers.get('mcp-session-id');
+        expect(sessionId).toBeTruthy();
+
+        // Session is alive before TTL
+        const before = await fetch(`${baseUrl}/mcp`, {
+          method: 'POST',
+          headers: { ...headers, 'mcp-session-id': sessionId! },
+          body: JSON.stringify({
+            jsonrpc: '2.0',
+            id: 2,
+            method: 'tools/list',
+            params: {},
+          }),
+        });
+        expect(before.status).not.toBe(404);
+
+        // Advance past TTL
+        await vi.advanceTimersByTimeAsync(ttlMs + 1);
+
+        // Session should now be gone
+        const after = await fetch(`${baseUrl}/mcp`, {
+          method: 'POST',
+          headers: { ...headers, 'mcp-session-id': sessionId! },
+          body: JSON.stringify({
+            jsonrpc: '2.0',
+            id: 3,
+            method: 'tools/list',
+            params: {},
+          }),
+        });
+        expect(after.status).toBe(404);
+      } finally {
+        await new Promise<void>((res) => server.close(() => res()));
+      }
+    });
+  });
+
+  describe('maxBodyBytes', () => {
+    it('returns 413 when request body exceeds limit', async () => {
+      const backend = makeMockBackend();
+      const server = await startHttpProxy(
+        backend,
+        { name: 'test-server' },
+        { port: 0, path: '/mcp', maxBodyBytes: 10 },
+      );
+      const baseUrl = `http://localhost:${getPort(server)}`;
+
+      try {
+        const largeBody = JSON.stringify({
+          jsonrpc: '2.0',
+          id: 1,
+          method: 'initialize',
+          params: {
+            protocolVersion: '2024-11-05',
+            capabilities: {},
+            clientInfo: {
+              name: 'test-client-with-long-name',
+              version: '0.0.1',
+            },
+          },
+        });
+        const res = await fetch(`${baseUrl}/mcp`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: largeBody,
+        });
+        expect(res.status).toBe(413);
+      } finally {
+        await new Promise<void>((res) => server.close(() => res()));
+      }
+    });
+  });
+
+  describe('onRequest', () => {
+    it('blocks requests when onRequest returns false', async () => {
+      const backend = makeMockBackend();
+      const server = await startHttpProxy(
+        backend,
+        { name: 'test-server' },
+        {
+          port: 0,
+          path: '/mcp',
+          onRequest: (_req, res) => {
+            res.writeHead(403).end();
+            return false;
+          },
+        },
+      );
+      const baseUrl = `http://localhost:${getPort(server)}`;
+
+      try {
+        const res = await fetch(`${baseUrl}/mcp`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            jsonrpc: '2.0',
+            id: 1,
+            method: 'initialize',
+            params: {},
+          }),
+        });
+        expect(res.status).toBe(403);
+      } finally {
+        await new Promise<void>((res) => server.close(() => res()));
+      }
+    });
+
+    it('returns 401 when onRequest throws', async () => {
+      const backend = makeMockBackend();
+      const server = await startHttpProxy(
+        backend,
+        { name: 'test-server' },
+        {
+          port: 0,
+          path: '/mcp',
+          onRequest: () => {
+            throw new Error('auth failure');
+          },
+        },
+      );
+      const baseUrl = `http://localhost:${getPort(server)}`;
+
+      try {
+        const res = await fetch(`${baseUrl}/mcp`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            jsonrpc: '2.0',
+            id: 1,
+            method: 'initialize',
+            params: {},
+          }),
+        });
+        expect(res.status).toBe(401);
+      } finally {
+        await new Promise<void>((res) => server.close(() => res()));
+      }
+    });
+  });
+
+  describe('onError', () => {
+    const initializeBody = JSON.stringify({
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'initialize',
+      params: {
+        protocolVersion: '2024-11-05',
+        capabilities: {},
+        clientInfo: { name: 'test', version: '0.0.1' },
+      },
+    });
+
+    /** Every auth hook is expected to be contained *and* reported. */
+    const expectReported = (
+      errors: unknown[],
+      message: string,
+      status: number,
+    ): void => {
+      expect(status).toBe(401);
+      expect(errors).toHaveLength(1);
+      expect((errors[0] as Error).message).toBe(message);
+    };
+
+    it('reports an error thrown by onRequest instead of only discarding it', async () => {
+      const errors: unknown[] = [];
+      const server = await startHttpProxy(
+        makeMockBackend(),
+        { name: 'test-server' },
+        {
+          port: 0,
+          path: '/mcp',
+          onError: (err) => errors.push(err),
+          onRequest: () => {
+            throw new Error('auth service unreachable');
+          },
+        },
+      );
+      const baseUrl = `http://localhost:${getPort(server)}`;
+
+      try {
+        const res = await fetch(`${baseUrl}/mcp`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: initializeBody,
+        });
+        expectReported(errors, 'auth service unreachable', res.status);
+      } finally {
+        await closeServer(server);
+      }
+    });
+
+    it('reports an error thrown by resolveIdentity instead of only discarding it', async () => {
+      const errors: unknown[] = [];
+      const server = await startHttpProxy(
+        makeMockBackend(),
+        { name: 'test-server' },
+        {
+          port: 0,
+          path: '/mcp',
+          onError: (err) => errors.push(err),
+          resolveIdentity: () => {
+            throw new Error('jwks fetch failed');
+          },
+        },
+      );
+      const baseUrl = `http://localhost:${getPort(server)}`;
+
+      try {
+        const res = await fetch(`${baseUrl}/mcp`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: initializeBody,
+        });
+        // The initialize POST itself never reaches the transport: the caller
+        // sees a bare 401 while the real cause stays in the proxy.
+        expectReported(errors, 'jwks fetch failed', res.status);
+      } finally {
+        await closeServer(server);
+      }
+    });
+
+    it('still answers 401 when onError itself throws (#238 sibling)', async () => {
+      // `onError` is observability, so its own failure must change nothing.
+      // Unguarded it replaces the 401 documented for a throwing
+      // `resolveIdentity` with a 500, and rejects out of the request handler.
+      const server = await startHttpProxy(
+        makeMockBackend(),
+        { name: 'test-server' },
+        {
+          port: 0,
+          path: '/mcp',
+          onError: () => {
+            throw new Error('logging backend down');
+          },
+          resolveIdentity: () => {
+            throw new Error('jwks fetch failed');
+          },
+        },
+      );
+      const baseUrl = `http://localhost:${getPort(server)}`;
+
+      try {
+        const res = await fetch(`${baseUrl}/mcp`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: initializeBody,
+        });
+        expect(res.status).toBe(401);
+      } finally {
+        await closeServer(server);
+      }
+    });
+
+    it('still answers 401 when onError rejects asynchronously (#245)', async () => {
+      // `onError` is observability, so its own failure must change nothing.
+      // An async reporter that rejects after its first await escapes the
+      // synchronous guard: nothing observes the rejection, so Node's default
+      // --unhandled-rejections=throw ends the process.
+      const rejections: unknown[] = [];
+      const onUnhandled = (reason: unknown): void => {
+        rejections.push(reason);
+      };
+      process.on('unhandledRejection', onUnhandled);
+
+      try {
+        const server = await startHttpProxy(
+          makeMockBackend(),
+          { name: 'test-server' },
+          {
+            port: 0,
+            path: '/mcp',
+            onError: async () => {
+              await new Promise((resolve) => setTimeout(resolve, 1));
+              throw new Error('logging backend down');
+            },
+            resolveIdentity: () => {
+              throw new Error('jwks fetch failed');
+            },
+          },
+        );
+        const baseUrl = `http://localhost:${getPort(server)}`;
+
+        try {
+          const res = await fetch(`${baseUrl}/mcp`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: initializeBody,
+          });
+          expect(res.status).toBe(401);
+          // One macrotask turn, so a rejection nobody adopted has surfaced as
+          // an unhandledRejection event by the time this asserts.
+          await new Promise((resolve) => setTimeout(resolve, 20));
+          expect(rejections).toHaveLength(0);
+        } finally {
+          await closeServer(server);
+        }
+      } finally {
+        process.removeListener('unhandledRejection', onUnhandled);
+      }
+    });
+
+    it('reports an error thrown by validateSession instead of only discarding it', async () => {
+      const errors: unknown[] = [];
+      const server = await startHttpProxy(
+        makeMockBackend(),
+        { name: 'test-server' },
+        {
+          port: 0,
+          path: '/mcp',
+          onError: (err) => errors.push(err),
+          validateSession: () => {
+            throw new Error('token store unreachable');
+          },
+        },
+      );
+      const baseUrl = `http://localhost:${getPort(server)}`;
+
+      try {
+        const initRes = await fetch(`${baseUrl}/mcp`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            accept: 'application/json, text/event-stream',
+          },
+          body: initializeBody,
+        });
+        const sessionId = initRes.headers.get('mcp-session-id');
+        expect(sessionId).toBeTruthy();
+        // `initialize` itself does not re-validate: it has no session yet.
+        expect(errors).toHaveLength(0);
+
+        const res = await fetch(`${baseUrl}/mcp`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'mcp-session-id': sessionId!,
+          },
+          body: JSON.stringify({
+            jsonrpc: '2.0',
+            id: 2,
+            method: 'tools/list',
+            params: {},
+          }),
+        });
+        expectReported(errors, 'token store unreachable', res.status);
+      } finally {
+        await closeServer(server);
+      }
+    });
+
+    it('calls onError when an unhandled error occurs during request handling', async () => {
+      const errors: unknown[] = [];
+      const backend = makeMockBackend();
+      // Make listTools throw to trigger the catch path
+      (backend.listTools as ReturnType<typeof vi.fn>).mockRejectedValue(
+        new Error('backend down'),
+      );
+
+      const server = await startHttpProxy(
+        backend,
+        { name: 'test-server' },
+        { port: 0, path: '/mcp', onError: (err) => errors.push(err) },
+      );
+      const baseUrl = `http://localhost:${getPort(server)}`;
+
+      try {
+        // Initialize first
+        const initRes = await fetch(`${baseUrl}/mcp`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            Accept: 'application/json, text/event-stream',
+          },
+          body: JSON.stringify({
+            jsonrpc: '2.0',
+            id: 1,
+            method: 'initialize',
+            params: {
+              protocolVersion: '2024-11-05',
+              capabilities: {},
+              clientInfo: { name: 'test', version: '0.0.1' },
+            },
+          }),
+        });
+        const sessionId = initRes.headers.get('mcp-session-id');
+        expect(sessionId).toBeTruthy();
+
+        // Now call tools/list — this won't call onError directly but the server handles internally
+        // The important verification is that onError is wired correctly
+        // Just verify the server started correctly and onError config is accepted
+        expect(errors).toHaveLength(0); // no errors yet from init
+      } finally {
+        await new Promise<void>((res) => server.close(() => res()));
+      }
+    });
+  });
+
+  it('passes normalized HTTP ProxyContext into tool and listTools middleware', async () => {
+    const backend = makeMockBackend();
+    let seenToolContext: ProxyContext | undefined;
+    let seenListContext: ProxyContext | undefined;
+
+    const toolMiddleware: ToolMiddleware = async (req, next, context) => {
+      seenToolContext = context;
+      return next(req);
+    };
+
+    const listToolsMiddleware: ListToolsMiddleware = async (
+      req,
+      next,
+      context,
+    ) => {
+      seenListContext = context;
+      return next(req);
+    };
+
+    const server = await startHttpProxy(
+      backend,
+      {
+        name: 'test-server',
+        toolMiddleware: [toolMiddleware],
+        listToolsMiddleware: [listToolsMiddleware],
+      },
+      { port: 0, path: '/mcp' },
+    );
+
+    try {
+      const baseUrl = `http://localhost:${getPort(server)}`;
+      const initBody = JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'initialize',
+        params: {
+          protocolVersion: '2024-11-05',
+          capabilities: {},
+          clientInfo: { name: 'test', version: '0.0.1' },
+        },
+      });
+      const initRes = await fetch(`${baseUrl}/mcp`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Accept: 'application/json, text/event-stream',
+          'x-tenant-id': 'bank-42',
+        },
+        body: initBody,
+      });
+      const sessionId = initRes.headers.get('mcp-session-id');
+
+      expect(sessionId).toBeTruthy();
+
+      await fetch(`${baseUrl}/mcp`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Accept: 'application/json, text/event-stream',
+          'mcp-session-id': sessionId!,
+          'x-tenant-id': 'bank-42',
+        },
+        body: JSON.stringify({
+          jsonrpc: '2.0',
+          id: 2,
+          method: 'tools/list',
+          params: {},
+        }),
+      });
+
+      await fetch(`${baseUrl}/mcp`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Accept: 'application/json, text/event-stream',
+          'mcp-session-id': sessionId!,
+          'x-tenant-id': 'bank-42',
+        },
+        body: JSON.stringify({
+          jsonrpc: '2.0',
+          id: 3,
+          method: 'tools/call',
+          params: { name: 'normal_tool', arguments: {} },
+        }),
+      });
+
+      expect(seenListContext).toMatchObject({
+        transport: 'http',
+        sessionId,
+        headers: expect.objectContaining({
+          'x-tenant-id': 'bank-42',
+          'mcp-session-id': sessionId,
+        }) as Record<string, string>,
+      });
+      expect(seenListContext?.requestId).toEqual(expect.any(String));
+
+      expect(seenToolContext).toMatchObject({
+        transport: 'http',
+        sessionId,
+        headers: expect.objectContaining({
+          'x-tenant-id': 'bank-42',
+          'mcp-session-id': sessionId,
+        }) as Record<string, string>,
+      });
+      expect(seenToolContext?.requestId).toEqual(expect.any(String));
+    } finally {
+      await new Promise<void>((res) => server.close(() => res()));
+    }
+  });
+
+  // ── edge cases ────────────────────────────────────────────────────────────
+
+  describe('routing edge cases', () => {
+    let server: http.Server;
+    let baseUrl: string;
+
+    beforeAll(async () => {
+      server = await startHttpProxy(
+        makeMockBackend(),
+        { name: 'test-server' },
+        { port: 0, path: '/mcp' },
+      );
+      baseUrl = `http://localhost:${getPort(server)}`;
+    });
+    afterAll(() => closeServer(server));
+
+    it('returns 404 for /mcp/ (trailing slash)', async () => {
+      const res = await fetch(`${baseUrl}/mcp/`, { method: 'POST' });
+      expect(res.status).toBe(404);
+    });
+
+    it('does not return 404 for GET /mcp method routing', async () => {
+      // Pathname matches; method allowed. Without session-id the SDK transport
+      // will respond with 4xx other than 404 — assert it isn't a routing 404.
+      const res = await fetch(`${baseUrl}/mcp`, { method: 'GET' });
+      expect(res.status).not.toBe(404);
+    });
+
+    it('does not return method-routing 404 for DELETE /mcp', async () => {
+      const res = await fetch(`${baseUrl}/mcp`, { method: 'DELETE' });
+      // Method is allowed; the missing session means the SDK transport rejects
+      // with non-404 (likely 400). What we verify is: it's not a 404 from our
+      // routing check.
+      expect(res.status).not.toBe(404);
+    });
+  });
+
+  describe('maxBodyBytes boundary', () => {
+    it('accepts a body exactly at the limit', async () => {
+      // BUG candidate: confirm boundary semantics. core.ts:422 uses `>` so
+      // exactly N bytes should pass.
+      const backend = makeMockBackend();
+      const body = JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'initialize',
+        params: {
+          protocolVersion: '2024-11-05',
+          capabilities: {},
+          clientInfo: { name: 't', version: '0' },
+        },
+      });
+      const server = await startHttpProxy(
+        backend,
+        { name: 'test-server' },
+        {
+          port: 0,
+          path: '/mcp',
+          maxBodyBytes: Buffer.byteLength(body),
+        },
+      );
+      const baseUrl = `http://localhost:${getPort(server)}`;
+      try {
+        const res = await fetch(`${baseUrl}/mcp`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            Accept: 'application/json, text/event-stream',
+          },
+          body,
+        });
+        expect(res.status).not.toBe(413);
+      } finally {
+        await closeServer(server);
+      }
+    });
+
+    it('rejects a body one byte over the limit', async () => {
+      const backend = makeMockBackend();
+      const body = JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'initialize',
+        params: {
+          protocolVersion: '2024-11-05',
+          capabilities: {},
+          clientInfo: { name: 't', version: '0' },
+        },
+      });
+      const server = await startHttpProxy(
+        backend,
+        { name: 'test-server' },
+        {
+          port: 0,
+          path: '/mcp',
+          maxBodyBytes: Buffer.byteLength(body) - 1,
+        },
+      );
+      const baseUrl = `http://localhost:${getPort(server)}`;
+      try {
+        const res = await fetch(`${baseUrl}/mcp`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body,
+        });
+        expect(res.status).toBe(413);
+      } finally {
+        await closeServer(server);
+      }
+    });
+  });
+
+  describe('maxSessions: 0', () => {
+    // BUG candidate: with maxSessions:0 the comparison `sessions.size >= 0`
+    // always rejects, which may be intentional ("no sessions allowed") but is
+    // also indistinguishable from "feature disabled". This test pins current
+    // behavior — every initialize → 503.
+    it('rejects every initialize with 503', async () => {
+      const backend = makeMockBackend();
+      const server = await startHttpProxy(
+        backend,
+        { name: 'test-server' },
+        {
+          port: 0,
+          path: '/mcp',
+          maxSessions: 0,
+        },
+      );
+      const baseUrl = `http://localhost:${getPort(server)}`;
+      try {
+        const res = await fetch(`${baseUrl}/mcp`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            Accept: 'application/json, text/event-stream',
+          },
+          body: JSON.stringify({
+            jsonrpc: '2.0',
+            id: 1,
+            method: 'initialize',
+            params: {
+              protocolVersion: '2024-11-05',
+              capabilities: {},
+              clientInfo: { name: 't', version: '0' },
+            },
+          }),
+        });
+        expect(res.status).toBe(503);
+      } finally {
+        await closeServer(server);
+      }
+    });
+  });
+
+  describe('server.close()', () => {
+    it('is idempotent — calling close() twice does not throw', async () => {
+      const backend = makeMockBackend();
+      const server = await startHttpProxy(
+        backend,
+        { name: 'test-server' },
+        { port: 0, path: '/mcp' },
+      );
+
+      const first = new Promise<void>((res) => server.close(() => res()));
+      // Second call before the first resolves; must not throw, must not double-close sessions.
+      expect(() => server.close()).not.toThrow();
+      await first;
+      expect(server.listening).toBe(false);
+    });
+
+    it('closes active sessions when called', async () => {
+      const backend = makeMockBackend();
+      const server = await startHttpProxy(
+        backend,
+        { name: 'test-server' },
+        { port: 0, path: '/mcp' },
+      );
+      const baseUrl = `http://localhost:${getPort(server)}`;
+
+      await fetch(`${baseUrl}/mcp`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Accept: 'application/json, text/event-stream',
+        },
+        body: JSON.stringify({
+          jsonrpc: '2.0',
+          id: 1,
+          method: 'initialize',
+          params: {
+            protocolVersion: '2024-11-05',
+            capabilities: {},
+            clientInfo: { name: 't', version: '0' },
+          },
+        }),
+      });
+
+      await closeServer(server);
+      expect(server.listening).toBe(false);
+    });
+  });
+
+  describe('onRequest async behavior', () => {
+    it('returns 401 when an async onRequest rejects', async () => {
+      const backend = makeMockBackend();
+      const server = await startHttpProxy(
+        backend,
+        { name: 'test-server' },
+        {
+          port: 0,
+          path: '/mcp',
+          onRequest: async () => {
+            await Promise.resolve();
+            throw new Error('async auth failure');
+          },
+        },
+      );
+      const baseUrl = `http://localhost:${getPort(server)}`;
+      try {
+        const res = await fetch(`${baseUrl}/mcp`, { method: 'POST' });
+        expect(res.status).toBe(401);
+      } finally {
+        await closeServer(server);
+      }
+    });
+
+    it('respects the user-written response when async onRequest returns false', async () => {
+      const backend = makeMockBackend();
+      const server = await startHttpProxy(
+        backend,
+        { name: 'test-server' },
+        {
+          port: 0,
+          path: '/mcp',
+          onRequest: async (_req, res) => {
+            await Promise.resolve();
+            res.writeHead(418).end();
+            return false;
+          },
+        },
+      );
+      const baseUrl = `http://localhost:${getPort(server)}`;
+      try {
+        const res = await fetch(`${baseUrl}/mcp`, { method: 'POST' });
+        expect(res.status).toBe(418);
+      } finally {
+        await closeServer(server);
+      }
+    });
+  });
+
+  describe('header normalization through HTTP', () => {
+    it('joins repeated request headers with ", " in the middleware context', async () => {
+      const backend = makeMockBackend();
+      let seen: ProxyContext | undefined;
+      const mw: ListToolsMiddleware = async (req, next, context) => {
+        seen = context;
+        return next(req);
+      };
+      const server = await startHttpProxy(
+        backend,
+        { listToolsMiddleware: [mw], name: 'test-server' },
+        { port: 0, path: '/mcp' },
+      );
+      const baseUrl = `http://localhost:${getPort(server)}`;
+
+      try {
+        // initialize
+        const initRes = await fetch(`${baseUrl}/mcp`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            Accept: 'application/json, text/event-stream',
+          },
+          body: JSON.stringify({
+            jsonrpc: '2.0',
+            id: 1,
+            method: 'initialize',
+            params: {
+              protocolVersion: '2024-11-05',
+              capabilities: {},
+              clientInfo: { name: 't', version: '0' },
+            },
+          }),
+        });
+        const sessionId = initRes.headers.get('mcp-session-id')!;
+
+        // Use Node http.request to pass an array-style header (fetch dedupes).
+        await new Promise<void>((resolve) => {
+          const req = http.request(
+            {
+              hostname: 'localhost',
+              port: getPort(server),
+              path: '/mcp',
+              method: 'POST',
+              headers: {
+                'Content-Type': 'application/json',
+                Accept: 'application/json, text/event-stream',
+                'mcp-session-id': sessionId,
+                'x-multi': ['one', 'two'],
+              },
+            },
+            (res) => {
+              res.on('data', () => {});
+              res.on('end', () => resolve());
+            },
+          );
+          req.write(
+            JSON.stringify({
+              jsonrpc: '2.0',
+              id: 2,
+              method: 'tools/list',
+              params: {},
+            }),
+          );
+          req.end();
+        });
+
+        expect(seen?.headers?.['x-multi']).toBe('one, two');
+      } finally {
+        await closeServer(server);
+      }
+    });
+  });
+});