fa-mcp-sdk 0.4.142 → 0.11.2

package/dist/core/web/server-http.js

@@ -1,7 +1,10 @@
+import { randomUUID } from 'node:crypto';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
-import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { InMemoryEventStore } from './event-store.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, isInitializeRequest, } from '@modelcontextprotocol/sdk/types.js';
 import chalk from 'chalk';
 import express from 'express';
 import helmet from 'helmet';
@@ -10,24 +13,28 @@ import { createAgentTesterRouter } from '../agent-tester/agent-tester-router.js'
 import { validateAdminAuthConfig } from '../auth/admin-auth.js';
 import { createAgentTesterSessionMW } from '../auth/agent-tester-auth.js';
 import { checkJwtToken, generateToken, MIN_ENCRYPT_KEY_LENGTH } from '../auth/jwt.js';
+import { canLocallyIssueJwt, getJwtRuntimeConfig } from '../auth/key-resolver.js';
 import { createAuthMW } from '../auth/middleware.js';
 import { checkPermanentToken } from '../auth/permanent.js';
 import { appConfig, getProjectData } from '../bootstrap/init-config.js';
-import { debugMcpNotification } from '../debug.js';
 import { getMainDBConnectionStatus } from '../db/pg-db.js';
-import { BaseMcpError } from '../errors/BaseMcpError.js';
 import { createJsonRpcErrorResponse, ServerError, toError, toStr } from '../errors/errors.js';
+import { PayloadTooLargeError, RateLimitedError, ResourceNotFoundError, TimeoutError, } from '../errors/specific-errors.js';
 import { logger as lgr } from '../logger.js';
+import { getMetrics, getMetricsRegistry, initMetrics } from '../metrics/metrics.js';
 import { createMcpServer } from '../mcp/create-mcp-server.js';
-import { getPrompt, getPromptsList } from '../mcp/prompts.js';
+import { getPromptsList } from '../mcp/prompts.js';
 import { getResource, getResourcesList } from '../mcp/resources.js';
+import { truncateToolResponse, withToolTimeout } from '../mcp/tool-limits.js';
 import { formatRateLimitError, isRateLimitError } from '../utils/rate-limit.js';
 import { getTools, normalizeHeaders } from '../utils/utils.js';
 import { createAdminRouter } from './admin-router.js';
 import { applyCors } from './cors.js';
 import { faviconSvg } from './favicon-svg.js';
 import { handleHomeInfo } from './home-api.js';
+import { createOAuthRouter } from './oauth-router.js';
 import { configureOpenAPI, createSwaggerUIAssetsMiddleware } from './openapi.js';
+import { requestIdMW } from './request-id.js';
 import { createSvgRouter } from './svg-icons.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -35,6 +42,26 @@ const __dirname = dirname(__filename);
 const staticPath = join(__dirname, 'static');
 const logger = lgr.getSubLogger({ name: chalk.bgYellow('server-http') });
 export const isAdminEnabled = appConfig.adminPanel?.enabled === true;
+/**
+ * Standard §14 — pick the rate-limit bucket key from the request:
+ *   - `scope: 'subject'` → JWT `sub`/`user` claim, falling back to req.ip when no auth payload
+ *   - `scope: 'ip'`      → req.ip / unknown
+ */
+function resolveRateLimitKey(req, suffix = '') {
+    const scope = appConfig.mcp.rateLimit?.scope ?? 'subject';
+    let key = '';
+    if (scope === 'subject') {
+        const payload = req.auth?.payload ?? req.authInfo?.payload;
+        const sub = payload?.sub ?? payload?.user ?? req.authInfo?.username;
+        if (sub && String(sub).trim()) {
+            key = `sub:${String(sub).trim().toLowerCase()}`;
+        }
+    }
+    if (!key) {
+        key = `ip:${req.ip || 'unknown'}`;
+    }
+    return suffix ? `${suffix}-${key}` : key;
+}
 /**
  * Handle rate limiting with consistent error response
  */
