Insiders ヘッダー、ルーティング、監査

insiders サーフェスを使うと、HTTP クライアントは実験的な挙動にオプトインし、そのリクエストが どの ルート、モデル、エージェント、セッションに属するかを宣言できます。このページでは ヘッダーの契約、そこからルーティングが何を導出するか、生成される監査証跡、そして出荷時点での この機能の境界を説明します。

ヘッダーがなければここにあるものは一切有効になりません。ヘッダーを送らないリクエストは ルーティングが存在しなかったときとまったく同じに振る舞います。ただし 後方互換性 に記した 1 点だけは意図的な例外です。

信頼モデル

ルーティングヘッダーは クライアントが送ってくるものであり、したがって偽造可能 です。 認証機構ではなく、身元として扱ってもいけません。

オプトインは、すでに信頼境界の内側にいる呼び出し元に与える権能だと考えてください。 ヘッダーの内容に依存する前に、呼び出し元を認証するゲートウェイの背後でサーバーを動かすか、 MCP_HOST を localhost に保ってください。ヘッダーが 実際に セキュリティ判断に関与する 唯一の箇所は ルート束縛トークン で、そこでは不一致はフェイルクローズになります。

ルート値は攻撃者が制御できる文字列で、ファイルシステムのパスやログ行に現れます。そのため すべてのルートは使用前にホワイトリストを通します。ルートのサニタイズ を参照してください。

X-MCP-Insiders ヘッダー

ヘッダー名の既定値は X-MCP-Insiders で、MCP_INSIDERS_HEADER で変更できます。 HTTP ヘッダー名は大文字小文字を区別しないため、検索も区別しません。

文法

値はカンマ区切りのリストです。問題はすべて 報告 されるだけで無視されます – タイプミスがリクエストを壊すことはありません。

値

効果

(ヘッダーなし)

無効

(空または空白のみ)

無効

false、0、off、no

無効

true、1、on、yes

有効。登録済みの各機能は既定値のまま

model-routing=false

有効。model-routing を強制的にオフ

model-routing

有効。model-routing を強制的にオン(裸のキー)

k=v, k2=v2

有効。登録済みの各キーを個別に上書き

追加の規則:

  • キー名は大文字小文字を区別せず、- と _ を同じ文字として扱います。 したがって Model_Routing と model-routing は同じ 1 つの機能を指します。

  • 登録されていないキーは unknown_keys に集められ、無視されます。 クライアントが、サーバーが知らない機能を有効にすることはできません。

  • パースできない値(たとえば model-routing=maybe)は malformed に集められ、 そのキーは破棄されます。

  • 4096 文字を超えるヘッダーはヘッダー全体を無効にし、malformed に header-too-long を記録します。

登録済みの機能

機能

既定値

有効時の効果

model-routing

オン

リクエストのルート、モデル、エージェント、クライアント、セッションがルーティングヘッダーから解決され、ツール呼び出しごとに監査レコードが 1 件追記される

experimental-tools

オン

insiders タグ付きツールが一覧に現れて呼び出し可能になり、director_tool が実験的な emotion / emotion_level パラメータを受け付ける

「既定でオン」は、サーフェスが有効化された後 の機能の状態を表します。 X-MCP-Insiders: true を送れば両方がオンになり、ヘッダーをまったく送らなければ 何もオンになりません。

優先順位(弱い順):

  1. 登録済みの既定値

  2. ヘッダーによるリクエスト単位の上書き

  3. MCP_INSIDERS_DISABLED_FEATURES – クライアントが送るものより優先される 運用者向けのキルスイッチ

ヘッダーが無効であれば、他の 2 つに関係なく機能集合は空になります。

ルートの宣言

model-routing が有効なとき、ルーティングは候補ヘッダーの集合を読みます。各グループは 順序付きリストで、空でない値を持つ最初のヘッダー が採用されます。

フィールド

既定の候補

環境変数による上書き

model

X-MCP-Model、X-MCP-Model-Name

MCP_MODEL_HEADERS

agent

X-MCP-Agent-ID、X-MCP-Agent、X-MCP-Agent-Source

MCP_AGENT_HEADERS

client

X-MCP-Client、X-MCP-Client-Session-Id

MCP_CLIENT_HEADERS

session

名前に session を含む最初の client 候補

–

3 つのリスト変数はいずれも JSON です。たとえば MCP_AGENT_HEADERS='["X-MCP-Agent-ID","X-MCP-Agent"]' のように書きます。 カンマ区切りの値はリストではなく設定エラーになります。

ルートの優先順位

