different-ai/openwork · error

MCP_HTTP_HTML_RESPONSE

MCP_HTTP_HTML_RESPONSE

Error message

MCP_HTTP_HTML_RESPONSE

What it means

MCP_HTTP_HTML_RESPONSE is raised when an MCP-phase request returns a response whose Content-Type is text/html. The classifier maps this to HTTP_ROUTING / unexpected_content_type: the URL is reachable, but it is serving an HTML page instead of the MCP JSON/event-stream protocol — almost always a sign-in page, portal route, or proxy-generated error page sitting at the MCP path. Non-retryable, owned by the organization admin.

Source

Thrown at ee/apps/den-api/src/capability-sources/external-mcp-diagnostics.ts:986

        operatorAction: "Grant the provider role, ACL, or application permission required for this operation.",
      }
    }
  }
  if (status >= 400) {
    return {
      phase,
      category: "http_failure",
      code: `MCP_HTTP_${status}`,
      retryable: status === 408,
      actionOwner: "provider_admin",
      operatorAction: "Inspect provider and proxy logs for the failing HTTP request using the diagnostic reference.",
    }
  }
  if (phase.startsWith("MCP_") && input.contentType === "text/html") {
    return {
      phase: "HTTP_ROUTING",
      category: "unexpected_html",
      code: "MCP_HTTP_HTML_RESPONSE",
      retryable: false,
      actionOwner: "organization_admin",
      operatorAction: "Verify the MCP path is not a sign-in page, portal route, or proxy-generated HTML response.",
    }
  }
  if (phase === "MCP_INITIALIZED" && (status === 202 || status === 204)) return null
  if (phase.startsWith("MCP_") && input.contentType !== "application/json" && input.contentType !== "text/event-stream") {
    return {
      phase: "MCP_TRANSPORT",
      category: "unexpected_content_type",
      code: "MCP_HTTP_CONTENT_TYPE",
      retryable: false,
      actionOwner: "provider_admin",
      operatorAction: "Return an MCP JSON or event-stream response with a standards-compliant Content-Type header.",
    }
  }
  return null
}

View on GitHub (pinned to 2b7df46e8a)

Solutions

1. Verify the MCP path is not a sign-in page, portal route, or proxy-generated HTML response by inspecting the returned HTML.
2. Correct the configured endpoint URL or add the authentication the proxy/SSO requires so the MCP handler is reached.
3. Fix the reverse proxy/SPA fallback so /mcp routes to the MCP server rather than the HTML index.

Example fix

// before: SPA fallback catches /mcp
app.get('*', () => sendFile('index.html'))
// after: MCP path excluded from the fallback
app.use('/mcp', mcpServer)
app.get('*', () => sendFile('index.html'))

// verify the endpoint returns an MCP content type before wiring it up
const probe = await fetch(mcpUrl, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: initializeBody })
const ct = probe.headers.get('content-type') ?? ''
if (ct.includes('text/html')) throw new Error(`${mcpUrl} serves HTML (sign-in/portal/proxy page), not MCP`) 

function isHtmlResponse(d: { code: string }): boolean {
  return d.code === 'MCP_HTTP_HTML_RESPONSE'
}

try {
  return await client.initialize(mcpUrl)
} catch (e) {
  if (isHtmlResponse(e.diagnostic)) {
    // non-retryable: inspect the HTML body (login page? proxy error?) and fix routing/auth
    throw new Error(`HTML page at MCP path — check SSO/proxy for ${mcpUrl}`)
  }
  throw e
}

When it happens

Trigger: Any request in an MCP_ phase where input.contentType === 'text/html'. Classic cases: an SSO gateway intercepting the MCP path and returning a login page, a proxy returning its HTML 502/error page, or the configured URL pointing at a web portal route instead of the MCP endpoint.

Common situations: Provider behind SSO where the MCP route requires a session cookie and unauthenticated requests get the login HTML; corporate proxies replacing upstream errors with branded HTML; misconfigured reverse proxy routing /mcp to a SPA fallback index.html.

Related errors

• MCP endpoint returned HTTP ${methodResponse.status} to GET
• MCP_HTTP_404
• MCP_HTTP_CONTENT_TYPE
• invalid_mcp_token_payload
• invalid_mcp_connection_payload

AI-assisted analysis of different-ai/openwork@2b7df46e8a (2026-09-01). Data as JSON: /api/errors/4a6134dca7fd777d. Report an issue: GitHub.