Claude CodeのheadersHelper｜プラグイン認証の新設定

Claude Codeのプラグインを社内マーケットプレイスから配る際、認証つきの取得URLに固定トークンをsettings.jsonへ平文で書いていて、漏えいやローテーションが不安だった方は多いはずです。結論から言えば、2026年8月20日公開のClaude Code v2.1.238で、url型マーケットプレイスやカタログのプラグインエントリにheadersHelperを指定できるようになり、カタログや同一オリジンのアーカイブ取得のたびにコマンドで短命トークンを発行してHTTPヘッダーに差し込めます。この記事では、headersHelperが何をする設定か、これまでの静的headersとの違い、url単位とカタログエントリ単位での書き方、install/update時の確認、そして筆者が社内プラグインを安全に配る運用でどう使うかまで、設定例つきでまとめます。

01Claude Code headersHelperとは｜何をする設定か

Claude CodeのheadersHelperとは、url型のプラグインマーケットプレイスやカタログのプラグインエントリに指定するコマンドで、カタログや同一オリジンのアーカイブを取得するたびに実行され、そこで生成したHTTPヘッダー（たとえば短命トークンを載せたAuthorizationヘッダー）を取得リクエストに差し込む仕組みです。認証が必要な取得URLに、固定の資格情報ではなくその場で発行した資格情報を渡せるようにするための設定です。

追加されたのはv2.1.238（2026-08-20）

公式のchangelogでは、2026年8月20日のv2.1.238のエントリに「headersHelper on a url marketplace or a catalog entry runs a command that mints HTTP headers (e.g. a short-lived token) for catalog and same-origin archive fetches」と記載されています。keybindingFlavor設定の追加や、長時間セッションでのメモリ肥大の修正なども同じバージョンで同時に入りました。headersHelperのプラグインマーケット対応は、このバージョン以降のClaude Codeで使えます。

headersHelperは何を解決するのか？

解決するのは、認証つきの取得先に固定トークンを置きたくない、という運用上の悩みです。社内やGitLab・Bitbucket・自己ホストにマーケットプレイスのmarketplace.jsonや配布アーカイブを置くと、取得時に認証ヘッダーが要ります。これまではそのヘッダーを固定値で持たせるしかなく、値が長命になりがちでした。headersHelperを使うと、取得の直前にコマンドを走らせて短命トークンを作り、そのつどヘッダーへ載せられます。トークンの寿命が短いぶん、設定ファイルに残った値が漏れても被害を抑えやすい、という位置づけです。プラグイン配布そのものの基礎はClaude Codeプラグインの使い方｜導入・自作・チーム配布までで整理しています。

02これまでの静的headersと何が違うか【比較表】

最大の違いは、認証ヘッダーが「設定ファイルに固定で書く値」から「取得のたびにコマンドで作る値」に変わった点です。従来も認証つきのurl取得はできましたが、その手段は静的なheadersに限られていました。

従来はsource.headersに固定トークンを書いていた

Claude Codeのマーケットプレイスソースにはurlタイプがあり、これはmarketplace.jsonへの直接URLを指すもので、認証つきアクセス用に任意のheadersを添えられます。Claude Codeはこのヘッダーを、マーケットプレイスURLと同一オリジン（スキーム・ホスト・ポートが一致）のアーカイブ取得にだけ送り、別オリジンへリダイレクトすると落とします。認証は通せますが、トークンは書いた値のまま長く残ります。

headersはsettings.jsonに直書きする値

このheadersはsource.headersとしてsettings.jsonに書くオブジェクトで、たとえばAuthorizationに固定のトークン文字列を入れておく形です。値が設定ファイルに残るため、リポジトリやバックアップに設定が混ざると、その1本のトークンが有効なまま外へ出る余地がありました。

v2.1.238で変わった3点

変わったのは次の3点です。1つ目は、値を固定文字列からコマンド出力に置き換えられるようになったこと。2つ目は、そのコマンドが取得のたびに実行されるため、短命トークンを毎回作れること。3つ目は、カタログエントリ（プラグイン単位）にも付けられ、その場合はinstall/updateのときだけ実行され、コマンドが表示されて確認が入ることです。適用範囲はいずれも、カタログ本体の取得と、同一オリジンのアーカイブ取得です。

