different-ai/openwork · error

MCP_HTTP_404

MCP_HTTP_404

Error message

MCP_HTTP_404

What it means

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.

Source

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

  hasSession: boolean
  contentType: string
}): Classification | null {
  const { phase, status } = input
  if (status === 404 && input.hasSession) {
    return {
      phase: "CONTINUITY_SESSION",
      category: "mcp_session_expired",
      code: "MCP_SESSION_NOT_FOUND",
      retryable: true,
      actionOwner: "openwork",
      operatorAction: "Reinitialize the MCP session, then retry the operation once.",
    }
  }
  if (status === 404 && phase.startsWith("MCP_")) {
    return {
      phase: "HTTP_ROUTING",
      category: "endpoint_not_found",
      code: "MCP_HTTP_404",
      retryable: false,
      actionOwner: "organization_admin",
      operatorAction: "Verify the complete MCP endpoint path, including any provider tenant or instance prefix.",
    }
  }
  if ((status === 406 || status === 415) && phase.startsWith("MCP_")) {
    return {
      phase: "MCP_TRANSPORT",
      category: "mcp_transport_negotiation",
      code: `MCP_HTTP_${status}`,
      retryable: false,
      actionOwner: "provider_admin",
      operatorAction: "Verify Streamable HTTP content negotiation and the provider's supported MCP transport.",
    }
  }
  if (status === 429) {
    return {
      phase,

View on GitHub (pinned to 2b7df46e8a)

Solutions

1. Verify the complete MCP endpoint path in the external MCP source config, including any provider tenant or instance prefix.
2. Test the URL directly with curl/HTTP client to confirm a 200/initialize response at exactly that path.
3. Correct the configured URL and re-run the capability; do not retry, this is not transient.

Example fix

// before: baseUrl missing the tenant prefix
const url = 'https://mcp.example.com/mcp'
// after
const url = 'https://mcp.example.com/tenants/acme/mcp'

// verify the endpoint answers before configuring it
const 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: {} }) })
if (res.status === 404) throw new Error(`MCP endpoint not found at ${mcpUrl}`)

function isEndpointNotFound(d: { code: string }): boolean {
  return d.code === 'MCP_HTTP_404'
}

try {
  return await client.initialize(mcpUrl)
} catch (e) {
  if (isEndpointNotFound(e.diagnostic)) {
    // non-retryable: surface config error to org admin with the exact URL used
    throw new Error(`Bad MCP URL configured: ${mcpUrl}`)
  }
  throw e
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• unsupported_transport
• MCP_OAUTH_CONFIGURATION_REQUIRED
• MCP endpoint returned HTTP ${methodResponse.status} to GET
• CONTINUITY_SESSION
• mcp_oauth_configuration_required

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