{"record":{"id":"6674d8d5e7ed91ee","repo":"different-ai/openwork","slug":"mcp-oauth-configuration-required-6674d8","errorCode":"mcp_oauth_configuration_required","errorMessage":"Failed to start OAuth (${response.status}).","messagePattern":"Failed to start OAuth \\((.+?)\\)\\.","errorType":"exception","errorClass":"McpOAuthConfigurationRequiredError","httpStatus":null,"severity":"error","filePath":"ee/apps/den-web/app/(den)/dashboard/_components/mcp-connections-data.tsx","lineNumber":890,"sourceCode":"    },\n  });\n}\n\nexport function useStartMcpConnectionOAuth() {\n  const { orgId } = useOrgDashboard();\n\n  return useMutation({\n    mutationFn: async (connectionId: string): Promise<{ status: \"connected\" | \"needs_auth\"; authorizeUrl: string | null }> => {\n      const { response, payload } = await requestJson(\n        `/v1/mcp-connections/${encodeURIComponent(connectionId)}/connect/start`,\n        { headers: getOrgScopeHeaders(requireOrgId(orgId)) },\n        20000,\n      );\n      if (!response.ok) {\n        const details = mcpOAuthStartDebugDetails(payload, response.status);\n        const requestError = getRequestError(payload, response, `Failed to start OAuth (${response.status}).`);\n        if (details.errorCode === \"mcp_oauth_configuration_required\") {\n          throw new McpOAuthConfigurationRequiredError(\n            requestError.message,\n            details,\n          );\n        }\n        throw new McpOAuthStartError(requestError.message, details);\n      }\n      return payload as { status: \"connected\" | \"needs_auth\"; authorizeUrl: string | null };\n    },\n  });\n}\n\nexport function useDisconnectMyProviderAccount() {\n  const queryClient = useQueryClient();\n  const { orgId } = useOrgDashboard();\n\n  return useMutation({\n    mutationFn: async (connection: Pick<ExternalMcpConnection, \"id\" | \"nativeProviderKey\">): Promise<string> => {\n      const path = isNativeProviderConnectionId(connection.id, connection.nativeProviderKey)","sourceCodeStart":872,"sourceCodeEnd":908,"githubUrl":"https://github.com/different-ai/openwork/blob/2b7df46e8ae1517d64c896c7793d2d52ec845669/ee/apps/den-web/app/(den)/dashboard/_components/mcp-connections-data.tsx#L872-L908","documentation":"Thrown by getRequestError when the POST that starts MCP OAuth returns a non-2xx status. When the payload's debug details carry errorCode 'mcp_oauth_configuration_required', the message is wrapped in McpOAuthConfigurationRequiredError so the UI can prompt an admin to configure the provider's OAuth client; otherwise it becomes a generic McpOAuthStartError.","triggerScenarios":"POST to the MCP OAuth start endpoint (20s timeout) returns 4xx/5xx with payload errorCode 'mcp_oauth_configuration_required' — the MCP server/org has no OAuth client configured for this connection.","commonSituations":"Org admin never registered the OAuth client for the MCP provider; providerId changed after provider reconfiguration; environment (self-hosted Den) missing OAuth client env vars; response also carries status/debug details used by mcpOAuthStartDebugDetails.","solutions":["Configure the MCP provider's OAuth client in Den (client ID/secret/tenant) so the start endpoint can mint an authorize URL","Inspect mcpOAuthStartDebugDetails(payload, status) in the thrown error for the exact missing configuration field","Catch McpOAuthConfigurationRequiredError in the UI and show the admin-configuration prompt instead of a generic failure","If self-hosted, set the provider OAuth env vars on the Den server and restart","Retry after configuration — the error is not transient"],"exampleFix":"// before\nthrow new McpOAuthConfigurationRequiredError(requestError.message, details);\n// after (caller)\ntry { await startOAuth(connnectionId); }\ncatch (e) {\n  if (e instanceof McpOAuthConfigurationRequiredError) {\n    openOAuthConfigDialog(e.details);\n    return;\n  }\n  throw e;\n}","handlingStrategy":"try-catch","validationCode":"// before starting OAuth, check the provider client is configured\nconst client = await fetchNativeProviderClient(providerId);\nif (!client.configured) {\n  openOAuthConfigurationDialog(providerId);\n  return;\n}","typeGuard":"function isMcpOAuthConfigurationRequired(e: unknown): e is McpOAuthConfigurationRequiredError {\n  return e instanceof McpOAuthConfigurationRequiredError;\n}","tryCatchPattern":"try {\n  await startOAuth.mutateAsync(connectionId);\n} catch (e) {\n  if (e instanceof McpOAuthConfigurationRequiredError) {\n    openOAuthConfigurationDialog(e.details);\n    return;\n  }\n  showToast({ variant: 'error', title: 'OAuth could not start', description: e instanceof Error ? e.message : String(e) });\n}","preventionTips":["Provision OAuth clients (client ID/secret/tenant) for every MCP provider before onboarding connections","Surface client.configured state in the UI before offering 'Connect'","Document required OAuth env vars for self-hosted Den","Treat mcp_oauth_configuration_required as actionable, not retryable"],"tags":["oauth","mcp","configuration","http-error"],"backgroundTag":"oauth-not-configured","analyzedSha":"2b7df46e8ae1517d64c896c7793d2d52ec845669","analyzedAt":"2026-09-01T07:59:23.713Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}