静的headers と headersHelper（v2.1.238）

項目	これまで（静的headers）	今回（headersHelper）	実務での意味
ヘッダーの値	固定文字列を直書き	コマンド出力を都度使用	秘密情報を設定に固定化しない
トークンの寿命	書いた値のまま長命になりがち	都度発行の短命トークンを想定	漏えい時の有効期間を短くできる
実行タイミング	値は常に同じ	取得のたびに実行（カタログ本体・同一オリジンのアーカイブ）	失効しても次の取得で作り直せる
付けられる単位	urlマーケットプレイス	urlマーケットプレイス／カタログエントリ	プラグイン単位で認証を分けられる
install/updateの確認	なし（固定値のため）	コマンドを表示し[y/N]（-yで省略）	意図しないコマンド実行を止められる

アウトプットにどんな差が出ると想定されるか

実測ではなく仕様差からの想定です。従来はsettings.jsonに固定トークンが残るため、設定が流出すると、その1本のトークンが長く有効なまま使われる余地がありました。headersHelperではヘッダーの実体が設定に残らず、コマンドが取得のたびに短命トークンを作る前提です。この仕様差から、社内マーケットプレイスの資格情報の棚卸しや、退職者のトークン失効といった運用作業が、固定トークンを配り直す方式より軽くなると想定されます。断定できるのは仕様上の挙動までで、削減量などの数値は実測していないため示しません。

03headersHelperの設定方法｜urlマーケットとカタログエントリ

設定はextraKnownMarketplacesの中で、url型ソースにheadersHelperを書く形が基本です。ここからは、まず基準となる静的headersの書き方を確認し、その置き換えとしてheadersHelperの書き方を紹介します。

基準：静的headersでの認証つきurlソース

従来の静的headersは、extraKnownMarketplacesのエントリ内で、sourceをurlタイプにしてheadersオブジェクトを添える書き方です。プロジェクトの.claude/settings.jsonに置くと、チームメンバーがそのフォルダのtrustダイアログを受け入れたあとにマーケットプレイスが追加されます。

{
  "extraKnownMarketplaces": {
    "acme-internal": {
      "source": {
        "source": "url",
        "url": "https://plugins.example.com/marketplace.json",
        "headers": { "Authorization": "Bearer <固定トークン>" }
      }
    }
  }
}

url marketplace全体にheadersHelperを付ける場合

固定トークンをやめ、コマンドで発行する場合は、同じurlソースにheadersHelperを指定します。指定したコマンドが、カタログ本体と同一オリジンのアーカイブを取得するたびに実行され、その出力ヘッダーがリクエストに載ります。値の実体を設定に書かず、短命トークンを発行するスクリプトへ委ねる形です。

{
  "extraKnownMarketplaces": {
    "acme-internal": {
      "source": {
        "source": "url",
        "url": "https://plugins.example.com/marketplace.json",
        "headersHelper": "/opt/acme/mint-plugin-headers.sh"
      }
    }
  }
}

スクリプトは短命トークンをヘッダーで返す

スクリプト側の役割は、社内の資格情報基盤やOIDCから短命トークンを取得し、Claude Codeが取得リクエストに載せるためのヘッダーを標準出力へ返すことです。出力の形式はClaude Codeのヘッダーヘルパーの規約に沿わせる必要があるため、最終的な形は公式changelogと/doctorの表示で確認してください。要点は「値を書かずコマンドに委ねる」ことです。

カタログエントリ（プラグイン単位）に付ける場合

カタログの各プラグインエントリにもheadersHelperを付けられます。この場合、そのプラグインをinstallまたはupdateするときだけコマンドが実行されます。実行前にコマンドが表示され、claude plugin install／claude plugin updateは[y/N]で確認を求めます。確認を省きたい自動化では-yを渡します。プラグインごとに取得先の認証を分けたいときに向いた単位です。

install/update時の[y/N]確認とは？

