●CC 2.1.328 — Claude Code 2.1.328 (11/19) fixes saving a scheduled task sometimes wiping your other tasks●SONNET 4.5 — Retires on the Claude API on 11/30, 10 days left. Sweep model IDs in code and saved settings in one pass●USAGE — Users report usage limits running out 3–5x faster since the week of Nov 9●NEW — One Source of Truth for MCP Config Across Claude Code and Gemini CLI●GEMINI API — The Gemini API now has tool retrieval (Preview), loading tool definitions only when needed●CREDIT — Seeing a low Credit balance? First check which billing account it refers to●CC 2.1.328 — Claude Code 2.1.328 (11/19) fixes saving a scheduled task sometimes wiping your other tasks●SONNET 4.5 — Retires on the Claude API on 11/30, 10 days left. Sweep model IDs in code and saved settings in one pass●USAGE — Users report usage limits running out 3–5x faster since the week of Nov 9●NEW — One Source of Truth for MCP Config Across Claude Code and Gemini CLI●GEMINI API — The Gemini API now has tool retrieval (Preview), loading tool definitions only when needed●CREDIT — Seeing a low Credit balance? First check which billing account it refers to
Switching to headersHelper in Claude Code broke auth for project-scoped catalogs only
Moving a private plugin catalog to headersHelper worked at user scope and failed under the project directory. The cause was credential non-inheritance. Here are two working helpers, measured execution costs, and what unattended runs need.
Three mornings that week opened with the same failure notification from an unattended run. Each one traced back to an expired token for the private repository that hosts my own plugin catalog.
As an indie developer I keep one shared set of skills and plugins across both the app side and the site side of my work, stored in a private repository and pulled from several machines and projects. The token lived directly in a config file. Every rotation meant remembering where it was, editing it, and discovering the file I forgot the morning an unattended run fell over.
Claude Code v2.1.238, released in August 2026, added headersHelper to plugin marketplaces, which lets that arrangement go away. A command runs every time the catalog is fetched and returns HTTP headers, so you can hand over a freshly minted, short-lived token instead of a long-lived one.
The migration should have taken half an hour. Instead, a helper that worked perfectly at user scope stopped authenticating the moment it moved under a project directory, and I burned half a day there. The reason makes complete sense in hindsight. I did not see it coming.
I have since reread the official documentation as it stands in November 2026 (the marketplace reference, the hosting guide, the MCP page, and the CLI reference) and revised this piece against it. Two things I believed at the time turned out to be slightly wrong. I've left the corrections in the text rather than quietly swapping them out, because I suspect I'm not the only one who read it that way.
What was actually painful about the token in a config file
With a catalog in a private repository, authentication is needed twice: once to fetch the catalog JSON, and again to fetch the archives it points at. Both used a fixed token.
The annoying part of a fixed token is not the expiry itself. It is that the only channel telling you it expired is an incident. A long-lived token gives no warning at all, and then several machines and several projects fail to fetch at the same moment.
There is also the file. Putting a token in a config file that lives in a repository turns that file into something you can leak. Even at the scale a single indie developer works at, forgetting to keep a project-level .mcp.json out of git is a real possibility.
headersHelper addresses both structurally rather than procedurally.
Where headersHelper actually plugs in
You can attach headersHelper to a URL marketplace definition and to individual catalog entries. The command you name prints a JSON object of headers to stdout, and those headers ride along with the request.
Placement
When it runs
Typical use
URL marketplace (declared in settings, e.g. extraKnownMarketplaces)
Before each fetch of marketplace.json and each archive download on the same origin (scheme, host, port). One run's output is reused for up to 60 seconds
Protecting the catalog as a whole
Catalog entry (in marketplace.json)
Only when that one plugin is installed or updated by itself and the user accepts the displayed command
Splitting distribution per entry. Archive sources only, and "strict": false is required
The important detail is that an entry-level helper does not run silently. claude plugin install and claude plugin update display the command and ask [y/N]. You can skip the prompt with -y, but skipping is a decision a human makes once.
If you run anything unattended, check this first. I missed it initially, and woke up to an install that simply had not happened on the unattended path. The current CLI reference is explicit: when stdin or stdout is not a TTY and you pass neither -y nor --accept-command, the install is refused with exit code 1.
Three exceptions are worth keeping in your head:
-y is ignored when the command runs inside a Claude Code session, such as from the Bash tool or a hook. Run it from your own terminal.
Bulk installs, installs pulled in as a dependency, and background auto-update never run an entry's helper. That plugin alone is left behind and shows up in the /plugin Errors tab.
--accept-command <sha256> (v2.1.271 or later) accepts exactly the command a previous --json run displayed. If the command or the archive URL changed in between, the install is refused outright.
✦
Thank you for reading this far.
Continue Reading
What follows includes implementation code, benchmarks, and practical content we hope you'll find useful. This site runs without ads — server and development costs are supported entirely by members like you. If it's been helpful, we'd be truly grateful for your support.
WHAT YOU'LL LEARN
✦You will know exactly which scope to place a headersHelper in when you move a private plugin catalog to short-lived tokens
✦You will catch the class of helper that works on your machine and dies once distributed, before you ship it to anyone
✦You will be able to choose between a static store read and per-request RS256 minting from measured cost (5 ms vs 21 ms) instead of guesswork
Secure payment via Stripe · Cancel anytime
✦
Unlock This Article
Get full access to the rest of this article. Buy once, read anytime. This site is ad-free — your support goes directly toward keeping it running.
What the helper itself must satisfy (official spec, November 2026)
A helper cannot be just anything. Here are the documented requirements, reordered by how likely I found them to bite.
Item
Requirement
What happens otherwise
Output
One JSON object on stdout, all values strings
The fetch or download it ran for does not happen
Exit
Exit 0 within 10 seconds
Same as above
Command text
At most 500 characters of printable ASCII, no run of four or more spaces
Not accepted as configuration
Execution
Run through sh (cmd.exe on Windows) with the working directory set to ~/.claude or CLAUDE_CONFIG_DIR
Relative paths resolve against the config directory
Variables provided
CLAUDE_CODE_MARKETPLACE_URL and CLAUDE_CODE_MARKETPLACE_NAME for a URL source; CLAUDE_CODE_PLUGIN_NAME and CLAUDE_CODE_PLUGIN_ARCHIVE_URL for an entry
—
URL source scheme
Must use the HTTPS scheme
The helper does not run; only static headers are sent
Redirects
Must stay on the archive URL's origin
The redirected request carries no headers at all
The smallest entry-level setup looks like this. Leave out sha256 and claude plugin validate warns you, so I write the pin and the helper together as a pair.
{ "name": "my-shared-skills", "description": "Shared skills for app and site work", "strict": false, "source": { "source": "archive", "url": "https://catalog.example.com/plugins/my-shared-skills-1.4.0.zip", "sha256": "<SHA-256 of the zip>" }, "headersHelper": "/Users/me/bin/headers-store.sh"}
The absolute path is deliberate. Because the working directory is the config directory, ./headers-store.sh would be looked up inside ~/.claude, not in your project.
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 a repository or plugin brings in runs with every credential-looking environment variable removed. Per the docs, that means any variable whose name contains TOKEN, SECRET, PASSWORD, KEY, or AUTH in either case, plus a fixed list such as ANTHROPIC_CUSTOM_HEADERS.
Which placements are affected differs slightly between the marketplace helper and the MCP helper:
Marketplace: removed for marketplace.json entries and for a project's .claude/settings.json or .claude/settings.local.json. Not removed for user settings, a --settings file, or managed settings.
MCP: removed for a project .mcp.json, a plugin, and inline servers in project or --add-dir agent files. Not removed for user or local scope, managed MCP, or claude.ai connectors.
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 environmentcat << 'EOF' > headers-env.sh#!/usr/bin/env bashset -euo pipefail: "${CATALOG_TOKEN:?CATALOG_TOKEN is not set}"printf '{"Authorization":"Bearer %s"}\n' "$CATALOG_TOKEN"EOFchmod +x headers-env.sh# (1) With the environment present - passesCATALOG_TOKEN=demo123 ./headers-env.sh# => {"Authorization":"Bearer demo123"}# (2) With inheritance stripped - approximates a project-scoped helperenv -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.
Here is the first correction. At the time I believed the whole environment vanished. The documented behavior is filtering by name, as above. env -i is a stricter approximation than reality, which makes it a sufficient test: pass it, and you pass in production. If you want something closer to the real rule, filter by name instead.
# Run with only credential-looking variables removed (approximates the documented rule)run_like_project_scope() { local keep=() while IFS='=' read -r name _; do case "$name" in *[Tt][Oo][Kk][Ee][Nn]*|*[Ss][Ee][Cc][Rr][Ee][Tt]*|*[Pp][Aa][Ss][Ss][Ww][Oo][Rr][Dd]*|*[Kk][Ee][Yy]*|*[Aa][Uu][Tt][Hh]*) ;; *) keep+=("$name=${!name}") ;; esac done < <(env | grep -E '^[A-Za-z_][A-Za-z0-9_]*=') (cd "${CLAUDE_CONFIG_DIR:-$HOME/.claude}" && env -i "${keep[@]}" "$@")}CATALOG_TOKEN=demo123 run_like_project_scope "$PWD/headers-env.sh"; echo "exit=$?"# => CATALOG_TOKEN: CATALOG_TOKEN is not set# => exit=1
The cd into the config directory mirrors the real execution conditions. If a relative path is hiding somewhere in the helper, this is where it shows up.
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.
The helper fetches its own secret and assumes the caller hands it nothing. I now apply that line to marketplace helpers and MCP helpers alike.
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 bashset -euo pipefail# The helper reads from a store rather than the environmentTOKEN=""# Prefer the macOS keychain when it existsif 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)"fiif [ -z "$TOKEN" ]; then echo "catalog token not found (keychain / ~/.config/claude-catalog/token)" >&2 exit 1fiprintf '{"Authorization":"Bearer %s"}\n' "$TOKEN"EOFchmod +x headers-store.sh# Confirm it passes with no inherited environmentenv -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.
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.
And because that name contains KEY, it is always stripped when the helper is called from project settings or marketplace.json, whatever value you set. The override only works when called from user settings. You could rename the variable to slip past the filter, but I settled on "override for local testing, default path in production." Protecting where a secret lives by being clever with variable names felt like something that would confuse me later.
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:
Helper
20 runs
Per run
Notes
Static token read from a store
102 ms
~5 ms
Process spawn and a file read
RS256 JWT signed per request
428 ms
~21 ms
2048-bit key, openssl dgst
Sixteen milliseconds apart. With dozens of plugins installed, that is not a difference anyone feels. A URL source's helper also reuses one run's output for up to 60 seconds, so it actually runs fewer times than there are fetches. 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. On top of that, the helper has a 10-second ceiling, so on a day the issuing service is slow, the catalog fetch itself stops. If you can sign locally, sign locally.
My working rule:
If the only consumers are you and your own machines, a static read from a store is enough
If consumers multiply, or you want revocation to mean something, sign short-lived tokens locally
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 stderrecho "[headers-store] plugin=${CLAUDE_CODE_PLUGIN_NAME:-none} marketplace=${CLAUDE_CODE_MARKETPLACE_NAME:-none} url=${CLAUDE_CODE_MARKETPLACE_URL:-${CLAUDE_CODE_PLUGIN_ARCHIVE_URL:-none}}" >&2
This is the second correction. An earlier version of this piece printed $PWD to tell scopes apart by launch location. Rereading the docs, the helper's working directory is the config directory no matter where it is called from, so $PWD prints the same value every time and tells you nothing about scope. I think I was satisfied with it only because I had been testing at user scope the whole time.
Print the variables Claude Code provides instead. If CLAUDE_CODE_PLUGIN_NAME is set, the call came from a catalog entry; if CLAUDE_CODE_MARKETPLACE_URL is set, it came from a URL source. On the very first fetch after adding a marketplace by URL, CLAUDE_CODE_MARKETPLACE_NAME is empty, so don't be alarmed by that. The one rule that stays: 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. The marketplace side works the same way: a URL-source helper declared in a project's .claude/settings.json does not run until that folder itself is trusted.
The same condition applies under claude -p, and there is a trap in it. A -p or SDK session does not count as accepting trust, and neither does trust granted to a parent folder. Until trust exists, MCP connects with static headers only, and claude -p prints one headersHelper not run line per server to stderr.
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.
For environments that cannot show a dialog, the docs also describe setting projects["<path>"].hasTrustDialogAccepted to true in ~/.claude.json. I only use that for the fixed-path checkout. Wiring something up to write it into a fresh disposable folder every run would mean routing around the trust mechanism entirely. Also note that a helper written in the settings of an --add-dir directory is ignored regardless of trust.
Placement
Trust dialog
Credential env vars
User settings / --settings / managed (marketplace)
Not required
Not removed
User / local / managed / claude.ai (MCP)
Not required
Not removed
Project .claude/settings.json (marketplace)
That folder itself must be trusted
Removed
Catalog entry in marketplace.json
Command accepted on each install
Removed
Project .mcp.json
That folder itself must be trusted
Removed
Inline MCP in an agent file
That folder itself must be trusted (otherwise the server is not loaded at all)
Removed
--add-dir settings (marketplace)
—
Helper is ignored
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.
Working backward from the symptom
After losing that half day, I wrote down the table I now walk top to bottom when something similar happens. Start from the row whose symptom matches yours.
Symptom
Likely cause
How to check
Fix
Works at user scope, auth fails once placed in a project
Credential-looking variables are stripped
Run the helper alone through run_like_project_scope or env -i
Read from the keychain or a mode-600 file
claude -p prints headersHelper not run
That folder itself is not trusted (-p and parent trust don't count)
Open an interactive session in the same folder and see whether the trust dialog appears
Approve once interactively; for a fixed path, set hasTrustDialogAccepted
Non-interactive install stops with exit 1
No TTY, and neither -y nor --accept-command
Look for output saying the command was only displayed
Run with -y from your own terminal; -y does nothing inside a Claude session
Bulk install or auto-update skips just that plugin
Entry helpers only run for a single-plugin install or update
Check the /plugin Errors tab
Install that plugin again on its own
validate reports sets headersHelper but is not "strict": false
The entry lacks "strict": false
Run claude plugin validate
Add "strict": false to the entry
Helper succeeds but the archive returns 401
A redirect left the origin and the headers were dropped
Follow the archive URL with curl -sI
Serve from the same origin, or use signed URLs that need no header
Helper fails intermittently
It exceeds the 10-second ceiling (a slow issuing service, for example)
Time the helper with time
Sign locally, or cache issued tokens briefly
Common misreadings
"Inside a headersHelper, every environment variable disappears." Only credential-looking names and a fixed list are removed. PATH and HOME remain. That said, I don't think the remaining variables are a reason to lean on the environment in your design.
"$PWD tells you which scope called the helper." The working directory is always ~/.claude (or CLAUDE_CONFIG_DIR). Use CLAUDE_CODE_PLUGIN_NAME or CLAUDE_CODE_MARKETPLACE_URL to tell them apart. I held this misreading for longer than I'd like to admit.
"Once claude -p runs in a folder, that folder counts as trusted."-p and SDK sessions never count as accepting trust. Either a person approves the dialog, or you declare it in ~/.claude.json.
Where you're likely to get stuck next
Once the helper works, the next thing that tends to break is the archive's sha256 changing on every rebuild, which breaks the pin. Why zips built from the same commit still hash differently, and how to normalize them, is covered in keeping a plugin zip's SHA-256 stable.
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 variable stripping won't trouble you 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.
Share
Thank You for Reading
Claude Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.