Write a credential helper changedthird-party/claude-desktop/credential-helper
Nearest release: v2.1.309, published under an hour after upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 22 Oct 2026 20:16 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 23 Oct 2026 18:07 UTC.
Upstream edited
Recorded here
Lines+6added
Lines−6removed
From line
4
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits10to this page, all time
The whole hunk
from line 4, old and new numbered
/
from line 4
44
55A 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.
66
7Configure the helper with the `inferenceCredentialHelper` key; see the [Configuration reference](/docs/third-party/claude-desktop/configuration.md#inferencecredentialhelper) for the full list of helper-related keys.
7Configure the helper with the `inferenceCredentialHelper` key; see the [Configuration reference](https://claude.com/docs/third-party/claude-desktop/configuration.md#inferencecredentialhelper) for the full list of helper-related keys.
88
99> [!NOTE]
1010>
11> `inferenceCredentialHelper` supplies credentials for the inference connection only. An MCP server deployed through [`managedMcpServers`](/docs/third-party/claude-desktop/configuration#managedmcpservers) uses the separate per-server `headersHelper` key, which follows the same execution model but prints a flat JSON header map and has its own cache and renewal settings (`headersHelperTtlSec`, default 300, versus `inferenceCredentialHelperTtlSec`, default 3600). See [Short-lived credentials with a headers helper](/docs/third-party/claude-desktop/extensions.md#short-lived-credentials-with-a-headers-helper).
11> `inferenceCredentialHelper` supplies credentials for the inference connection only. An MCP server deployed through [`managedMcpServers`](https://claude.com/docs/third-party/claude-desktop/configuration#managedmcpservers) uses the separate per-server `headersHelper` key, which follows the same execution model but prints a flat JSON header map and has its own cache and renewal settings (`headersHelperTtlSec`, default 300, versus `inferenceCredentialHelperTtlSec`, default 3600). See [Short-lived credentials with a headers helper](https://claude.com/docs/third-party/claude-desktop/extensions.md#short-lived-credentials-with-a-headers-helper).
1212
1313## What the helper must do
1414
from line 23
2323 { "token": "...", "headers": { "X-Org-Route": "prod" } }
2424 ```
2525
26 Headers from the JSON object are merged over [`inferenceCustomHeaders`](/docs/third-party/claude-desktop/configuration#inferencecustomheaders); the helper's value wins on a conflict.
26 Headers from the JSON object are merged over [`inferenceCustomHeaders`](https://claude.com/docs/third-party/claude-desktop/configuration#inferencecustomheaders); the helper's value wins on a conflict.
2727
2828## Pass arguments to the helper
2929
30Set [`inferenceCredentialHelperArgs`](/docs/third-party/claude-desktop/configuration#inferencecredentialhelperargs) to a JSON array of strings to pass arguments to the helper. Claude Desktop passes each entry to the executable as one argument, in order and exactly as written. One installed script can then serve users whose configurations differ, for example by environment or tenant. This configuration runs `/usr/local/bin/corp-cred-helper --environment production`:
30Set [`inferenceCredentialHelperArgs`](https://claude.com/docs/third-party/claude-desktop/configuration#inferencecredentialhelperargs) to a JSON array of strings to pass arguments to the helper. Claude Desktop passes each entry to the executable as one argument, in order and exactly as written. One installed script can then serve users whose configurations differ, for example by environment or tenant. This configuration runs `/usr/local/bin/corp-cred-helper --environment production`:
3131
3232```json theme={null}
3333{
from line 36
3636}
3737```
3838
39In a macOS configuration profile or the Windows registry, write the array as a JSON string, as with the other [array-typed keys](/docs/third-party/claude-desktop/configuration-format.md#value-types). A [bootstrap server](/docs/third-party/claude-desktop/bootstrap.md) can deliver `inferenceCredentialHelperArgs` too, under the same [user-consent rule](/docs/third-party/claude-desktop/bootstrap.md#keys-that-require-user-consent) as the helper path. In the nested response format ([`bootstrap-config-v2`](/docs/third-party/claude-desktop/bootstrap#response-schema)), set `args` next to `command` in `inference.credential`.
39In a macOS configuration profile or the Windows registry, write the array as a JSON string, as with the other [array-typed keys](https://claude.com/docs/third-party/claude-desktop/configuration-format.md#value-types). A [bootstrap server](https://claude.com/docs/third-party/claude-desktop/bootstrap.md) can deliver `inferenceCredentialHelperArgs` too, under the same [user-consent rule](https://claude.com/docs/third-party/claude-desktop/bootstrap.md#keys-that-require-user-consent) as the helper path. In the nested response format ([`bootstrap-config-v2`](https://claude.com/docs/third-party/claude-desktop/bootstrap#response-schema)), set `args` next to `command` in `inference.credential`.
4040
4141On Windows, a `.cmd` or `.bat` helper receives each argument wrapped in double quotes, so read the values with `%~1`, `%~2`, and so on to remove the quotes. A `.ps1` helper, a `.exe` helper, and helpers on macOS and Linux receive each value as written.
4242
from line 46
4646
4747## Use a different helper path on Windows
4848
49When one configuration serves both Windows devices and macOS or Linux devices, set `inferenceCredentialHelper` to the macOS and Linux path and [`inferenceCredentialHelperWindows`](/docs/third-party/claude-desktop/configuration#inferencecredentialhelperwindows) to the Windows path, for example `C:\Program Files\Corp\cred-helper.exe`. Windows devices run that executable with the same arguments, timeout, cache time, and environment variables as the main helper, and macOS and Linux devices ignore the key. A [bootstrap server](/docs/third-party/claude-desktop/bootstrap.md) can deliver it under the same [user-consent rule](/docs/third-party/claude-desktop/bootstrap.md#keys-that-require-user-consent) as the helper path; in the nested response format, set `commandWindows` next to `command` in `inference.credential`.
49When one configuration serves both Windows devices and macOS or Linux devices, set `inferenceCredentialHelper` to the macOS and Linux path and [`inferenceCredentialHelperWindows`](https://claude.com/docs/third-party/claude-desktop/configuration#inferencecredentialhelperwindows) to the Windows path, for example `C:\Program Files\Corp\cred-helper.exe`. Windows devices run that executable with the same arguments, timeout, cache time, and environment variables as the main helper, and macOS and Linux devices ignore the key. A [bootstrap server](https://claude.com/docs/third-party/claude-desktop/bootstrap.md) can deliver it under the same [user-consent rule](https://claude.com/docs/third-party/claude-desktop/bootstrap.md#keys-that-require-user-consent) as the helper path; in the nested response format, set `commandWindows` next to `command` in `inference.credential`.
5050
5151## When the helper runs
5252
No line in this hunk matches that.