{"record":{"id":"350c44c8b3953ddb","repo":"mastra-ai/mastra","slug":"mcp-server-modern-http-options-incompatible","errorCode":"MCP_SERVER_MODERN_HTTP_OPTIONS_INCOMPATIBLE","errorMessage":"startHTTP options ${names.map(name => `\"${name}\"`).join(', ')} are incompatible with protocolVersion \"2026-07-28\"","messagePattern":"startHTTP options (.+?)\"`\\)\\.join\\(', '\\)\\} are incompatible with protocolVersion \"2026-07-28\"","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/mcp/src/server/server.ts","lineNumber":583,"sourceCode":"  private servesModernEra(): boolean {\n    return this.protocolVersion === '2026-07-28';\n  }\n\n  private assertModernEraHTTPOptions(options?: MCPServerStreamableHTTPOptions): void {\n    if (!options) return;\n\n    const incompatibleOptions = new Set(\n      Object.keys(options).filter(option => !ACCEPTED_MODERN_ERA_HTTP_OPTION_KEYS.has(option)),\n    );\n\n    if (options.sessionIdGenerator !== undefined) incompatibleOptions.add('sessionIdGenerator');\n    if (options.serverless === false) incompatibleOptions.add('serverless');\n    if (options.serverlessStreaming === false) incompatibleOptions.add('serverlessStreaming');\n\n    if (incompatibleOptions.size === 0) return;\n\n    const names = [...incompatibleOptions].sort();\n    throw new MastraError({\n      id: 'MCP_SERVER_MODERN_HTTP_OPTIONS_INCOMPATIBLE',\n      domain: ErrorDomain.MCP,\n      category: ErrorCategory.USER,\n      text: `startHTTP options ${names.map(name => `\"${name}\"`).join(', ')} are incompatible with protocolVersion \"2026-07-28\"`,\n      details: { incompatibleOptions: names.join(', ') },\n    });\n  }\n\n  private validateHTTPRequestHeaders(\n    req: http.IncomingMessage,\n    res: http.ServerResponse<http.IncomingMessage>,\n    options?: MCPServerStreamableHTTPOptions,\n  ): boolean {\n    if (!options?.enableDnsRebindingProtection) return true;\n\n    if (options.allowedHosts?.length) {\n      const allowedHostnames = options.allowedHosts.map(host => new URL(`http://${host}`).hostname);\n      if (!hostHeaderValidation(allowedHostnames)(req, res)) return false;","sourceCodeStart":565,"sourceCodeEnd":601,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/mcp/src/server/server.ts#L565-L601","documentation":"`startHTTP` with protocolVersion \"2026-07-28\" runs in the modern serverless-capable HTTP era, so legacy options that opt out of that behavior are rejected. `assertModernEraHTTPOptions` collects options such as `serverless: false` or `serverlessStreaming: false` and throws this MastraError (USER category) listing the incompatible names.","triggerScenarios":"Calling `server.startHTTP({ protocolVersion: '2026-07-28', serverless: false })` (or `serverlessStreaming: false`, or other legacy HTTP options collected into `incompatibleOptions`) — any explicitly-`false` legacy flag combined with the modern protocol version.","commonSituations":"Upgrading an existing server to the 2026-07-28 protocol version while keeping old `serverless: false` config copied from pre-modern-era examples or migration guides.","solutions":["Remove the `serverless: false` / `serverlessStreaming: false` options from the startHTTP call; modern-era defaults apply.","If you truly need the legacy behavior, keep the older protocolVersion instead of \"2026-07-28\".","Read `details.incompatibleOptions` in the thrown MastraError to see exactly which options to drop."],"exampleFix":"// before\nawait server.startHTTP({ protocolVersion: '2026-07-28', serverless: false });\n// after\nawait server.startHTTP({ protocolVersion: '2026-07-28' });","handlingStrategy":"validation","validationCode":"if (opts.protocolVersion === '2026-07-28' && (opts.serverless === false || opts.serverlessStreaming === false)) throw new Error('Legacy serverless:false options are incompatible with protocolVersion 2026-07-28');","typeGuard":null,"tryCatchPattern":"try { await server.startHTTP(opts); } catch (e) { if (e?.id === 'MCP_SERVER_MODERN_HTTP_OPTIONS_INCOMPATIBLE') { const { incompatibleOptions } = e.details; for (const name of incompatibleOptions.split(', ')) delete opts[name.trim()]; await server.startHTTP(opts); } else throw e; }","preventionTips":["Don't carry legacy serverless/serverlessStreaming flags into modern protocolVersion configs.","Pin and review startHTTP options when bumping protocolVersion.","Type your options object so `false` values require an explicit, documented decision."],"tags":["configuration","mcp","http","protocol-version"],"backgroundTag":"incompatible-options-combination","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}