danny-avila/LibreChat · warning · Error

[MCP][${serverName}][${toolName}] OAuth authentication requi

Error message

[MCP][${serverName}][${toolName}] OAuth authentication required. Please check the server logs for the authentication URL.

What it means

In the MCP tool _call catch block (MCP.js:1148), when an auth-class error occurs and either OAuth machinery IS configured or an OAuth flow signal was emitted, the tool surfaces this message directing the user to the auth URL in the server logs. Unlike 149, this is the expected mid-flow state: the OAuth dance has started or is pending, and the operator must complete it.

Source

Thrown at api/server/services/MCP.js:1148

        error.message?.includes('401') ||
        error.message?.includes('OAuth') ||
        error.message?.includes('authentication') ||
        error.message?.includes('Non-200 status code (401)');
      const isOAuthFlowSignal =
        error.message === 'OAuth flow initiated - return early' ||
        error.message === 'Pending OAuth flow reused - return early';

      if (isOAuthError) {
        if (
          capturedServerConfig &&
          !requiresOAuthMachinery(capturedServerConfig) &&
          !isOAuthFlowSignal
        ) {
          throw new Error(
            `[MCP][${serverName}][${toolName}] upstream authentication failed; MCP OAuth is not configured for this server.`,
          );
        }
        throw new Error(
          `[MCP][${serverName}][${toolName}] OAuth authentication required. Please check the server logs for the authentication URL.`,
        );
      }

      throw new Error(
        `[MCP][${serverName}][${toolName}] tool call failed${error?.message ? `: ${error?.message}` : '.'}`,
      );
    }
  };

  const toolInstance = tool(_call, {
    schema,
    name: normalizedToolKey,
    description: description || '',
    responseFormat: AgentConstants.CONTENT_AND_ARTIFACT,
  });
  toolInstance.mcp = true;
  toolInstance.mcpRawServerName = serverName;

View on GitHub (pinned to 5ff282f900)

Solutions

Read the server logs for the authentication URL printed for this server/user and complete the consent in the browser.
If no URL appears, raise log verbosity and confirm the OAuth flow actually started (check oauthStart/oauthEnd wiring).
After completing consent, retry the tool call — the token should now be cached.

Defensive patterns

Strategy: try-catch

Try / catch

try {
  await callMcpTool(...);
} catch (e) {
  if (/OAuth authentication required/.test(e.message)) {
    const url = await pollLogsForAuthUrl(serverName, runId);
    return redirectTo(url);
  }
  throw e;
}

Prevention

Surface the auth URL from server logs to the user in-product, not just in logs.
After consent, retry automatically since the token is cached.
Monitor token expiry and refresh proactively to reduce re-consent prompts.

When it happens

Trigger: The MCP server returned 401/auth error and LibreChat has OAuth configured, so it initiated (or reused) an OAuth flow and threw 'OAuth flow initiated - return early'. The user must visit the printed authentication URL to authorize the MCP server.

Common situations: First tool call against a freshly added OAuth-backed MCP server. A previously authorized token expired and the refresh failed, forcing re-auth. Multiple users; one user has not yet completed consent.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

AI-assisted analysis of danny-avila/LibreChat@5ff282f900 (2026-08-12). Data as JSON: /api/errors/31393d5dfbc96f5c. Report an issue: GitHub.