@@ -46,19 +73,19 @@ async function handleRateLimit(rateLimiter, clientId, ip, context = '', res, id)
         if (isRateLimitError(rateLimitError)) {
             const rateLimitMessage = formatRateLimitError(rateLimitError, appConfig.mcp.rateLimit.maxRequests);
             logger.warn(`Rate limit exceeded${context ? ` in ${context}` : ''}: ip: ${ip}`);
+            const scope = (appConfig.mcp.rateLimit?.scope ?? 'subject');
+            getMetrics()?.rateLimitHits.inc({ scope });
+            // Standard §14 + Appendix B: HTTP 429, JSON-RPC code -32003, `Retry-After` header in
+            // seconds (also mirrored under `error.data.retryAfter` per Appendix B.3).
+            const retryAfterSec = Math.max(1, Math.ceil((rateLimitError.msBeforeNext ?? 1000) / 1000));
+            const error = new RateLimitedError(rateLimitMessage, retryAfterSec);
             if (res) {
-                res.status(200).json({
-                    jsonrpc: '2.0',
-                    id: id ?? 1,
-                    error: {
-                        code: -32000,
-                        message: rateLimitMessage,
-                    },
-                });
+                res.setHeader('Retry-After', String(retryAfterSec));
+                res.status(error.statusCode).json(createJsonRpcErrorResponse(error, id ?? null));
                 return;
             }
             else {
-                throw new Error(rateLimitMessage, { cause: rateLimitError });
+                throw error;
             }
         }
         throw rateLimitError;
