Skip to main content
A credential helper is an executable on the user’s machine that prints an inference token to stdout. Claude Desktop on 3P runs it whenever it needs a credential for the configured inference provider, caches the result for a configurable time, and re-runs it when the credential expires. Use a helper when your token comes from an internal secret broker, a CLI, or an SSO flow that the built-in interactive sign-in options don’t cover. Configure the helper with the inferenceCredentialHelper key; see the Configuration reference for the full list of helper-related keys.

​
What the helper must do

Claude Desktop runs the executable at the configured path with no arguments and reads stdout. The exit code must be 0. Anything written to stderr is logged for diagnostics but otherwise ignored. Stdout must contain exactly one of the following, with no banners, prompts, or log lines mixed in:
  • A single bare token. The whole trimmed stdout becomes the bearer token.
  • A JSON object, when per-request headers are needed: 
    { "token": "...", "headers": { "X-Org-Route": "prod" } }
    Headers from the JSON object are merged over inferenceCustomHeaders; the helper’s value wins on a conflict.

​
When the helper runs

Claude Desktop sets the CLAUDE_HELPER_CONTEXT environment variable on every invocation so the script can decide whether interactive authentication (opening a browser, prompting for a device code) is appropriate.
ValueMeaning
interactiveThe user started a session and is present. Interactive sign-in is acceptable.
mid-session-refreshA running session’s credential expired. Prefer a silent refresh; the user is waiting on a turn.
scheduled-taskA scheduled task started with no user present.
setup-testThe in-app configuration window’s connection test.
backgroundA background probe or health check.
A well-behaved helper should attempt its silent path (cached token, refresh-token grant) for any value other than interactive, and exit non-zero rather than block on user input when that path is exhausted. Claude Desktop treats a non-zero exit as a refresh failure and surfaces it to the user. The legacy variable CLAUDE_HELPER_MANUAL_RUN=1 is also set when CLAUDE_HELPER_CONTEXT is setup-test, for scripts written before the context variable existed. New scripts should branch on CLAUDE_HELPER_CONTEXT instead. The helper runs with a PATH that includes the user’s login-shell PATH and standard install locations in addition to the app’s launch environment, so a script can invoke tools such as aws or gcloud by name even when the app was launched from the Dock or Finder rather than a terminal.

​
Timeouts and caching

The helper’s output is cached for inferenceCredentialHelperTtlSec seconds (default 3600). After expiry it re-runs at the next session start. Each run is bounded by inferenceCredentialHelperTimeoutSec seconds (default 60, maximum 600). When Claude Desktop re-runs the helper to recover a session mid-turn (CLAUDE_HELPER_CONTEXT=mid-session-refresh), the timeout is additionally clamped to 20 seconds so a slow helper can’t stall the turn. A helper’s silent path should comfortably finish within that window.

​
Turn off mid-session re-runs

By default, when a running session’s credential is rejected, Claude Desktop re-runs the helper with CLAUDE_HELPER_CONTEXT=mid-session-refresh to recover without interrupting the user. If your helper can’t run safely outside the interactive context, set inferenceCredentialHelperSilentRefreshEnabled to false. Claude Desktop then keeps the cached credential until the next session start and surfaces an expiry prompt instead of re-running the helper mid-session.