Authentication

Relevant source files

• src/__tests__/authentication.test.ts
• src/__tests__/config.test.ts
• src/__tests__/helpscout-client.test.ts
• src/utils/helpscout-client.ts

The Help Scout MCP Server utilizes the OAuth2 Client Credentials flow to authenticate with the Help Scout API. This implementation is designed to be stateless, handling token acquisition, caching, and proactive refreshing to ensure uninterrupted tool execution.

OAuth2 Client Credentials Flow

The server identifies itself to Help Scout using a Client ID and Client Secret. Unlike Personal Access Tokens (which are deprecated in this context), the Client Credentials flow is the standard for server-to-server integrations.

Token Acquisition and Expiry

Tokens are acquired via a POST request to the /oauth2/token endpoint src/utils/helpscout-client.ts257-269 The server manages the token lifecycle with the following logic:

• Buffer for Expiry: The server subtracts a 60-second buffer (1 minute) from the expires_in value provided by Help Scout src/utils/helpscout-client.ts265-266 This prevents requests from failing due to token expiration during transit.
• Proactive Refresh: Before every API request, the ensureAuthenticated() method checks if the current token is missing or expired src/utils/helpscout-client.ts237-245

Concurrent Authentication Deduplication

To prevent multiple simultaneous requests from triggering redundant authentication calls (the thundering herd problem), the server uses an authenticationPromise src/utils/helpscout-client.ts108 If an authentication request is already in progress, subsequent calls will await the existing promise instead of initiating new ones src/utils/helpscout-client.ts233-235

Authentication Sequence

The following diagram illustrates the interaction between the HelpScoutClient and the Help Scout Identity Provider.

Authentication Data Flow

Sources: src/utils/helpscout-client.ts106-270

Configuration and Validation

Authentication credentials are provided via environment variables. The server supports both modern and legacy naming conventions for backwards compatibility, though OAuth2 is strictly required.

Credential Mapping

The config object prioritizes modern naming but falls back to legacy variables if necessary:

Internal Property	Primary Env Var	Legacy Fallback
clientId	HELPSCOUT_APP_ID	HELPSCOUT_CLIENT_ID / HELPSCOUT_API_KEY
clientSecret	HELPSCOUT_APP_SECRET	HELPSCOUT_CLIENT_SECRET

Sources: src/__tests__/authentication.test.ts23-57 src/__tests__/helpscout-client.test.ts28-49

Validation Logic

The validateConfig() function (referenced in tests and initialization) ensures that a complete set of credentials exists before the server starts. It enforces the following:

1. Deprecation of Personal Access Tokens: If the legacy HELPSCOUT_API_KEY starts with "Bearer ", the server rejects the configuration as Personal Access Tokens are no longer supported src/__tests__/config.test.ts44-51
2. OAuth2 Presence: Both a clientId and a clientSecret must be resolved from the environment src/__tests__/authentication.test.ts79-108
3. HTTPS Enforcement: The HelpScoutClient constructor calls validateHttpsBaseUrl() to ensure the HELPSCOUT_BASE_URL uses HTTPS to protect credentials in transit src/utils/helpscout-client.ts127 src/utils/helpscout-client.ts174-185

Configuration Entity Mapping

Sources: src/utils/helpscout-client.ts174-185 src/__tests__/authentication.test.ts22-108 src/__tests__/config.test.ts21-78

Implementation Details

HelpScoutClient Class

The HelpScoutClient handles the heavy lifting of authentication state management.

• accessToken: Stores the current JWT src/utils/helpscout-client.ts106
• tokenExpiresAt: A timestamp (ms) indicating when the token should be considered invalid src/utils/helpscout-client.ts107
• ensureAuthenticated(): The internal method that manages the token lifecycle src/utils/helpscout-client.ts231-252
• setupInterceptors(): Registers an Axios request interceptor that calls ensureAuthenticated() and attaches the Authorization: Bearer <token> header to every outgoing request src/utils/helpscout-client.ts282-288

Error Handling and Retries

The client includes specialized logic for handling authentication failures during request execution:

• 401 Handling: If a request fails with a 401 Unauthorized and a client secret is configured, the client identifies this as a retryable condition src/utils/helpscout-client.ts120 It will invalidate the current token and attempt a refresh src/utils/helpscout-client.ts312-316
• Transient Failures: The client retries transient OAuth2 token failures (e.g., 5xx from the identity provider) before giving up on an API request src/__tests__/helpscout-client.test.ts128-158

Sources: src/utils/helpscout-client.ts104-320 src/__tests__/helpscout-client.test.ts160-195