Switching to headersHelper in Claude Code broke auth for project-scoped catalogs only

The half day went to credential non-inheritance

The helper worked at user scope and failed under a project. I assumed it was the trust dialog and spent a long time looking in that direction.

The real cause was elsewhere. A headersHelper that comes from a project, a plugin, or an agent file runs without the inherited credential environment variables. Helpers at user, managed, or claude.ai scope run from the Claude config directory, under different assumptions entirely.

The intent is to close the path where a config file committed to a repository walks out the door still holding your keys. That reasoning holds up. The catch is that if your helper reads a token from an environment variable, the difference is invisible for as long as you only test at user scope.

To see the behavior directly, I ran the same script with the inherited environment stripped.

# A naive helper that reads the token from the environment
cat << 'EOF' > headers-env.sh
#!/usr/bin/env bash
set -euo pipefail
: "${CATALOG_TOKEN:?CATALOG_TOKEN is not set}"
printf '{"Authorization":"Bearer %s"}\n' "$CATALOG_TOKEN"
EOF
chmod +x headers-env.sh
 
# (1) With the environment present - passes
CATALOG_TOKEN=demo123 ./headers-env.sh
# => {"Authorization":"Bearer demo123"}
 
# (2) With inheritance stripped - approximates a project-scoped helper
env -i HOME="$HOME" PATH="$PATH" ./headers-env.sh; echo "exit=$?"
# => headers-env.sh: line 3: CATALOG_TOKEN: CATALOG_TOKEN is not set
# => exit=1

Strip the environment with env -i and the same script exits 1. That is what happened on my machine, and matching that symptom against the project-scope failure is what finally pointed me at the cause.

One line, run before distributing, would have saved the half day. Write the helper, then confirm it survives without an inherited environment. That was the expensive lesson here.

Move credential retrieval inside the helper

The fix is unglamorous: stop depending on the environment and have the helper pull from a credential store itself.

cat << 'EOF' > headers-store.sh
#!/usr/bin/env bash
set -euo pipefail
 
# The helper reads from a store rather than the environment
TOKEN=""
 
# Prefer the macOS keychain when it exists
if command -v security >/dev/null 2>&1; then
  TOKEN="$(security find-generic-password -a "$USER" -s claude-catalog -w 2>/dev/null || true)"
fi
 
# Fallback for environments without a keychain (CI, containers)
if [ -z "$TOKEN" ]; then
  STORE="${HOME}/.config/claude-catalog/token"
  TOKEN="$(cat "$STORE" 2>/dev/null || true)"
fi
 
if [ -z "$TOKEN" ]; then
  echo "catalog token not found (keychain / ~/.config/claude-catalog/token)" >&2
  exit 1
fi
 
printf '{"Authorization":"Bearer %s"}\n' "$TOKEN"
EOF
chmod +x headers-store.sh
 
# Confirm it passes with no inherited environment
env -i HOME="$HOME" PATH="$PATH" ./headers-store.sh; echo "exit=$?"
# => {"Authorization":"Bearer ..."}
# => exit=0

Set chmod 600 on the fallback file. Naming the locations you searched in the stderr message pays off more than it looks like it should: a helper that silently returns nothing looks identical to an authentication failure from the caller's side, and separating the two costs real time.

The command -v security branch exists because I wanted one helper for both a macOS workstation and a container. Writing it keychain-only means editing it again on the container side every time.

Mint short-lived tokens per request

Swapping a fixed token into a store reduces the pain of rotation but leaves the lifetime problem intact. Since the helper runs on every fetch anyway, minting something short-lived right there is the natural move.

What I settled on for repository distribution is a signed JWT valid for five minutes, generated fresh each time.

cat << 'EOF' > headers-jwt.sh
#!/usr/bin/env bash
set -euo pipefail
 
KEY="${CATALOG_SIGNING_KEY:-$HOME/.config/claude-catalog/key.pem}"
[ -f "$KEY" ] || { echo "signing key not found: $KEY" >&2; exit 1; }
 
b64() { openssl base64 -A | tr '+/' '-_' | tr -d '='; }
 
NOW=$(date +%s)
HEADER=$(printf '{"alg":"RS256","typ":"JWT"}' | b64)
PAYLOAD=$(printf '{"iss":"catalog-client","exp":%d}' $((NOW + 300)) | b64)
SIG=$(printf '%s.%s' "$HEADER" "$PAYLOAD" | openssl dgst -sha256 -sign "$KEY" | b64)
 
printf '{"Authorization":"Bearer %s.%s.%s"}\n' "$HEADER" "$PAYLOAD" "$SIG"
EOF
chmod +x headers-jwt.sh

The 300-second exp accounts for the catalog fetch and the archive fetches running back to back. Shorten it too far and the token expires mid-retrieval.

CATALOG_SIGNING_KEY can override the key path, but the part that matters is that the default is a fixed path under the home directory. Given the previous section, the helper has to work from its defaults alone, with no environment variable arriving.

Measure the cost before choosing

The helper runs on every fetch, and the number of fetches grows with the number of plugins, so measuring once makes the decision easy. Twenty runs each, on a Linux container with OpenSSL 3:

Sixteen milliseconds apart. With dozens of plugins installed, that is not a difference anyone feels. Signing cost was the thing I had been wary of going in, and it turned out not to be the thing that matters.

What does matter is what happens if you call an external service to issue the token. A full network round trip lands in a code path that runs on every fetch, and the order of magnitude changes. If you can sign locally, sign locally.

My working rule:

1. If the only consumers are you and your own machines, a static read from a store is enough
2. If consumers multiply, or you want revocation to mean something, sign short-lived tokens locally
3. Reserve an external issuing service for cases where immediate revocation is genuinely required

Sometimes you want to know which scope's helper actually answered. The fetch path parses the helper's stdout directly, so mixing debug output into it breaks the request. Anything you add belongs on stderr.

# stdout stays pure JSON; diagnostics go to stderr
echo "[headers-store] scope=$(basename "$PWD") store=keychain" >&2

$PWD reflects where the helper was launched from, which distinguishes a user-scope run from one under a project directory. Adding that single line ended my confusion about scopes for good. One caution: never write the token itself to stderr. It lands in logs.

Trust approval is now a precondition

One more change matters for unattended setups. A headersHelper in a project's .mcp.json, and inline MCP servers written into project or --add-dir agent files, now require that folder's trust dialog to have been approved. Running with claude -p is treated the same way.

On my side this bit exactly once, in a freshly created checkout used for CI. A single human approval clears it permanently, so it is not an ongoing obstacle. But if your setup recreates the folder each time, it bites each time.

I moved the working checkout to a fixed path. A design that treats folders as disposable does not sit well with trust granted per folder, and adjusting the execution environment is the cheaper side to change.

Having this table on day one would have saved me the half day. Once you know the assumptions differ by scope, the diagnosis takes minutes.

What to do next

If you keep your own catalog in a private repository with the token written into a config file, write one helper and run env -i HOME="$HOME" PATH="$PATH" ./headers-store.sh against it. Pass that, and the helper works at any scope. Fail it, and there is still an environment dependency hiding somewhere.

Doing that check before the migration matters more than the migration itself. I did it in the wrong order and paid half a day for the privilege. If this saves someone else the same afternoon, it was worth writing down.