different-ai/openwork · error

MCP_UNSUPPORTED_VERSION

MCP_UNSUPPORTED_VERSION

Error message

Configure the provider to support an MCP protocol version compatible with OpenWork.

What it means

This diagnostic code is emitted when the error message from an external MCP server indicates an unsupported MCP protocol version (detected via hasUnsupportedVersionMessage). The server and OpenWork could not agree on a mutually supported MCP protocol version during initialization, so the connection is classified as mcp_version_mismatch at phase MCP_VERSION, non-retryable, owned by the provider administrator.

Source

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

      actionOwner: "organization_admin",
      operatorAction: "Verify the provider OAuth flow, redirect URI, PKCE, and registered grant/response types.",
    }
  }
  if (name === "TemporarilyUnavailableError" || name === "ServerError") {
    return {
      phase: fallbackPhase,
      category: "oauth_provider_unavailable",
      code: name === "TemporarilyUnavailableError" ? "MCP_OAUTH_TEMPORARILY_UNAVAILABLE" : "MCP_OAUTH_SERVER_ERROR",
      retryable: true,
      actionOwner: "provider_admin",
      operatorAction: "Check authorization-server availability and retry with bounded backoff.",
    }
  }
  if (hasUnsupportedVersionMessage(error)) {
    return {
      phase: "MCP_VERSION",
      category: "mcp_version_mismatch",
      code: "MCP_UNSUPPORTED_VERSION",
      retryable: false,
      actionOwner: "provider_admin",
      operatorAction: "Configure the provider to support an MCP protocol version compatible with OpenWork.",
    }
  }

  const phase = fallbackPhase
  const category = phase.startsWith("AUTH_")
    ? "oauth_failure"
    : phase.startsWith("MCP_") || phase.startsWith("CONTINUITY_")
      ? "mcp_protocol_failure"
      : "connection_failure"
  return {
    phase,
    category,
    code: `MCP_${phase}`,
    retryable: phase === "NETWORK_TCP" || phase === "MCP_TRANSPORT",
    actionOwner: phase.startsWith("AUTH_") ? "organization_admin" : "provider_admin",

View on GitHub (pinned to 2b7df46e8a)

Solutions

1. Ask the provider admin to upgrade (or align) their MCP server to a protocol version compatible with OpenWork.
2. Pin/adjust the negotiated protocolVersion on the provider side to one OpenWork supports and redeploy.
3. Re-test the connection after the provider deploys the compatible MCP SDK version.
4. If you control the bridge, update its initialize handler to echo a supported version instead of a hard-coded one.

Example fix

// before: hard-coded stale protocol version
{ protocolVersion: '2024-10-07' }
// after: negotiate a supported version
{ protocolVersion: SUPPORTED_MCP_VERSIONS.includes(req.protocolVersion) ? req.protocolVersion : LATEST_SUPPORTED_MCP_VERSION }

const init = await client.initialize(serverUrl);
if (!SUPPORTED_MCP_VERSIONS.includes(init.protocolVersion)) {
  throw new Error(`Provider protocolVersion ${init.protocolVersion} not supported; supported: ${SUPPORTED_MCP_VERSIONS.join(', ')}`);
}

function isUnsupportedVersion(e: unknown): boolean {
  return typeof e === 'object' && e !== null && /unsupported|unrecognized protocol version/i.test(String((e as Error).message ?? ''));
}

try { await connect(server); } catch (e) {
  if (isUnsupportedVersion(e)) { reportDiagnostic('MCP_UNSUPPORTED_VERSION', { owner: 'provider_admin', retryable: false }); return; }
  throw e;
}

When it happens

Trigger: Connecting to an external MCP server built against an MCP spec revision whose protocolVersion value in the initialize handshake is outside the versions OpenWork negotiates; the provider upgraded or downgraded its MCP SDK; a gateway proxies MCP but rewrites the version field.

Common situations: Provider pinned to an old MCP SDK version while the client moved to a newer protocol revision; provider on a preview/beta protocol version; self-hosted MCP bridge written against an early draft spec; provider bumped versions without notice and cached connections still use stale versions.

Related errors

• unsupported_protocol_version
• MCP_VERSION
• invalid_mcp_token_payload
• invalid_mcp_connection_payload
• OpenWork server cannot read MCP config for this workspace.

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