{"record":{"id":"a79aa0d9e9a6323c","repo":"different-ai/openwork","slug":"mcp-http-content-type","errorCode":"MCP_HTTP_CONTENT_TYPE","errorMessage":"MCP_HTTP_CONTENT_TYPE","messagePattern":"MCP_HTTP_CONTENT_TYPE","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"ee/apps/den-api/src/capability-sources/external-mcp-diagnostics.ts","lineNumber":997,"sourceCode":"      operatorAction: \"Inspect provider and proxy logs for the failing HTTP request using the diagnostic reference.\",\n    }\n  }\n  if (phase.startsWith(\"MCP_\") && input.contentType === \"text/html\") {\n    return {\n      phase: \"HTTP_ROUTING\",\n      category: \"unexpected_html\",\n      code: \"MCP_HTTP_HTML_RESPONSE\",\n      retryable: false,\n      actionOwner: \"organization_admin\",\n      operatorAction: \"Verify the MCP path is not a sign-in page, portal route, or proxy-generated HTML response.\",\n    }\n  }\n  if (phase === \"MCP_INITIALIZED\" && (status === 202 || status === 204)) return null\n  if (phase.startsWith(\"MCP_\") && input.contentType !== \"application/json\" && input.contentType !== \"text/event-stream\") {\n    return {\n      phase: \"MCP_TRANSPORT\",\n      category: \"unexpected_content_type\",\n      code: \"MCP_HTTP_CONTENT_TYPE\",\n      retryable: false,\n      actionOwner: \"provider_admin\",\n      operatorAction: \"Return an MCP JSON or event-stream response with a standards-compliant Content-Type header.\",\n    }\n  }\n  return null\n}\n\nfunction classifyByCode(code: string): Classification | null {\n  if (code === \"MCP_OAUTH_AUTHORIZATION_ID_REQUIRED\") {\n    return {\n      phase: \"CONFIGURATION\",\n      category: \"oauth_authorization_transaction_invalid\",\n      code,\n      retryable: false,\n      actionOwner: \"openwork\",\n      operatorAction: \"Start OAuth through Den so the callback is bound to a signed, expiring authorization transaction.\",\n    }","sourceCodeStart":979,"sourceCodeEnd":1015,"githubUrl":"https://github.com/different-ai/openwork/blob/2b7df46e8ae1517d64c896c7793d2d52ec845669/ee/apps/den-api/src/capability-sources/external-mcp-diagnostics.ts#L979-L1015","documentation":"MCP_HTTP_CONTENT_TYPE is raised when an MCP-phase response has a Content-Type that is neither application/json nor text/event-stream (and it is not the exempt MCP_INITIALIZED 202/204 case). It signals MCP_TRANSPORT / unexpected_content_type: the server answered, but not with a standards-compliant MCP payload encoding, so the client cannot parse it. Non-retryable, owned by the provider admin.","triggerScenarios":"Any MCP request whose response Content-Type is, e.g., text/plain, application/octet-stream, or missing entirely — instead of application/json or text/event-stream — during discovery, execution, or other MCP phases.","commonSituations":"Provider returning plain-text error bodies with wrong headers; a non-JSON endpoint deployed at the MCP path; proxy middleware (compression, body rewrites) stripping or replacing the Content-Type header; provider server upgrade regressing streamable-HTTP content negotiation (e.g. always replying JSON where SSE was negotiated, or vice versa, with a bad header).","solutions":["Fix the provider to return application/json or text/event-stream with a standards-compliant Content-Type header for MCP responses.","Check for middleware/proxies between the gateway and provider that rewrite or strip the Content-Type.","Confirm the endpoint is actually the streamable-HTTP MCP server, not a legacy/custom handler with different response encoding."],"exampleFix":"// before: plain-text error response\nreturn new Response('oops', { status: 200 })\n// after\nreturn new Response(JSON.stringify({ jsonrpc: '2.0', error }), { status: 200, headers: { 'Content-Type': 'application/json' } })","handlingStrategy":"validation","validationCode":"// assert standards-compliant content type before accepting the endpoint\nconst allowed = ['application/json', 'text/event-stream']\nconst ct = (res.headers.get('content-type') ?? '').split(';')[0].trim()\nif (!allowed.includes(ct)) throw new Error(`non-MCP Content-Type: ${ct}`)","typeGuard":"function isBadContentType(d: { code: string }): boolean {\n  return d.code === 'MCP_HTTP_CONTENT_TYPE'\n}","tryCatchPattern":"try {\n  return await parseMcpResponse(res)\n} catch (e) {\n  if (isBadContentType(e.diagnostic)) {\n    // non-retryable: provider must fix its Content-Type header; capture it for the bug report\n    throw new Error(`provider returned Content-Type '${res.headers.get('content-type')}'`)\n  }\n  throw e\n}","preventionTips":["Always set Content-Type: application/json (or text/event-stream for streams) on provider MCP responses.","Audit proxies/middleware for header rewriting or body re-encoding.","Add an integration test asserting response Content-Type on initialize, tools/list, and tools/call."],"tags":["mcp","content-type","transport","protocol","non-retryable"],"backgroundTag":"unexpected-content-type","analyzedSha":"2b7df46e8ae1517d64c896c7793d2d52ec845669","analyzedAt":"2026-09-01T07:59:23.713Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}