ルートは、次に挙げるうち利用可能な最初のものです:

  1. 空でない最初の agent 候補

  2. 空でない最初の client 候補

  3. MCP クライアントが通知する名前(client_info.name)

  4. リクエストが HTTP 経由で届いていない場合は stdio、それ以外は unknown

ルートのサニタイズ

ルートがどこから来たものであれ、ディレクトリ名として使う前、あるいはログ行に書く前に ホワイトリストを通過しなければなりません:

  • 許可される文字: A-Za-z0-9._-

  • 長さ: 1 から 64 文字

  • 拒否されるもの: パス区切り(/、\)、トラバーサル(.、..)、空白、 非 ASCII 文字、空文字列、および 64 文字を超えるもの

拒否された値は unknown になります。この方法でサニタイズされるのは ルート だけで、 抽出された model、agent、client、session の各フィールドは生の値を 保つ点に注意してください。運用者がクライアントの実際の送信内容を確認できるようにするためです。

ルートごとのログと監査証跡

ログレコード

ツール呼び出しごとに、novelai_image_mcp.audit.<route> という名前のロガーへ 1 行を出力します。 そこにはツール名、ルート、モデル、エージェント、クライアント、セッション、所要時間、結果、 および有効な機能が含まれます。ロガー名にルートが含まれるため、運用者は標準のログ設定で チームごとの振り分けやフィルタができます。

監査レコード

監査レコードは、model-routing が有効な間だけ、追記専用の JSONL ファイルに追記されます。 出力先は MCP_AUDIT_LOG_PATH が設定されていればそこ、そうでなければ NOVELAI_OUTPUT_DIR 内の audit.jsonl です。

ファイルは O_APPEND で開かれ、各レコードは 1 回の os.write で書かれます。 そのため並行して書き込むプロセスは、行の半分同士を混ぜ合わせるのではなく、行単位で追記します。 書き込み中にクラッシュすると 1 行を失うことはありますが、すでに書かれた行を壊すことはありません。

フィールド

内容

ts

UTC タイムスタンプ、ISO-8601

route

サニタイズ済みのルート

model / agent / client / session

抽出された値、または null

tool

ツール名

duration_ms

実時間の所要時間。小数第 3 位で丸め

outcome

ok、error、rejected のいずれか

features

有効な機能名のソート済みリスト

artifacts

結果が言及した *.png パスのソート済みリスト

unknown_keys

ヘッダー中の未認識キーのソート済みリスト

malformed

ヘッダー中の使用不能な項目のソート済みリスト

headers

サニタイズ済みのルーティングヘッダースナップショット。最大 32 件、各値 256 文字まで

arguments

呼び出し引数の要約(下記参照)

秘匿化

証跡は、ペイロードがそこへ漏れ込まないように設計されています:

  • プロンプト形式の引数(prompt、negative_prompt など)は {"length": n, "sha256": "<先頭 16 桁の 16 進数>"} になります。プロンプト本文は 決して書かれません。

  • 画像形式の引数(image、mask、images、init_image、 references、base64)はリテラル [redacted image] になります。

  • 256 文字を超える文字列は すべて、そのまま書かれずに要約(ダイジェスト)化されます。 これにより、想定外の引数名で base64 の塊が紛れ込むことはありません。

  • コンテナはサイズに、未知のオブジェクトは型名に縮約されます。

  • 認証情報を含むヘッダー – authorization、cookie、set-cookie、 proxy-authorization、および -token、-secret、 -password、-passwd、-key、-credential(s) で終わるもの – は 記録前にヘッダースナップショットから除去され、ログに出力されることもありません。

失敗時の挙動

監査は、それが観測する対象を決して壊してはいけません。監査ファイルを作成または書き込み できない場合、失敗は ERROR としてログに記録され、ツール呼び出しは通常どおり結果を返します。 監査の問題がツール呼び出しの失敗に変わるコードパスは存在しません。

ルートスコープの出力

ルーティングが有効で、かつ MCP_ROUTE_SCOPED_OUTPUT が true(既定値)のとき、 生成された画像はルートごとのサブディレクトリに書き込まれます:

<NOVELAI_OUTPUT_DIR>/<sanitised route>/<name>-<timestamp>-<hex>.png

novelai://outputs/{name} リソースも同じディレクトリで名前を解決するため、クライアントは 自分が書いたものをそのまま読み戻せます。ディレクトリ名は上で述べたのと同じホワイトリストから 来るので、敵対的なルートが出力ディレクトリの外へ抜け出すことはできません。

