different-ai/openwork · error · McpOAuthConfigurationRequiredError

mcp_oauth_configuration_required

mcp_oauth_configuration_required

Error message

Failed to start OAuth (${response.status}).

What it means

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.

Source

Thrown at ee/apps/den-web/app/(den)/dashboard/_components/mcp-connections-data.tsx:890

    },
  });
}

export function useStartMcpConnectionOAuth() {
  const { orgId } = useOrgDashboard();

  return useMutation({
    mutationFn: async (connectionId: string): Promise<{ status: "connected" | "needs_auth"; authorizeUrl: string | null }> => {
      const { response, payload } = await requestJson(
        `/v1/mcp-connections/${encodeURIComponent(connectionId)}/connect/start`,
        { headers: getOrgScopeHeaders(requireOrgId(orgId)) },
        20000,
      );
      if (!response.ok) {
        const details = mcpOAuthStartDebugDetails(payload, response.status);
        const requestError = getRequestError(payload, response, `Failed to start OAuth (${response.status}).`);
        if (details.errorCode === "mcp_oauth_configuration_required") {
          throw new McpOAuthConfigurationRequiredError(
            requestError.message,
            details,
          );
        }
        throw new McpOAuthStartError(requestError.message, details);
      }
      return payload as { status: "connected" | "needs_auth"; authorizeUrl: string | null };
    },
  });
}

export function useDisconnectMyProviderAccount() {
  const queryClient = useQueryClient();
  const { orgId } = useOrgDashboard();

  return useMutation({
    mutationFn: async (connection: Pick<ExternalMcpConnection, "id" | "nativeProviderKey">): Promise<string> => {
      const path = isNativeProviderConnectionId(connection.id, connection.nativeProviderKey)

View on GitHub (pinned to 2b7df46e8a)

Solutions

1. Configure the MCP provider's OAuth client in Den (client ID/secret/tenant) so the start endpoint can mint an authorize URL
2. Inspect mcpOAuthStartDebugDetails(payload, status) in the thrown error for the exact missing configuration field
3. Catch McpOAuthConfigurationRequiredError in the UI and show the admin-configuration prompt instead of a generic failure
4. If self-hosted, set the provider OAuth env vars on the Den server and restart
5. Retry after configuration — the error is not transient

Example fix

// before
throw new McpOAuthConfigurationRequiredError(requestError.message, details);
// after (caller)
try { await startOAuth(connnectionId); }
catch (e) {
  if (e instanceof McpOAuthConfigurationRequiredError) {
    openOAuthConfigDialog(e.details);
    return;
  }
  throw e;
}

// before starting OAuth, check the provider client is configured
const client = await fetchNativeProviderClient(providerId);
if (!client.configured) {
  openOAuthConfigurationDialog(providerId);
  return;
}

function isMcpOAuthConfigurationRequired(e: unknown): e is McpOAuthConfigurationRequiredError {
  return e instanceof McpOAuthConfigurationRequiredError;
}

try {
  await startOAuth.mutateAsync(connectionId);
} catch (e) {
  if (e instanceof McpOAuthConfigurationRequiredError) {
    openOAuthConfigurationDialog(e.details);
    return;
  }
  showToast({ variant: 'error', title: 'OAuth could not start', description: e instanceof Error ? e.message : String(e) });
}

When it happens

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

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

Related errors

• MCP_OAUTH_CONFIGURATION_REQUIRED
• Failed to start OAuth (${response.status}).
• MCP_OAUTH_METHOD_NOT_ALLOWED
• OpenWork-managed MCP OAuth is currently available for local
• OpenWork-managed OAuth requires a remote MCP URL.

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