@@ -69,6 +96,11 @@ async function handleRateLimit(rateLimiter, clientId, ip, context = '', res, id)
  */
 export async function startHttpServer() {
     const app = express();
+    // Express `trust proxy`. Required for /.well-known/openid-configuration when the server
+    // sits behind HTTPS reverse proxy (X-Forwarded-Proto / X-Forwarded-Host).
+    if (appConfig.webServer.trustProxy !== undefined) {
+        app.set('trust proxy', appConfig.webServer.trustProxy);
+    }
     // Initialize rate limiter
     const rateLimiter = new RateLimiterMemory({
         keyPrefix: appConfig.shortName,
@@ -77,15 +109,34 @@ export async function startHttpServer() {
     });
     // Create universal auth middleware for all endpoints
     const authMW = createAuthMW();
+    // Standard §15.1 — sticky `X-Request-Id` (+ W3C traceparent/tracestate) MUST be installed
+    // before CORS, auth or any handler that may shortcut the chain — otherwise 401/403
+    // responses would land without a correlation id, breaking downstream debugging.
+    app.use(requestIdMW());
+    // Standard §15.3 — Prometheus metrics. Opt-in: enabled flag drives both `prom-client`
+    // registry initialisation and `GET /metrics` mounting below.
+    const metricsCfg = appConfig.webServer.metrics;
+    const metricsEnabled = metricsCfg?.enabled === true;
+    if (metricsEnabled) {
+        initMetrics();
+    }
     // Security middleware
     app.use(helmet({
         contentSecurityPolicy: false, // Allow for SSE
         crossOriginEmbedderPolicy: false,
     }));
-    // JSON parsing
-    app.use(express.json({ limit: '10mb' }));
-    app.use(express.urlencoded({ extended: true, limit: '10mb' }));
+    // JSON parsing. Body size is capped by `mcp.limits.maxPayloadBytes` (standard §14, default 1 MiB).
+    // Anything above is intercepted by the error-handling middleware below and converted to
+    // a JSON-RPC `-32005` / HTTP 413 response.
+    const { maxPayloadBytes } = appConfig.mcp.limits;
+    app.use(express.json({ limit: maxPayloadBytes }));
+    app.use(express.urlencoded({ extended: true, limit: maxPayloadBytes }));
     applyCors(app);
+    // OAuth discovery + token endpoints (mounted before auth MW so they remain public).
+    // Active only when jwtToken.mode !== 'legacyAesCtr'.
+    if (getJwtRuntimeConfig().mode !== 'legacyAesCtr') {
+        app.use(createOAuthRouter());
+    }
     app.use(faviconSvg());
     // Serve static files (CSS, JS, SVG)
     app.use('/static', express.static(staticPath));
@@ -97,12 +148,14 @@ export async function startHttpServer() {
     app.get('/', (req, res) => {
         res.sendFile(join(staticPath, 'home', 'index.html'));
     });
-    // Health check endpoint
+    // Health check endpoint. Standard §16.1 mandates `status`, `version` and `uptime`. An
+    // `unhealthy` body is paired with HTTP 503 so platform health probes pick up the failure.
     app.get('/health', async (req, res) => {
         let health = {
             status: 'healthy',
+            version: appConfig.version,
+            uptime: process.uptime(),
             details: {
-                uptime: process.uptime(),
                 timestamp: new Date().toISOString(),
             },
         };
@@ -112,15 +165,56 @@ export async function startHttpServer() {
                 health.status = 'unhealthy';
             }
         }
-        res.json(health);
+        res.status(health.status === 'healthy' ? 200 : 503).json(health);
     });
-    // Token check endpoint: GET /ct?t=<token> or POST /ct {"t": "<token>"}
-    // Returns { success, type: 'permanent' | 'JWT', payload? } or { success: false, error }
-    const handleTokenCheck = (req, res) => {
+    // Standard §15.3 — Prometheus metrics endpoint. Opt-in (default off). Public by design —
+    // protect via network policy / reverse proxy if the server is reachable from the network.
+    if (metricsEnabled) {
+        const metricsPath = metricsCfg?.path || '/metrics';
+        app.get(metricsPath, async (_req, res) => {
+            try {
+                const reg = getMetricsRegistry();
+                res.setHeader('Content-Type', reg.contentType);
+                res.end(await reg.metrics());
+            }
+            catch (err) {
+                logger.error('Failed to render Prometheus metrics', err);
+                res.status(500).send('Failed to render metrics');
+            }
+        });
+    }
+    // Readiness probe (standard §16.2) — no authentication; reports whether every dependency
+    // the server needs to serve traffic is up. Empty / sensitive details are NEVER returned —
+    // each check is reduced to `ok` / `error`.
+    app.get('/ready', async (req, res) => {
+        const checks = {};
+        let ready = true;
+        if (appConfig.isMainDBUsed) {
+            const dbStatus = await getMainDBConnectionStatus();
+            if (dbStatus === 'connected') {
+                checks.db = 'ok';
+            }
+            else {
+                checks.db = 'error';
+                ready = false;
+            }
+        }
+        // Cache singleton: trivially available; surface it for diagnostic completeness.
+        checks.cache = 'ok';
+        // JWKS check is a placeholder until Phase 5 introduces the OAuth profile.
+        checks.jwks = 'skipped';
+        res.status(ready ? 200 : 503).json({
+            status: ready ? 'ready' : 'not_ready',
+            checks,
+        });
+    });
+    // Token check endpoint: POST /ct {"t": "<token>"}. Standard §7.1 forbids secrets in URL.
+    // GET /ct?t=<token> is gated behind webServer.tokenCheck.allowQueryToken (non-prod only).
+    const handleTokenCheck = async (req, res) => {
         const raw = req.method === 'GET' ? req.query.t : req.body?.t;
         const token = typeof raw === 'string' ? raw.trim() : '';
         if (!token) {
-            return res.status(400).json({ success: false, error: 'Token not provided. Pass via "t" query/body parameter' });
+            return res.status(400).json({ success: false, error: 'Token not provided. Pass via "t" body parameter' });
         }
         const { errorReason: permError } = checkPermanentToken(token);
         if (!permError) {
@@ -129,13 +223,21 @@ export async function startHttpServer() {
         const xff = req.headers['x-forwarded-for'];
         const xffStr = (Array.isArray(xff) ? (xff[0] ?? '') : (xff ?? '')).split(',').shift() ?? '';
         const clientIp = req.ip ?? (xffStr.trim() || (req.socket?.remoteAddress ?? ''));
-        const jwtResult = checkJwtToken({ token, clientIp });
+        const jwtResult = await checkJwtToken({ token, clientIp });
         if (!jwtResult.errorReason) {
             return res.json({ success: true, type: 'JWT', payload: jwtResult.payload });
         }
         return res.status(401).json({ success: false, error: jwtResult.errorReason });
     };
-    app.get('/ct', handleTokenCheck);
+    const allowQueryToken = appConfig.webServer.tokenCheck?.allowQueryToken === true && process.env.NODE_ENV !== 'production';
+    if (allowQueryToken) {
+        app.get('/ct', handleTokenCheck);
+    }
+    else {
+        app.get('/ct', (_req, res) => res.status(405).json({
+            error: 'GET /ct is disabled by standard §7.1. Use POST /ct with JSON body {"t": "<token>"}.',
+        }));
+    }
     app.post('/ct', handleTokenCheck);
     // Public endpoint: returns used HTTP headers configured in the template (optional)
     app.get('/used-http-headers', (req, res) => {
@@ -172,13 +274,26 @@ export async function startHttpServer() {
     }
     // JWT generation API endpoint
     if (appConfig.webServer.genJwtApiEnable) {
+        const jwtMode = getJwtRuntimeConfig().mode;
         const encryptKey = appConfig.webServer.auth?.jwtToken?.encryptKey;
-        if (!encryptKey || encryptKey.length < MIN_ENCRYPT_KEY_LENGTH || encryptKey === '***') {
+        const legacyKeyMissing = jwtMode === 'legacyAesCtr' && (!encryptKey || encryptKey.length < MIN_ENCRYPT_KEY_LENGTH || encryptKey === '***');
+        if (legacyKeyMissing) {
             logger.error('genJwtApiEnable is true but webServer.auth.jwtToken.encryptKey is not configured');
         }
+        else if (jwtMode === 'remoteJwks') {
+            app.post('/gen-jwt', authMW, (_req, res) => {
+                const { jwksUri } = getJwtRuntimeConfig();
+                res.status(501).json({
+                    success: false,
+                    error: 'cannot_issue_token',
+                    error_description: 'This server runs in mode=remoteJwks and does not issue JWTs. ' +
+                        (jwksUri ? `Obtain tokens from the IdP at ${jwksUri}.` : 'Obtain tokens from the configured IdP.'),
+                });
+            });
+        }
         else {
             const TTL_MULTIPLIERS = { s: 1, m: 60, d: 86400, y: 31536000 };
-            app.post('/gen-jwt', authMW, (req, res) => {
+            app.post('/gen-jwt', authMW, async (req, res) => {
                 try {
                     const { username, ttl, service, params } = req.body;
                     if (!username || !username.trim()) {
@@ -224,7 +339,14 @@ export async function startHttpServer() {
                             Object.assign(payload, params);
                         }
                     }
-                    const token = generateToken(username.trim(), liveTimeSec, payload);
+                    if (jwtMode !== 'legacyAesCtr' && !canLocallyIssueJwt()) {
+                        return res.status(501).json({
+                            success: false,
+                            error: 'cannot_issue_token',
+                            error_description: `Current jwtToken.mode=${jwtMode} cannot sign tokens locally.`,
+                        });
+                    }
+                    const token = await generateToken(username.trim(), liveTimeSec, payload);
                     const expire = Date.now() + liveTimeSec * 1000;
                     return res.json({
                         success: true,
@@ -270,7 +392,7 @@ export async function startHttpServer() {
     // Client capabilities are read lazily on every call via `sseServer.getClientCapabilities()` so the
     // value reflects the post-handshake state for every list/read/call.
     async function createSseServer(preservedHeaders, mcpAuthPayload) {
-        const sseServer = createMcpServer();
+        const sseServer = createMcpServer('sse');
         const sseCtx = () => {
             const caps = sseServer.getClientCapabilities();
             return {
@@ -298,16 +420,20 @@ export async function startHttpServer() {
             return (await getResource(request.params.uri, sseCtx()));
         });
         // Override the tool call handler to include rate limiting, preserved headers and auth payload
-        sseServer.setRequestHandler(CallToolRequestSchema, async (request) => {
+        sseServer.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
             // Apply rate limiting for each SSE tool call
             const toolCallClientId = 'sse-tool-unknown';
             await handleRateLimit(rateLimiter, toolCallClientId, 'unknown', `SSE tool call | tool: ${request.params.name}`);
-            // Execute the tool call with preserved headers and payload from SSE connection establishment
+            // Execute the tool call with preserved headers and payload from SSE connection establishment.
+            // Same `mcp.limits` enforcement as the Streamable HTTP path.
             const { toolHandler } = getProjectData();
-            return (await toolHandler({
+            const sseToolName = request.params?.name ?? 'unknown';
+            const response = (await withToolTimeout(sseToolName, () => toolHandler({
                 ...request.params,
                 ...sseCtx(),
-            }));
+                signal: extra?.signal,
+            })));
+            return truncateToolResponse(response);
         });
         return sseServer;
     }
@@ -315,7 +441,7 @@ export async function startHttpServer() {
     app.get('/sse', authMW, async (req, res) => {
         try {
             // Apply rate limiting for SSE connection
-            const clientId = `sse-${req.ip || 'unknown'}`;
+            const clientId = resolveRateLimitKey(req, 'sse');
             await handleRateLimit(rateLimiter, clientId, req.ip || 'unknown', 'SSE', res, 1);
             logger.info('SSE client connected');
             // Preserve normalized headers from SSE connection establishment
@@ -366,14 +492,8 @@ export async function startHttpServer() {
             }
             const transportData = sseTransports.get(sessionId);
             if (!transportData) {
-                res.status(404).json({
-                    jsonrpc: '2.0',
-                    error: {
-                        code: -32001,
-                        message: 'Session not found',
-                    },
-                    id: null,
-                });
+                const err = new ResourceNotFoundError('SSE session not found');
+                res.status(err.statusCode).json(createJsonRpcErrorResponse(err, null));
                 return;
             }
             const { transport } = transportData;
@@ -398,18 +518,12 @@ export async function startHttpServer() {
                 break;
             }
             if (!targetTransport) {
-                res.status(404).json({
-                    jsonrpc: '2.0',
-                    error: {
-                        code: -32001,
-                        message: 'No SSE connection established. Connect via GET /sse first.',
-                    },
-                    id: req.body?.id ?? null,
-                });
+                const err = new ResourceNotFoundError('No SSE connection established. Connect via GET /sse first.');
+                res.status(err.statusCode).json(createJsonRpcErrorResponse(err, req.body?.id ?? null));
                 return;
             }
             // Apply rate limiting
-            const clientId = req.ip || 'unknown';
+            const clientId = resolveRateLimitKey(req);
             await handleRateLimit(rateLimiter, clientId, req.ip || 'unknown', 'SSE POST', res, req.body?.id);
             logger.info(`Direct SSE POST request received: ${req.body.method} | id: ${req.body.id}`);
             // Use the transport's built-in handlePostMessage method
@@ -422,158 +536,169 @@ export async function startHttpServer() {
             }
         }
     });
-    // Streamable HTTP is stateless per request — there is no per-connection MCP server holding
-    // capabilities after the handshake. We instead key the capabilities reported on `initialize`
-    // by the `Mcp-Session-Id` header the client SHOULD send on subsequent requests. When the
-    // header is missing (e.g. one-shot clients that don't observe sessions), `clientCapabilities`
-    // stays `undefined` and handlers MUST fall back to text-only output.
-    const httpClientCapabilitiesBySession = new Map();
+    // Streamable HTTP runs **stateful**: each MCP session owns a `StreamableHTTPServerTransport`
+    // bound to its own `Server` instance (so `getClientCapabilities()` works like on stdio). The
+    // transport is created on `initialize`, keyed by the server-generated `Mcp-Session-Id`, and the
+    // SDK transport handles protocol-version negotiation, error codes, notifications (202) and the
+    // GET-SSE / DELETE-teardown semantics for us.
     const HTTP_SESSION_HEADER = 'mcp-session-id';
-    // Soft cap to bound memory; oldest session entry is evicted (FIFO via Map insertion order).
+    // Soft cap to bound memory; oldest session is evicted (FIFO via Map insertion order).
     const MAX_HTTP_SESSIONS = 4096;
-    const getSessionId = (headers) => headers[HTTP_SESSION_HEADER];
-    const cacheClientCapabilities = (sessionId, capabilities) => {
-        if (httpClientCapabilitiesBySession.size >= MAX_HTTP_SESSIONS) {
-            const oldestKey = httpClientCapabilitiesBySession.keys().next().value;
-            if (oldestKey) {
-                httpClientCapabilitiesBySession.delete(oldestKey);
+    const mcpTransports = new Map();
+    // Standard §6 (MAY) — SSE resumability. A single in-memory EventStore is shared across sessions
+    // (each stream owns its own streamId). Created only when opted in; otherwise the transport is
+    // built without an eventStore and behavior is unchanged.
+    const sseResumability = appConfig.mcp.sse?.resumability === true;
+    const sseEventStore = sseResumability
+        ? new InMemoryEventStore(appConfig.mcp.sse?.maxStoredEvents ?? 1000)
+        : undefined;
+    if (sseResumability) {
+        logger.info(`MCP SSE resumability enabled (in-memory, max ${appConfig.mcp.sse?.maxStoredEvents ?? 1000} events)`);
+    }
+    const evictOldestSession = (keep) => {
+        while (mcpTransports.size > MAX_HTTP_SESSIONS) {
+            const oldest = mcpTransports.keys().next().value;
+            if (!oldest || oldest === keep) {
+                break;
+            }
+            const t = mcpTransports.get(oldest);
+            mcpTransports.delete(oldest);
+            void t?.close();
+        }
+    };
+    // Race the underlying transport against `mcp.limits.toolTimeoutMs` for `tools/call` requests.
+    // The standard (§14) requires HTTP 504 + JSON-RPC -32004 on timeout. The SDK's transport
+    // doesn't surface HTTP-level timeouts, so we monitor at this layer — whoever writes the
+    // response first wins. The tool promise itself is still bounded inside the SDK handler by
+    // `withToolTimeout`, which throws an `McpError(-32004)` to keep the JSON-RPC code correct
+    // for the SSE branch and for the (unlikely) case the handler beats the HTTP timer.
+    const runHttpToolCall = async (req, res, exec) => {
+        if (req.body?.method !== 'tools/call') {
+            await exec();
+            return;
+        }
+        const timeoutMs = appConfig.mcp.limits.toolTimeoutMs;
+        let timer;
+        const timerPromise = new Promise((resolve) => {
+            timer = setTimeout(() => resolve('timeout'), timeoutMs);
+            if (typeof timer?.unref === 'function') {
+                timer.unref();
+            }
+        });
+        try {
+            const winner = await Promise.race([exec().then(() => 'done'), timerPromise]);
+            if (winner === 'timeout' && !res.headersSent) {
+                const toolName = req.body?.params?.name ?? 'unknown';
+                const err = new TimeoutError(`Tool '${toolName}' exceeded ${timeoutMs} ms timeout`, {
+                    reason: 'tool_timeout',
+                });
+                logger.warn(`Tool timeout (${timeoutMs} ms) for tool: ${toolName}`);
+                res.status(err.statusCode).json(createJsonRpcErrorResponse(err, req.body?.id ?? null));
             }
         }
-        httpClientCapabilitiesBySession.set(sessionId, capabilities);
+        finally {
+            if (timer) {
+                clearTimeout(timer);
+            }
+        }
+    };
+    const noSessionError = (req, res) => {
+        res.status(400).json({
+            jsonrpc: '2.0',
+            id: req.body?.id ?? null,
+            error: { code: -32600, message: 'No valid MCP session. Send `initialize` first.' },
+        });
     };
-    // POST endpoint for MCP requests
+    // GET (server→client SSE stream) and DELETE (session teardown) operate on an existing session.
+    const routeToSession = async (req, res) => {
+        const sessionId = req.headers[HTTP_SESSION_HEADER];
+        const transport = sessionId ? mcpTransports.get(sessionId) : undefined;
+        if (!transport) {
+            noSessionError(req, res);
+            return;
+        }
+        await transport.handleRequest(req, res, req.body);
+    };
+    // POST endpoint for MCP requests — handshake + all JSON-RPC calls go through the SDK transport.
     app.post('/mcp', authMW, async (req, res) => {
         try {
-            // Apply rate limiting
-            const clientId = req.ip || 'unknown';
+            // Rate limiting and the body-size limit stay here, before the transport takes over.
+            const clientId = resolveRateLimitKey(req);
             await handleRateLimit(rateLimiter, clientId, req.ip || 'unknown', 'HTTP MCP', res, req.body?.id);
-            const request = req.body;
-            const { method, params, id } = request;
-            logger.info(`HTTP MCP request received: ${method} | id: ${id}`);
-            // JSON-RPC notifications (no `id`) MUST NOT receive a response. MCP clients legitimately
-            // emit a variety of `notifications/*` events (initialized, cancelled, progress,
-            // roots/list_changed, message, …) and we acknowledge them with 204 instead of erroring out
-            // on unknown ones — matching MCP/JSON-RPC semantics and keeping the log clean.
-            if (typeof method === 'string' && method.startsWith('notifications/')) {
-                if (method === 'notifications/initialized') {
-                    logger.info('MCP client initialization completed');
-                }
-                else {
-                    logger.debug(`MCP notification received: ${method}`);
-                }
-                if (debugMcpNotification.enabled) {
-                    debugMcpNotification(`← ${method}\n${JSON.stringify(params ?? {}, null, 2)}`);
+            if (res.headersSent) {
+                return; // rate limit already responded
+            }
+            // Dedicated rate-limit bucket for tool calls (was inline in the old switch).
+            if (req.body?.method === 'tools/call') {
+                const toolCallClientId = resolveRateLimitKey(req, 'tool');
+                await handleRateLimit(rateLimiter, toolCallClientId, req.ip || 'unknown', `tool call | tool: ${req.body?.params?.name || 'unknown'}`, res, req.body?.id);
+                if (res.headersSent) {
+                    return;
                 }
-                return res.status(204).send();
             }
-            const mcpAuthPayload = req.authInfo?.payload;
-            const preservedHeaders = normalizeHeaders(req.headers);
-            const sessionId = getSessionId(preservedHeaders);
-            const cachedCapabilities = sessionId ? httpClientCapabilitiesBySession.get(sessionId) : undefined;
-            const httpArgs = {
-                transport: 'http',
-                headers: preservedHeaders,
-                payload: mcpAuthPayload,
-                ...(cachedCapabilities ? { clientCapabilities: cachedCapabilities } : {}),
-            };
-            let result;
-            switch (method) {
-                case 'initialize':
-                    const { protocolVersion, capabilities: clientCapabilities, clientInfo } = params || {};
-                    logger.info(`MCP client initializing: protocolVersion: ${protocolVersion} | clientCapabilities: ${JSON.stringify(clientCapabilities)} | clientInfo: ${JSON.stringify(clientInfo)}`);
-                    // Cache reported capabilities so subsequent stateless POSTs from the same session can
-                    // surface them through `IToolHandlerParams.clientCapabilities`.
-                    if (sessionId && clientCapabilities && typeof clientCapabilities === 'object') {
-                        cacheClientCapabilities(sessionId, clientCapabilities);
+            const sessionId = req.headers[HTTP_SESSION_HEADER];
+            const existing = sessionId ? mcpTransports.get(sessionId) : undefined;
+            if (existing) {
+                await runHttpToolCall(req, res, () => existing.handleRequest(req, res, req.body));
+                return;
+            }
+            if (isInitializeRequest(req.body)) {
+                logger.info(`MCP client initializing: protocolVersion: ${req.body?.params?.protocolVersion} | clientInfo: ${JSON.stringify(req.body?.params?.clientInfo)}`);
+                const transport = new StreamableHTTPServerTransport({
+                    sessionIdGenerator: () => randomUUID(),
+                    // Standard §6 (MAY) — attach the EventStore only when resumability is enabled.
+                    ...(sseEventStore ? { eventStore: sseEventStore } : {}),
+                    onsessioninitialized: (sid) => {
+                        mcpTransports.set(sid, transport);
+                        evictOldestSession(sid);
+                    },
+                    onsessionclosed: (sid) => {
+                        mcpTransports.delete(sid);
+                    },
+                });
+                // SDK `Transport` exposes `onclose` as a plain setter (not an EventTarget), so
+                // `addEventListener` does not apply here — this is the canonical SDK pattern.
+                // oxlint-disable-next-line unicorn/prefer-add-event-listener
+                transport.onclose = () => {
+                    const sid = transport.sessionId;
+                    if (sid) {
+                        mcpTransports.delete(sid);
                     }
-                    result = {
-                        protocolVersion: '2024-11-05',
-                        capabilities: {
-                            tools: {},
-                            prompts: {},
-                            resources: {},
-                        },
-                        serverInfo: {
-                            name: appConfig.name,
-                            version: appConfig.version,
-                        },
-                    };
-                    break;
-                case 'tools/list':
-                    const tools = await getTools(httpArgs);
-                    result = { tools };
-                    break;
-                case 'tools/call':
-                    // Apply rate limiting for tool calls
-                    const toolCallClientId = `tool-${req.ip || 'unknown'}`;
-                    await handleRateLimit(rateLimiter, toolCallClientId, req.ip || 'unknown', `tool call | tool: ${params?.name || 'unknown'}`, res, id);
-                    const { toolHandler } = getProjectData();
-                    result = await toolHandler({ ...params, ...httpArgs });
-                    break;
-                case 'prompts/list':
-                    result = await getPromptsList(httpArgs);
-                    break;
-                case 'prompts/get': {
-                    result = await getPrompt(request, httpArgs);
-                    break;
-                }
-                case 'resources/list':
-                    result = await getResourcesList(httpArgs);
-                    break;
-                case 'resources/read': {
-                    result = await getResource(params.uri, httpArgs);
-                    break;
-                }
-                case 'ping':
-                    result = { pong: true };
-                    break;
-                default:
-                    throw new Error(`Unknown method: ${method}`);
+                };
+                const server = createMcpServer('http');
+                // Cast: SDK `Transport` types are stricter under `exactOptionalPropertyTypes`, but
+                // `StreamableHTTPServerTransport` is a valid transport.
+                await server.connect(transport);
+                await runHttpToolCall(req, res, () => transport.handleRequest(req, res, req.body));
+                return;
             }
-            return res.json({
-                jsonrpc: '2.0',
-                id,
-                result,
-            });
+            // No session and not an `initialize` request → 400 per MCP transport semantics.
+            noSessionError(req, res);
         }
         catch (error) {
             if (!error.printed) {
                 logger.error('MCP request failed', toError(error));
                 error.printed = true;
             }
-            let errorResponse;
-            if (error instanceof BaseMcpError) {
-                // Use full error structure with details for better debugging
-                const errorObj = error.toJSON();
-                errorResponse = {
-                    code: -1,
-                    message: errorObj.message,
-                    data: {
-                        code: errorObj.code,
-                        details: errorObj.details,
-                        // stack: process.env.NODE_ENV === 'development' ? errorObj.stack : undefined
-                    },
-                };
-            }
-            else {
-                // Standard error handling for non-MCP errors
-                errorResponse = {
-                    code: -1,
-                    message: toStr(error),
-                };
+            if (!res.headersSent) {
+                res
+                    .status(500)
+                    .json(createJsonRpcErrorResponse(error instanceof ServerError ? error : new ServerError(toStr(error))));
             }
-            return res.json({
-                jsonrpc: '2.0',
-                id: req.body?.id ?? 1,
-                error: errorResponse,
-            });
         }
     });
+    app.get('/mcp', authMW, async (req, res) => {
+        await routeToSession(req, res);
+    });
+    app.delete('/mcp', authMW, async (req, res) => {
+        await routeToSession(req, res);
+    });
     // 404 handler for unknown routes
     app.use((req, res) => {
         const availableEndpoints = {
             home: 'GET /',
             health: 'GET /health',
+            ready: 'GET /ready',
             checkToken: 'GET /ct?t=<token>, POST /ct',
             sse: 'GET /sse, POST /sse',
             messages: 'POST /messages',
@@ -599,17 +724,32 @@ export async function startHttpServer() {
             availableEndpoints,
         });
     });
-    // Error handling middleware (must have 4 parameters for Express to recognize it)
+    // Error handling middleware (must have 4 parameters for Express to recognize it).
+    // Special case: `express.json()` raises `entity.too.large` with `error.type === 'entity.too.large'`
+    // when the request body exceeds `mcp.limits.maxPayloadBytes`. Standard §14 maps that to
+    // JSON-RPC `-32005` / HTTP 413.
     app.use((error, req, res, _next) => {
+        if (error && error.type === 'entity.too.large') {
+            logger.warn(`Payload too large from ip: ${req.ip}, limit: ${maxPayloadBytes}`);
+            if (!res.headersSent) {
+                const err = new PayloadTooLargeError(`Request body exceeds ${maxPayloadBytes} bytes`, {
+                    reason: 'payload_too_large',
+                });
+                res.status(err.statusCode).json(createJsonRpcErrorResponse(err, req.body?.id ?? null));
+            }
+            return;
+        }
         logger.error('Express error handler', error);
         if (!res.headersSent) {
             res.status(500).json(createJsonRpcErrorResponse(error));
         }
     });
-    // Start HTTP server
-    const { port } = appConfig.webServer;
-    app.listen(port, '0.0.0.0', () => {
-        let msg = `${chalk.magenta(appConfig.productName)} started with ${chalk.blue('HTTP')} transport on port ${chalk.blue(port)}
+    // Start HTTP server. Bind address is driven by config — default is the loopback interface
+    // (`127.0.0.1`) so the server is unreachable from the network until an operator opts in to
+    // `0.0.0.0` or a specific NIC address. Standard §6.
+    const { port, host } = appConfig.webServer;
+    app.listen(port, host || '127.0.0.1', () => {
+        let msg = `${chalk.magenta(appConfig.productName)} started with ${chalk.blue('HTTP')} transport on ${chalk.blue(host)}:${chalk.blue(port)}
 Home page: http://localhost:${port}/`;
         if (isAdminEnabled) {
             msg += `\nAdmin panel: http://localhost:${port}/admin`;