{"record":{"id":"0caef429fdbecd38","repo":"different-ai/openwork","slug":"mcp-unsupported-version","errorCode":"MCP_UNSUPPORTED_VERSION","errorMessage":"Configure the provider to support an MCP protocol version compatible with OpenWork.","messagePattern":"Configure the provider to support an MCP protocol version compatible with OpenWork\\.","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"ee/apps/den-api/src/capability-sources/external-mcp-diagnostics.ts","lineNumber":1382,"sourceCode":"      actionOwner: \"organization_admin\",\n      operatorAction: \"Verify the provider OAuth flow, redirect URI, PKCE, and registered grant/response types.\",\n    }\n  }\n  if (name === \"TemporarilyUnavailableError\" || name === \"ServerError\") {\n    return {\n      phase: fallbackPhase,\n      category: \"oauth_provider_unavailable\",\n      code: name === \"TemporarilyUnavailableError\" ? \"MCP_OAUTH_TEMPORARILY_UNAVAILABLE\" : \"MCP_OAUTH_SERVER_ERROR\",\n      retryable: true,\n      actionOwner: \"provider_admin\",\n      operatorAction: \"Check authorization-server availability and retry with bounded backoff.\",\n    }\n  }\n  if (hasUnsupportedVersionMessage(error)) {\n    return {\n      phase: \"MCP_VERSION\",\n      category: \"mcp_version_mismatch\",\n      code: \"MCP_UNSUPPORTED_VERSION\",\n      retryable: false,\n      actionOwner: \"provider_admin\",\n      operatorAction: \"Configure the provider to support an MCP protocol version compatible with OpenWork.\",\n    }\n  }\n\n  const phase = fallbackPhase\n  const category = phase.startsWith(\"AUTH_\")\n    ? \"oauth_failure\"\n    : phase.startsWith(\"MCP_\") || phase.startsWith(\"CONTINUITY_\")\n      ? \"mcp_protocol_failure\"\n      : \"connection_failure\"\n  return {\n    phase,\n    category,\n    code: `MCP_${phase}`,\n    retryable: phase === \"NETWORK_TCP\" || phase === \"MCP_TRANSPORT\",\n    actionOwner: phase.startsWith(\"AUTH_\") ? \"organization_admin\" : \"provider_admin\",","sourceCodeStart":1364,"sourceCodeEnd":1400,"githubUrl":"https://github.com/different-ai/openwork/blob/2b7df46e8ae1517d64c896c7793d2d52ec845669/ee/apps/den-api/src/capability-sources/external-mcp-diagnostics.ts#L1364-L1400","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ask the provider admin to upgrade (or align) their MCP server to a protocol version compatible with OpenWork.","Pin/adjust the negotiated protocolVersion on the provider side to one OpenWork supports and redeploy.","Re-test the connection after the provider deploys the compatible MCP SDK version.","If you control the bridge, update its initialize handler to echo a supported version instead of a hard-coded one."],"exampleFix":"// before: hard-coded stale protocol version\n{ protocolVersion: '2024-10-07' }\n// after: negotiate a supported version\n{ protocolVersion: SUPPORTED_MCP_VERSIONS.includes(req.protocolVersion) ? req.protocolVersion : LATEST_SUPPORTED_MCP_VERSION }","handlingStrategy":"validation","validationCode":"const init = await client.initialize(serverUrl);\nif (!SUPPORTED_MCP_VERSIONS.includes(init.protocolVersion)) {\n  throw new Error(`Provider protocolVersion ${init.protocolVersion} not supported; supported: ${SUPPORTED_MCP_VERSIONS.join(', ')}`);\n}","typeGuard":"function isUnsupportedVersion(e: unknown): boolean {\n  return typeof e === 'object' && e !== null && /unsupported|unrecognized protocol version/i.test(String((e as Error).message ?? ''));\n}","tryCatchPattern":"try { await connect(server); } catch (e) {\n  if (isUnsupportedVersion(e)) { reportDiagnostic('MCP_UNSUPPORTED_VERSION', { owner: 'provider_admin', retryable: false }); return; }\n  throw e;\n}","preventionTips":["Pin MCP server SDK versions to releases OpenWork supports and test upgrades in staging","Echo negotiated protocolVersion in initialize handlers instead of hard-coding","Add a version compatibility check to provider onboarding","Subscribe to MCP spec/SDK release notes to catch breaking version changes"],"tags":["mcp","protocol-version","compatibility","initialization"],"backgroundTag":"protocol-version-mismatch","analyzedSha":"2b7df46e8ae1517d64c896c7793d2d52ec845669","analyzedAt":"2026-09-01T07:59:23.713Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}