◉CLAUDE LABJP
●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
Articles/Claude Code
⟐ Claude Code/2026-08-22Intermediate

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.

Claude Code289Plugins3MarketplaceAuthentication4Indie Development11

✦ Premium Article

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.

PlacementWhen it runsTypical 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 secondsProtecting 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 commandSplitting 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.

or
Unlock all articles with Membership →
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.

  • ✦Copy-paste ready implementation code
  • ✦New advanced guides published daily
  • ✦$5/mo or $10 for lifetime access
View Membership →

Related Articles

⟐ Claude Code2026-09-10
One plugin.json turns a shelf of skills into something you can switch off as a group
When I sorted my skills by what work they belong to, the set I open almost daily turned out to be 5 percent of the total. Here is how I dropped a .claude-plugin/plugin.json into each group so I could switch a whole shelf off, plus the two loading rules I tripped over on the way.
⟐ Claude Code2026-09-10
When Every Request Fails With Not signed in to the Cloud gateway, Check the Version Before the Config
A Claude Code 2.1.265 regression broke every request for gateway and proxy setups. I use it as an excuse to build a small snapshot of the auth input surface, so the next time something breaks you can tell config from version in seconds.
⟐ Claude Code2026-09-03
Aligning Log Timezones at Display Time, or Fixing Them at Write Time
AdMob, the store reports, and my own logs each ended the day at a different moment. Here is how I went back and forth between display-side and write-side timezone handling, and what I settled on.