Auth and keys
Claude Code headersHelper: read the MCP key from a secret store
Set up Claude Code's headersHelper so a remote MCP server's bearer key comes from Keychain or libsecret at connect time, not from a file or an env variable.
By Lucian Dyer, FetchMCP team · Published
This article was drafted with AI assistance from the sources listed below and edited and published by the FetchMCP team. Disclosure: the FetchMCP API, which this article mentions, is this site's own product.
- 1Store the keySave it once in Keychain or libsecret under the server name, fetchmcp.
- 2Write the helperA script that prints a JSON object with an Authorization header to stdout.
- 3Point the config at itSet headersHelper to the script's absolute path in .mcp.json.
- 4Trust the folderProject and local-scope helpers run only after the trust dialog.
- 5Rotate in the storeUpdate the stored key, then reconnect from /mcp to re-run the helper.
Your fetch server needs Authorization: Bearer <key>. Putting the key in .mcp.json puts it in git as soon as the file is committed. A ${VAR} reference keeps it out of the file, but the key still has to be set somewhere in your environment. headersHelper is the third option: Claude Code runs a command when it connects, and the command prints the headers.
Checked against the Claude Code MCP docs on 2026-11-20.
What the helper must do
headersHelper is a field on an http server entry. Its value is a command. Claude Code runs it in a shell and expects a JSON object of string key-value pairs on stdout:
{"Authorization": "Bearer YOUR_KEY"}
The rules from the docs:
- 10 seconds. Claude Code gives up on the command after that.
- Fresh every time. It runs at session start and on every reconnect. Nothing is cached, so any token reuse is the script's job.
- Dynamic wins. A header the helper returns overrides a static
headersentry with the same name. - No OAuth fallback. When the output includes
Authorization, Claude Code uses that as the server's authentication. - One retry on 401 or 403. If a tool call fails with either status, Claude Code re-runs the helper, reconnects and retries the call once. Only if that retry fails too does
/mcpmark the server as needing authentication.
Why the helper cannot read your key variable
FETCHMCP_API_KEY looks like the obvious source. For a project .mcp.json, it is not available.
A helper that a repository or plugin supplies is a command you did not write. So for servers in a project .mcp.json or a plugin, Claude Code runs the helper without any environment variable whose name looks like a credential. The docs give the pattern: TOKEN, SECRET, PASSWORD, KEY or AUTH anywhere in the name, in either case. FETCHMCP_API_KEY matches.
Servers at user or local scope keep those variables. The docs' advice for the stripped case is to read the credential from a file or a credential store. That is also the better habit at any scope.
Store the key once
security add-generic-password on macOS. -a and -s are required; -w at the end makes it prompt for the value, which the man page recommends:
security add-generic-password -a "$USER" -s fetchmcp -w
secret-tool store on Linux with libsecret. It requires a --label and prompts for the password:
secret-tool store --label='FetchMCP API key' service fetchmcp
Both commands prompt for the value instead of taking it as an argument.
One helper for every server
CLAUDE_CODE_MCP_SERVER_NAME is set for the helper, along with CLAUDE_CODE_MCP_SERVER_URL. The docs suggest using them so one script serves several servers. Store each key under its server name and the script needs no edits per server:
#!/bin/sh
# mcp-headers.sh: print an Authorization header for the MCP server Claude Code is connecting to
name="$CLAUDE_CODE_MCP_SERVER_NAME"
if command -v security >/dev/null 2>&1; then
key=$(security find-generic-password -s "$name" -w) || exit 1
else
key=$(secret-tool lookup service "$name") || exit 1
fi
printf '{"Authorization": "Bearer %s"}\n' "$key"
find-generic-password -w prints only the password. secret-tool lookup prints the stored secret and returns non-zero on failure.
Make it executable and test it without printing the key:
chmod +x /usr/local/bin/mcp-headers.sh
CLAUDE_CODE_MCP_SERVER_NAME=fetchmcp /usr/local/bin/mcp-headers.sh \
| python3 -c 'import json, sys; print(list(json.load(sys.stdin)))'
The output should be ['Authorization'].
Point the config at it
Use an absolute path. Claude Code picks the helper's working directory from where the server is configured, and a cd during the session does not move it, so a relative path breaks easily:
{
"mcpServers": {
"fetchmcp": {
"type": "http",
"url": "https://fetchmcp.net/mcp",
"headersHelper": "/usr/local/bin/mcp-headers.sh"
}
}
}
This file holds no secret and no variable name, so it is safe to commit. Each developer stores their own key under fetchmcp and installs the same script.
Trust the folder first
headersHelper is an arbitrary shell command, so Claude Code is careful about where it comes from. For a server in a project .mcp.json or at local scope, the helper runs only after you accept the trust dialog for that project directory. Trust on a parent folder does not count.
Until then, Claude Code connects with the static headers alone. With no static Authorization, the server sees no key. In a claude -p or SDK session you also get one headersHelper not run line per server on stderr.
For a non-interactive setup, the docs name projects["<path>"].hasTrustDialogAccepted set to true in ~/.claude.json.
When the server still says 401
If the server rejects the helper's credential while connecting, Claude Code reports a failed connection, not a server that needs authentication. Work through it in order:
- Run the script by hand with the test above. A JSON error means the store lookup failed.
['Authorization']does not prove the key is non-empty, so check that the stored entry has a value. - Check the name. The stored entry must match the server key in
.mcp.json, herefetchmcp. - Check the time. If your secret store asks you to unlock it, unlock it before you start Claude Code; the helper has 10 seconds.
- Fix the stored key, then reconnect from
/mcpto run the helper again.
The same step is your rotation routine: update the entry in the store, reconnect, done. No config file changes. For the ${VAR} route and its own traps, see the empty Bearer header post. Bearer keys, OAuth and rotation in general are in the authentication guide.
Try it with a real server
FetchMCP API runs a remote MCP server over Streamable HTTP and authenticates it with Authorization: Bearer <key>, the same key as its REST API. The MCP server registers 2 tools. Store the key under fetchmcp and the config above works as written. Failed fetches cost 0 credits. Current configs are in the MCP docs.
Frequently asked questions
What does headersHelper do in Claude Code?
It is a command set on an MCP server entry. Claude Code runs it in a shell when it connects to the server and on reconnect, reads a JSON object of string key-value pairs from its stdout, and merges those into the request headers. Dynamic headers override static headers with the same name.
How long can a headersHelper take?
Claude Code gives up on the command after 10 seconds. The result is not cached, so the helper runs again on every connection.
Why can't my headersHelper read FETCHMCP_API_KEY from the environment?
For a server in a project .mcp.json or a plugin, Claude Code runs the helper without environment variables whose names look like credentials, such as names containing KEY, TOKEN, SECRET, PASSWORD or AUTH. Have the helper read the key from a file or a credential store instead.
Why does my headersHelper not run?
For a server in a project .mcp.json or at local scope, Claude Code runs the helper only after you accept the trust dialog for the project folder. Until then it connects with the static headers alone. In a claude -p or SDK session it prints a headersHelper not run line to stderr.
Sources
- Connect Claude Code to tools via MCP (Claude Code docs) (Documentation)
- security(1) man page (macOS) (Documentation)
- secret-tool(1) man page (Debian) (Documentation)