{"record":{"id":"ffc2fee8a75a6a63","repo":"different-ai/openwork","slug":"mcp-provider-auth-required","errorCode":"MCP_PROVIDER_AUTH_REQUIRED","errorMessage":"MCP_PROVIDER_AUTH_REQUIRED","messagePattern":"MCP_PROVIDER_AUTH_REQUIRED","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"ee/apps/den-api/src/capability-sources/external-mcp-diagnostics.ts","lineNumber":485,"sourceCode":"function providerDeclaredErrorFromJson(\n  value: unknown,\n  phase: ExternalMcpDiagnosticPhase,\n): ProviderDeclaredErrorEvidence | null {\n  if (Array.isArray(value)) {\n    for (const item of value) {\n      const evidence = providerDeclaredErrorFromEnvelope(item, phase)\n      if (evidence) return evidence\n    }\n    return null\n  }\n  return providerDeclaredErrorFromEnvelope(value, phase)\n}\n\nfunction providerAuthorizationClassification(connectUrl: string): Classification {\n  return {\n    phase: \"PROVIDER_AUTHORIZATION\",\n    category: \"provider_authorization_required\",\n    code: \"MCP_PROVIDER_AUTH_REQUIRED\",\n    retryable: false,\n    actionOwner: \"member\",\n    operatorAction: \"Connect your account for this provider using its sign-in link, then retry this capability.\",\n    connectUrl,\n  }\n}\n\nfunction providerDeclaredErrorClassification(): Classification {\n  return {\n    phase: \"PROVIDER_EXECUTION\",\n    category: \"provider_declared_error\",\n    code: \"MCP_PROVIDER_DECLARED_ERROR\",\n    retryable: false,\n    actionOwner: \"provider_admin\",\n    operatorAction: \"Look up the provider-declared JSON-RPC error code with the provider, then correct the downstream condition and retry.\",\n  }\n}\n","sourceCodeStart":467,"sourceCodeEnd":503,"githubUrl":"https://github.com/different-ai/openwork/blob/2b7df46e8ae1517d64c896c7793d2d52ec845669/ee/apps/den-api/src/capability-sources/external-mcp-diagnostics.ts#L467-L503","documentation":"providerAuthorizationClassification in external-mcp-diagnostics.ts produces a diagnostic classification (not an exception) meaning the external MCP provider requires per-user account authorization before the capability can be used. The gateway has connected to the provider but the member's account is not linked, so calls are rejected with category provider_authorization_required.","triggerScenarios":"A capability backed by an external MCP provider is executed while the requesting member has not completed OAuth/account linking for that provider; the gateway classifies the failure with connectUrl pointing to the provider's sign-in flow.","commonSituations":"First use of a connector before sign-in; an OAuth token was revoked or expired server-side; an admin added a new provider that members have not yet linked; sign-in flow was abandoned midway.","solutions":["Open the connectUrl from the diagnostic and complete the provider's sign-in/OAuth flow, then retry the capability","If the token expired or was revoked, re-authorize via the same connect link","Verify with the org admin that the provider connection is enabled for your account","After re-authenticating, re-run search_capabilities/execute_capability to confirm resolution"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Before executing a capability, check prior diagnostics/connection state:\n// if (connection.diagnostics.some(d => d.code === \"MCP_PROVIDER_AUTH_REQUIRED\")) {\n//   prompt user to open connection.connectUrl and sign in\n// }","typeGuard":"function needsProviderAuth(d: { code: string; connectUrl?: string }): d is { code: \"MCP_PROVIDER_AUTH_REQUIRED\"; connectUrl: string } {\n  return d.code === \"MCP_PROVIDER_AUTH_REQUIRED\" && typeof (d as { connectUrl?: string }).connectUrl === \"string\"\n}","tryCatchPattern":"try {\n  await executeCapability(capability, input)\n} catch (err) {\n  if (err instanceof Error && err.message.includes(\"MCP_PROVIDER_AUTH_REQUIRED\")) {\n    console.log(\"Connect your provider account:\", diagnostic.connectUrl)\n    // surface sign-in link to the member, then retry after authorization\n  } else throw err\n}","preventionTips":["Prompt members to complete provider sign-in right after adding a connector","Proactively check token expiry and re-auth before calls fail","Surface connectUrl in your UI as soon as provider_authorization_required appears","After re-auth, verify with a cheap capability listing before retrying heavy operations"],"tags":["mcp","oauth","authorization","provider"],"backgroundTag":"oauth-authorization-required","analyzedSha":"2b7df46e8ae1517d64c896c7793d2d52ec845669","analyzedAt":"2026-09-01T07:59:23.713Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}