カタログエントリのheadersHelperが実行される直前に、そのコマンド文字列を画面に出し、実行してよいかを尋ねる確認です。マーケットプレイス側が指定したコマンドが手元で走る前に、内容を目視できる仕掛けです。CIなど無人で回す場合は-yで明示的に承認します。逆に対話で使うときは、表示されたコマンドが意図どおりかを見てからyを押すのが安全です。

04MCPの.mcp.json headersHelperとの違い

結論から言えば、両者は別物です。headersHelperという名前はMCPサーバー設定にも以前からありますが、今回v2.1.238で増えたのはプラグインマーケットプレイス側のheadersHelperです。混同しやすいので切り分けておきます。

どちらのheadersHelperかは用途で分かれる？

分かれます。見分けは用途で、AIツール（MCPサーバー）への接続ヘッダーならMCP側、プラグインのカタログとアーカイブの取得ヘッダーならプラグイン側です。次の表で対象と設定ファイルを並べます。

MCPのheadersHelper と プラグインのheadersHelper

項目	MCP側（以前から）	プラグイン側（v2.1.238）
対象	MCPサーバーへの接続	プラグインのカタログ・アーカイブ取得
書く場所	.mcp.json などのMCP設定	extraKnownMarketplacesのurlソース／カタログエントリ
位置づけ	既存機能（改善が積み重ねられてきた）	今回の新規対応

MCP側のheadersHelperは以前からある

MCPサーバーのheadersHelperは、.mcp.jsonなどに書く設定で、MCPサーバーへの接続時に動的なヘッダーを生成するためのものです。こちらは今回の新設ではなく、たとえば401/403が返ったときにヘルパーを再実行して再接続する改善や、プロジェクトの.mcp.jsonに置いた場合はそのフォルダのtrustダイアログの承認を必須にするなどのセキュリティ強化が、過去のバージョンで積み重ねられてきました。MCPそのものの仕組みはMCPとは？仕組みと使い方を図解で解説しています。

今回のプラグイン側headersHelperの適用先

一方で今回のプラグインマーケットプレイスのheadersHelperは、AIツールへの接続ヘッダーではなく、プラグインのカタログと配布アーカイブを取得するときのヘッダーを対象にします。SNSで「MCPの認証情報を平文で書く時代ではなくなった」と紹介されているのを見かけますが、正確にはMCP接続の話とは別で、プラグイン配布の取得認証に短命トークンを使えるようになった、というのが今回の変更点です。用途がAIツール接続か、プラグイン取得かで、どちらのheadersHelperかが分かれます。

05社内プラグイン配布・サイト制作でどう使うか【実践】

ここからは、筆者が自社ツール開発とサイト制作の現場でheadersHelperをどう使うかを、コピペできる粒度で紹介します。題材は、社内で作ったClaude Codeのプラグイン（スキルやスラッシュコマンド）を、認証つきの社内マーケットプレイスから配る運用です。

自社ツール開発：短命トークンで社内マーケットを配る

社内向けに作った定型作業のスラッシュコマンドやスキルを、認証つきのURLに置いたmarketplace.jsonから配るとします。従来は固定トークンを全員のsettings.jsonに配っていましたが、退職や漏えいのたびに配り直しが要りました。headersHelperにすると、各メンバーの端末で短命トークンを作るスクリプトを1本置き、設定はそれを指すだけにできます。

スクリプトの骨組み

以下は、社内のトークン発行APIから短命トークンを受け取り、ヘッダーとして返すスクリプトの骨組みです。

#!/usr/bin/env bash
# /opt/acme/mint-plugin-headers.sh
# 社内のトークン発行APIから短命トークンを取得し、
# Claude Codeが取得リクエストに載せるヘッダーを出力する。
set -euo pipefail
TOKEN="$(curl -fsS \
  -H "X-Actor: $(whoami)" \
  https://auth.internal.example.com/plugins/short-lived-token)"
# 出力形式はClaude Codeのヘッダーヘルパー規約に合わせる
printf 'Authorization: Bearer %s\n' "$TOKEN"

このスクリプトをheadersHelperに指定しておけば、カタログやアーカイブの取得のたびに新しいトークンが発行されます。固定トークンをリポジトリのバックアップやチャットで共有する必要がなくなり、失効も発行API側の設定で一括して適用できます。プラグイン配布の脆弱性対策という観点はClaude Securityとは？コミット前に脆弱性を止める使い方と合わせて設計すると、取得と実行の両面を締められます。