ルーティングがオフの場合、または MCP_ROUTE_SCOPED_OUTPUT=false の場合は、 すべてのパスがルーティング導入前にサーバーが生成していたものになります。

ルート束縛トークン

MCP_AUTH_TOKEN は元の意味を保ちます。HTTP トランスポート用の静的なベアラートークン 1 つで、 MCP リクエストが処理される前に FastMCP が検証します。

MCP_ROUTE_TOKENS は、その上に ルート束縛 トークンを追加します。ルートからそのトークンへの 対応を与える JSON オブジェクトです:

MCP_AUTH_TOKEN=static-token
MCP_ROUTE_TOKENS='{"team-a":"token-for-team-a","team-b":"token-for-team-b"}'

ルートトークンはそのルートとして認証され、同じリクエストがルーティングヘッダーで 異なる ルートを宣言した場合は拒否されます。不一致があると検証器がリクエストを拒否し、ベアラー ミドルウェアがそれを 401 と WWW-Authenticate チャレンジに変換します – ToolError ではありません。両方のルートは WARNING でログに記録されるため、 拒否は監査可能なままです。

知っておくべき詳細:

  • 使用可能な宣言ルートがない リクエスト – ルーティングヘッダーがまったくない、あるいは 値が unknown にサニタイズされる – は受理され、トークン自身のルートに帰属されます。 フェイルクローズになるのは、異なる 2 つのルートがどちらも存在する場合だけです。

  • 静的トークンはルート検査に一切関与しないため、ルートトークンが設定されているかどうかに かかわらずその意味は変わりません。

  • 尊重できないエントリは警告つきでスキップされます。空のトークン、MCP_AUTH_TOKEN と 等しいトークン(静的トークンが優先されます)、ホワイトリストを通過しないルート名 (そのトークンはそもそも登録されないため、決して認証できません)、2 つのルートに束縛された トークン(ソート順で最初のルートが優先されます)が該当します。

  • どちらの設定も構成されていない場合、認証ミドルウェアは導入されず、エンドポイントは 以前とまったく同じに振る舞います。

後方互換性

insiders ヘッダーを送らないリクエストは、1 点の意図的な例外を除いて、今日のサーバーを見ます:

  • ツール、リソース、プロンプト、スキーマは変わりません。

  • ツールの追加も削除もありません。出荷されているツールは insiders タグを 1 つも 持たないため、一覧フィルタがオプトインしていないクライアントから何かを隠すことはありません。

  • 生成された画像はフラットな NOVELAI_OUTPUT_DIR レイアウトのままです。

  • 監査ファイルは書かれません。

  • MCP_AUTH_TOKEN は以前とまったく同じに振る舞います。

警告

director_tool の emotion と emotion_level パラメータはゲートされるようになりました。 experimental-tools のオプトインなしでどちらかを渡すと、ToolError で失敗します。 これは意図的な挙動変更であり、CHANGELOG の Changed に記録されています。既定値以外の emotion_level を渡すだけでもパラメータを渡したことになるため、既定の呼び出し形状は 影響を受けません。

拡張ポイント

  • 同階層の機能を追加する。 apps/server/src/novelai_image_mcp/features.py の INSIDERS_FEATURES に、名前、default_enabled、1 行の要約を持つエントリを 1 つ 追加します。ヘッダーパーサー、ミドルウェア、すべてのツールが、それ以上の変更なしに これを取り込みます。

  • 新しいツールをゲートする。 tags={"insiders"} を付けて登録します。一覧フィルタと 名前による拒否はいずれもこのタグから導かれます。既存のツールにこのタグを付けないでください – ヘッダーを送らないすべてのクライアントからそのツールが消えてしまいます。

  • 既存ツールに新しいパラメータをゲートする。 features: frozenset[str] = Depends(get_effective_features) を読み取り、 EXPERIMENTAL_TOOLS がないときは director_tool と同様に本体から ToolError を送出します。

v1 の境界

  • ツールスキーマは静的です。 FastMCP はサーバー起動時にツールのパラメータスキーマを 公開するため、スキーマをリクエストごとに変えることはできません。したがって実験的な パラメータはスキーマ上に表示されたままになり、オプトインは代わりにツール本体で 強制されます。スキーマをイントロスペクトしたクライアントはパラメータを見られますが、 ヘッダーなしでは使えません。

  • ルーティングはリクエスト単位であり、接続単位ではありません。 ヘッダーはツール呼び出しを 運ぶ HTTP リクエストから読み取られます。

  • ヘッダーは認証ではありません。 信頼モデル を参照してください。

関連項目