{"record":{"id":"78a3d2551436320e","repo":"different-ai/openwork","slug":"mcp-http-404","errorCode":"MCP_HTTP_404","errorMessage":"MCP_HTTP_404","messagePattern":"MCP_HTTP_404","errorType":"error_code","errorClass":null,"httpStatus":404,"severity":"error","filePath":"ee/apps/den-api/src/capability-sources/external-mcp-diagnostics.ts","lineNumber":909,"sourceCode":"  hasSession: boolean\n  contentType: string\n}): Classification | null {\n  const { phase, status } = input\n  if (status === 404 && input.hasSession) {\n    return {\n      phase: \"CONTINUITY_SESSION\",\n      category: \"mcp_session_expired\",\n      code: \"MCP_SESSION_NOT_FOUND\",\n      retryable: true,\n      actionOwner: \"openwork\",\n      operatorAction: \"Reinitialize the MCP session, then retry the operation once.\",\n    }\n  }\n  if (status === 404 && phase.startsWith(\"MCP_\")) {\n    return {\n      phase: \"HTTP_ROUTING\",\n      category: \"endpoint_not_found\",\n      code: \"MCP_HTTP_404\",\n      retryable: false,\n      actionOwner: \"organization_admin\",\n      operatorAction: \"Verify the complete MCP endpoint path, including any provider tenant or instance prefix.\",\n    }\n  }\n  if ((status === 406 || status === 415) && phase.startsWith(\"MCP_\")) {\n    return {\n      phase: \"MCP_TRANSPORT\",\n      category: \"mcp_transport_negotiation\",\n      code: `MCP_HTTP_${status}`,\n      retryable: false,\n      actionOwner: \"provider_admin\",\n      operatorAction: \"Verify Streamable HTTP content negotiation and the provider's supported MCP transport.\",\n    }\n  }\n  if (status === 429) {\n    return {\n      phase,","sourceCodeStart":891,"sourceCodeEnd":927,"githubUrl":"https://github.com/different-ai/openwork/blob/2b7df46e8ae1517d64c896c7793d2d52ec845669/ee/apps/den-api/src/capability-sources/external-mcp-diagnostics.ts#L891-L927","documentation":"MCP_HTTP_404 is raised when an MCP-phase request returns HTTP 404 and there is no established session (the hasSession branch above it did not match). It is classified as HTTP_ROUTING / endpoint_not_found: the configured MCP URL does not resolve to an MCP endpoint at all. It is non-retryable and owned by the organization admin because the URL/path must be corrected.","triggerScenarios":"Calling the MCP endpoint URL (initialize, tools/list, or tools/call) when no session exists and the server answers 404 — e.g. the path in the external MCP source configuration is wrong or missing a tenant/instance prefix.","commonSituations":"Configuring the MCP base URL without the /mcp route segment; forgetting a tenant, instance, or version prefix required by the provider (e.g. /org/{id}/mcp); pointing at a domain that hosts other services where only other paths exist.","solutions":["Verify the complete MCP endpoint path in the external MCP source config, including any provider tenant or instance prefix.","Test the URL directly with curl/HTTP client to confirm a 200/initialize response at exactly that path.","Correct the configured URL and re-run the capability; do not retry, this is not transient."],"exampleFix":"// before: baseUrl missing the tenant prefix\nconst url = 'https://mcp.example.com/mcp'\n// after\nconst url = 'https://mcp.example.com/tenants/acme/mcp'","handlingStrategy":"validation","validationCode":"// verify the endpoint answers before configuring it\nconst res = await fetch(mcpUrl, { method: 'POST', headers: { 'Content-Type': 'application/json', Accept: 'application/json, text/event-stream' }, body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: {} }) })\nif (res.status === 404) throw new Error(`MCP endpoint not found at ${mcpUrl}`)","typeGuard":"function isEndpointNotFound(d: { code: string }): boolean {\n  return d.code === 'MCP_HTTP_404'\n}","tryCatchPattern":"try {\n  return await client.initialize(mcpUrl)\n} catch (e) {\n  if (isEndpointNotFound(e.diagnostic)) {\n    // non-retryable: surface config error to org admin with the exact URL used\n    throw new Error(`Bad MCP URL configured: ${mcpUrl}`)\n  }\n  throw e\n}","preventionTips":["Copy the full MCP endpoint URL (including tenant/instance prefix) from the provider's docs, not just the base domain.","Smoke-test the URL with an initialize request before saving the external source config.","Re-check the endpoint path after provider tenant moves or version upgrades."],"tags":["mcp","http-404","routing","configuration","non-retryable"],"backgroundTag":"http-404-endpoint-not-found","analyzedSha":"2b7df46e8ae1517d64c896c7793d2d52ec845669","analyzedAt":"2026-09-01T07:59:23.713Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}