サイト制作：制作チームに社内コマンドを安全に配る

LP制作やサイト制作のチームでは、原稿整形・画像のalt生成・レスポンシブ確認といった定型作業を、Claude Codeのスラッシュコマンドに落として共有します。これらを社内マーケットプレイスにまとめ、プロジェクトの.claude/settings.jsonにextraKnownMarketplacesを書いておけば、制作メンバーはそのフォルダをtrustした時点でコマンド群が入ります。認証はheadersHelperで短命トークンにしておくと、外部の委託メンバーが入るプロジェクトでも、固定トークンを手渡しせずに配布できます。プラグイン単位で取得先を分けたい場合は、カタログエントリ側のheadersHelperを使い、機微なコマンドだけ別の認証にする運用も取れます。

導入の最小手順

最小の流れは次のとおりです。1つ目に、短命トークンを発行してヘッダーを出力するスクリプトを各端末（または配布イメージ）に置きます。2つ目に、extraKnownMarketplacesのurlソースへheadersHelperとしてそのパスを指定します。3つ目に、プロジェクトをtrustしてマーケットプレイスを追加し、/pluginから必要なプラグインを有効化します。4つ目に、claude plugin updateを走らせて、確認プロンプトとヘッダー生成が期待どおり動くかを見ます。

06headersHelperを使うときの注意点

便利な一方で、コマンドを走らせる仕組みである以上、押さえておきたい点があります。

表示されたコマンドは実行前に必ず確認する

カタログエントリのheadersHelperは、install/update時にコマンドが表示され[y/N]を求めます。マーケットプレイス側が用意したコマンドが手元で動くため、表示された内容が意図どおりかを見てから承認するのが前提です。-yで承認を省くのは、発行元と中身を信頼できる社内マーケットなど、対象を限ったときにとどめるのが安全です。

短命トークンの権限は絞る

headersHelperはトークンを短命にできますが、権限の広さは発行API側の設計次第です。プラグインの取得に必要な読み取り権限だけに絞ったトークンを発行し、書き込みや他リソースへのアクセスを含めないようにします。ヘッダーは同一オリジンの取得にだけ送られ、別オリジンへのリダイレクトでは落ちますが、発行するトークン自体の権限管理は運用側の責任です。

trustしていないフォルダでは追加されない

プロジェクトのsettings.jsonに書いたextraKnownMarketplacesは、そのフォルダをtrustして初めて反映されます。信頼していないフォルダや-p実行では、エントリは黙って無視されます。チームに配る際は、この挙動を前提に、trustの案内も一緒に共有しておくと詰まりません。

FAQよくある質問

08まとめ：headersHelperを入れるかの判断基準

headersHelperを入れるかは、「認証つきのプラグイン取得先に、固定トークンを置き続けたくないか」で決まります。個人で公開マーケットプレイスだけを使うなら、静的な設定のままでも困りません。一方、社内やGitLab・自己ホストに認証つきでプラグインを配っているなら、短命トークンに切り替えるだけで、資格情報の棚卸しと失効がぐっと扱いやすくなります。まずはextraKnownMarketplacesの1つを、ヘッダーを出力する小さなスクリプトに置き換え、claude plugin updateで確認プロンプトと取得が通るかを試すのが、失敗しない進め方です。プラグイン配布の全体像はClaude Codeプラグインの使い方、取得後の安全性はClaude Securityと合わせて設計してください。

その後のバージョンで入った使用量まわりの新機能は、Claude Code 2.1.243の新機能（/usageループ内訳・キーレスサインイン）で解説しています。

09出典

• Anthropic「Claude Code changelog」v2.1.238（2026-08-20）ほかhttps://code.claude.com/docs/en/changelog
• Anthropic「Claude Code settings（extraKnownMarketplaces / source types）」https://code.claude.com/docs/en/settings
• Anthropic「Create and distribute a plugin marketplace」https://code.claude.com/docs/en/plugin-marketplaces