mcp-inspector

MCPJam CLI 調査

mcpjam または MCP Inspector の出力から MCP サーバーの動作を分析するときは、このスキルを使用してください。目的は、次の項目を区別することです。

• 実際のプロトコル上の問題
• 相互運用性に関する警告
• 実装の仕上げに関する問題
• mcpjam または SDK に起因する現象

対話的な使用

ユーザーがサーバーへの接続とその使用を希望している場合は、次の手順に従ってください。

1. まずサーバーをプローブします：server probe --url <url> --quiet --format json。

• 接続先のサーフェスが公開されていると決めつける前に、プローブを使って認証の状態、リソースメタデータ、認可サーバーのメタデータ、登録方法を確認します。

2. プローブに oauth_required と表示された場合は、oauth login --credentials-out <path> で認証するか、OAuth フローのテストがタスクの目的である場合は oauth conformance --credentials-out <path> を実行します。
3. ツールを検出します：tools list --url <url> --credentials-file <path> --quiet --format json。

• toolsMetadata 内の _meta.ui.resourceUri、非推奨の _meta["ui/resourceUri"]、または openai/outputTemplate を持つツールには、インタラクティブ UI があります。
• 特定のツールについては、toolsMetadata.<toolName>._meta.ui.resourceUri、toolsMetadata.<toolName>._meta["ui/resourceUri"]、または toolsMetadata.<toolName>["openai/outputTemplate"] を確認します。

4. ツールを実行します：tools call --url <url> --tool-name <name> --tool-args <json> --credentials-file <path>。
5. UI を使って実行します：tools call --url <url> --tool-name <name> --tool-args <json> --credentials-file <path> --ui。

• --ui はローカルの Inspector バックエンドを起動または接続し、完了した結果を App Builder に表示します。
• 非 TTY、エージェント、CI での実行では、--ui はデフォルトでブラウザーを開きません。CLI 自体に App Builder を開かせる場合は、--open を指定してください。
• --open はシステムブラウザーの URL を開きます。すでに制御されている自動化ブラウザーに接続したり、新しいタブで注入済みのレンダリングを表示させたりするものではありません。ブラウザー自動化によって Inspector App Builder がすでに開かれている場合は、--no-open を使用してください。起動、ブラウザーを開く操作、検出のすべてを禁止する必要がある場合は、--attach-only を使用してください。
• no_active_client は、Inspector バックエンドが実行中でもブラウザークライアントが接続されていない可能性を示します。手動での復旧が必要な場合は、mcpjam inspector start ではなく mcpjam inspector open を使用してください。
• ルートの error.code または inspectorRender.commands.*.error.code にある unknown_server は、Inspector が要求されたサーバーを特定できなかったことを示します。App Builder が別のサーバーにフォーカスしているというメッセージが表示された場合は、--server-name <focused-name> を指定して再試行してください。
• UI の成功は、終了コード 0 だけではなく、inspectorRender.status === "rendered" で判断してください。レンダリングが skipped の場合は、inspectorRender.remediation または安定したルートの warning.code に基づいて分岐してください。
• レンダリング成功の証拠として外部スクリーンショットを必須にしないでください。iframe や canvas の内容がブラウザースナップショットツールで取得できない場合があります。inspectorRender.status、コマンドの応答、スナップショットの証拠を優先してください。
• ツールに UI メタデータがある場合、またはユーザーが明示的に UI の表示を求めた場合にのみ、--ui を使用してください。

ユーザーが調査、監査、またはトリアージを求めている場合は、以下の調査ワークフローを使用してください。

基本方針

• 正規化された CLI の利便性を重視した出力よりも、生のリクエスト／レスポンスの証拠を信頼してください。
• 観察事項、適合性の問題、セキュリティ上の所見を区別してください。これらには関連性がありますが、相互に置き換えられるものではありません。
• 主張が仕様のどの程度の強さに対応するかを示してください。MUST と MUST NOT は強い適合性の指標です。SHOULD と RECOMMENDED はより緩やかな指針です。MAY と任意フィールドは通常、参考情報です。
• 具体的な攻撃者の利益、または明確な破損経路を裏付けられない限り、セキュリティ上の所見を high と評価しないでください。
• 証拠が曖昧な場合は、結論を誇張するのではなく、確信度を下げるか pending を使用してください。

調査ワークフロー

1. 主張を実際に裏付ける、最も対象を絞ったコマンドから始めます。
2. コマンドが失敗する可能性がある場合、再利用可能な引き継ぎ用の成果物が必要な場合、または CI で証拠を保持する必要がある場合は、server probe、server validate、tools call、または oauth login に --debug-out <path> を追加します。
3. プローブの結果が oauth_required で、タスクがサーバーのサーフェスを調べることである場合は、oauth login または別のサポート対象の認証フローを続行して再利用可能な認証情報を取得してから、認証後の動作を判断します。複数コマンドを使う接続セッションでは、oauth login、oauth conformance、または oauth conformance-suite に --credentials-out <path> を指定してトークンを保存し、後続のコマンドには --credentials-file <path> を指定します。アクセストークンのみを使用する例外については、references/cli-surface-notes.md を参照してください。トークンがすでに利用可能な場合（CI、M2M、環境変数）は、可能であれば認証情報ファイルを優先し、--access-token または --oauth-access-token は代替手段としてのみ使用します。
4. 認証に成功したら、server info、server capabilities、tools list、resources list/read/templates、prompts list/get などの直接的なコマンドで、接続されたサーフェスを調べます。
5. 単機能のコマンド出力をいくつも使う代わりに、幅優先のスナップショットが必要な場合は、server doctor --out <path> を使用します。
6. 出力が server doctor または --debug-out の成果物から得られた場合は、主要コマンドの証拠、プローブの証拠、接続後の一括調査の証拠に分けます。
7. 主張が MCP Apps のツールメタデータまたは ui:// リソースに関するものであれば、tools list または resources read に移る前に、apps conformance --quiet --format json から始めます。
8. 主張が Inspector でのツール結果のレンダリングに関するものであれば、tools call --tool-name <name> --tool-args <json|@file|-> --ui --quiet --format json を使用します。

• 非 TTY の実行では、Inspector ブラウザクライアントがまだ接続されていない場合は --open を追加します。
• ブラウザーの自動化ですでに http://127.0.0.1:6274/#app-builder が開かれている場合は、--no-open を追加します。--open はシステムブラウザーを起動するため、自動化の制御対象クライアントに接続されない場合があります。
• inspectorRender.status === "rendered" によって UI の配信を確認します。inspectorRender.remediation と、安定したスキップされたレンダリングの warning.code 値は、復旧の手掛かりとして扱い、MCP ツールの失敗とは見なさないでください。
• ルートエラーまたはコマンドエラーに unknown_server が含まれ、メッセージで対象サーバーが特定されている場合は、--server-name <focused-name> を指定して再試行します。
• レンダリングがスキップされた場合に警告ではなくハードエラーにしたいときは、--require-render を使用します。

9. フィールドが CLI によって追加された可能性、または SDK によって正規化された可能性がある場合は、結論を出す前に references/cli-surface-notes.md を参照します。
10. 主張が MCP のセマンティクスに依存する場合は、references/mcp-2025-11-25-interpretation.md を参照します。
11. 主張が Cross-App Access、ID-JAG、またはエンタープライズ管理の認可に関わる場合は、xaa run の出力をトリアージする前に references/xaa-id-jag-interpretation.md を参照します。
12. タスクにセキュリティレビューが含まれる場合は、references/security-best-practices.md でチェックリスト全体を確認し、以下のセキュリティレビューワークフローに従います。
13. 以下の出力要件に従って結果を記述します。

セキュリティレビューワークフロー

MCP サーバーのセキュリティ態勢を評価するタスクでは、このワークフローを使用します。すべてのチェックには既存の CLI コマンドを使用します。特別なセキュリティツールは必要ありません。すべてのサーバーで認証が必須だと決めつけないでください。

フェーズ 1：観察（読み取り専用）

まず server probe --url <target> --quiet --format json を実行します。状況の把握に役立つ場合に限り、oauth metadata または server doctor --out <path> を追加します。

• 初期の認証シグナルを記録します。
  • full-auth candidate：probe の status が oauth_required
  • public-or-mixed candidate：probe の status が ready
  • unknown：probe が reachable、error、またはそれ以外の曖昧な状態のみ
• 検出した事実を記録します。
  • OAuth メタデータ URL と、それらがパブリック、プライベート、または疑わしい接続先を示しているかどうか
  • scopes_supported、WWW-Authenticate、PKCE メソッド
  • dcr、cimd、preregistered などの登録方式
• 信頼する証拠の範囲を記録します。生の probe／RPC 証拠は、doctor の要約や便宜的なフィールドより優先されます。
• フェーズ 1 では、観察結果とコンプライアンス上の注記を記録できます。それだけでセキュリティ重大度を high にしてはいけません。

フェーズ 2：挙動を試す（引き続きほぼ未認証）

フェーズ 1 の認証シグナルは、実際の挙動で確認できるまでは暫定的なものとして扱います。

• full-auth candidate の場合：
  • DCR がサポートされている場合は、DCR の形式を調べるプローブを実行します。
  • 可能であれば、未認証での代表的な tools list または tools call の挙動を抜き取り確認します。
  • 不正なトークン、期限切れトークン、または対象オーディエンスが明らかに誤っているトークンがどう扱われるかを確認します。ただし、拒否されたことから分かる内容を誇張しないでください。
• public-or-mixed candidate の場合：
  • 未認証で tools list を実行します。
  • 公開されているツールを読み取り専用、書き込み、または副作用ありに分類します。
  • 代表的な公開ツールを未認証で呼び出します。
  • アクセス制限されたツールが、空のデータや部分的なデータを黙って返すのではなく、明確な認証チャレンジで失敗するか確認します。
• 匿名アクセスの階層、レート制限、または機能が制限されたパブリックアクセスは、セキュリティ態勢に関する注記であり、別個の態勢クラスではありません。
• フェーズ 2 の挙動が明らかになったら、no-auth、full-auth、mixed-auth、unknown のいずれかに再分類します。フェーズ 2 がフェーズ 1 と矛盾する場合は、以前の分類を無理に適用せず、態勢を更新して関連する確認を再実行します。
• フェーズ 2 で見つかった入力検証上の問題は、フェーズ 3 で攻撃者にとっての利点が証明されるまでは、セキュリティ重大度を medium 以下にとどめます。
• 設計やセキュリティ態勢に関する問題は、フェーズ 2 でも実際のセキュリティ上の問題となり得ますが、自動的に重大度を引き上げてはいけません。安全でない挙動、悪用経路、所有者の意図に関する不確実性を記録してから、medium または high と判定します。

フェーズ 3：攻撃者にとっての利点を悪用または確認する

同意や Cookie に依存する証明には、oauth login と同じブラウザーセッションを使用します。

• フェーズ 3 では、もっともらしい懸念を、エンドツーエンドで実証された実際のセキュリティ上の問題へと進めます。
  • DCR と認可フローの証明
  • リダイレクト URI の完全一致チェックを回避できることの証明
  • 他者のトークン受け入れ、またはトークンのパススルーの証明
  • コード、トークン、またはテナントをまたぐデータの取得
• 同意のスキップは high となる経路の一つですが、唯一の経路ではありません。攻撃者が具体的な利得を得ることを示す実証済みの攻撃チェーンがあれば、high と判定できます。

フェーズ 4：影響範囲を確認する

• 認証が成功した後、JWT クレームをデコードし、生ログで Mcp-Session-Id を調べ、ツール、リソース、プロンプト、スコープ、テナントコンテキストを列挙します。
• フェーズ 4 の主な目的は、影響範囲の評価です。悪用も証明できない限り、状況を示す情報として扱います。

セキュリティ重大度の評価

• high：攻撃者にとっての利点、または仕様に準拠したクライアントの不具合が、直接的な証拠で実証されている
• medium：具体的な攻撃シナリオがある信頼性の高いセキュリティ上の問題だが、エンドツーエンドの証明はまだ不完全
• low：強化の不足、または影響が限定的なセキュリティ上の懸念
• pending：重大度を大きく引き上げる、または引き下げる可能性がある、具体的な未確認事項が残るもっともらしいセキュリティ上の懸念
• info：攻撃者にとって信頼できる利点はまだないものの、事実として確認された観察結果

チェックリストの項目に該当しただけで、セキュリティ重大度を無理に medium や high とするのではなく、pending を使用してください。

コマンドの選び方

• server probe：HTTP トランスポートへの到達性、初期化の挙動、OAuth ディスカバリーのヒントを確認します。
• server doctor：プローブと接続後の挙動をまとめたトリアージ用アーティファクトです。幅広い確認に適していますが、これだけでワイヤーレベルの挙動を証明できるとは限りません。
• oauth metadata、oauth proxy、oauth debug-proxy：適合性の出力が想定外に見える場合に、エンドポイントとメタデータを正確に調査します。
• oauth login：再利用可能な認証情報を取得し、認証済みの MCP パスを確認します。--credentials-out <path> を指定すると、後続の接続コマンドで手動のトークン抽出をせずに --credentials-file <path> を使用できるよう、トークンをディスクに保存できます（モード 0600）。有効期限が切れていないアクセストークンを必要とするコマンドについては、references/cli-surface-notes.md を確認してください。OAuth が必要なサーバーを調査する場合に使用し、ログイン結果だけで終わらせず、後続の接続コマンドも実行してください。
• oauth conformance、oauth conformance-suite：フローレベルの認証チェックです。包括的なセキュリティレビューではなく、対象を絞ったプローブとして扱ってください。成功したフローの認証情報を後続の接続コマンドに渡す場合は --credentials-out <path> を使用し、その後は JSON 出力からトークンを抽出せずに --credentials-file <path> を使用してください。生の JSON 出力では、OAuth のシークレットはデフォルトで伏せられます。--conformance-checks を有効にすると、このコマンドは DCR の非ループバック http:// リダイレクト、無効なクライアントの拒否、認可エンドポイントでのリダイレクト不一致の処理、MCP サーバーでの無効なベアラートークンの拒否、トークンエンドポイントでのリダイレクト不一致を直接プローブできます。
• xaa run：認可サーバーと MCP サーバーに対する、ヘッドレスの Cross-App Access（ID-JAG）フローです。発行、JWT bearer grant による交換、認証済み MCP 初期化を行います。エンタープライズ管理の認可や ID-JAG の信頼関係のデバッグが関係するタスクで使用してください。--issuer-base-url は、CLI のローカル署名鍵を公開するオリジン（通常は mcpjam inspector start）を指定する必要があります。出力をトリアージする前に references/xaa-id-jag-interpretation.md をお読みください。これは現在の ID-JAG ドラフトに対する対象を絞ったチェックであり、適合性スイートではありません。負のテストのスコアカード（改ざんされた ID-JAG）は CLI ではなく Inspector UI にあります。
• apps conformance：_meta.ui.resourceUri、ui:// リソース、resources/read、HTML MIME とペイロードの形式、_meta.ui メタデータに関する、サーバー側 MCP Apps のチェックです。MCP Apps のサーフェスをトリアージする際に使用してください。
• server info、server capabilities、server validate、server ping、server export：初期化と認証の後に、接続後の挙動を確認します。
• tools list と tools call、resources list/read/templates、prompts list/get/list-multi：接続後の機能を直接確認します。--ui を指定すると、tools call は完了したツールの結果を Inspector でレンダリングし、UI コマンド／レンダリングの証拠として inspectorRender を報告します。
• --quiet --format json を優先してください。要約ではなくリクエストとレスポンスの証拠が必要な場合は、使用可能であれば --rpc を追加してください。失敗時にもアーティファクトが必要な場合は --debug-out を追加してください。これは生の証拠の代わりではありません。
• 適合性コマンドと差分コマンドの CI レポート用アーティファクトには、--reporter junit-xml または --reporter json-summary を使用してください。server validate は --reporter を受け付けません。検証アーティファクトには --debug-out を使用してください。--format junit-xml は使用しないでください。--format が指定できるのは、生の json または human 出力のみです。
• JSON 値を取るオプションでは、ペイロードが生成されたものである場合や引用符を含む場合、シェルでエスケープしたインライン JSON よりも @path または - による標準入力を優先してください。例：mcpjam tools call --url <target> --tool-name <name> --tool-args @params.json --quiet --format json

出力の仕様

一般的なトリアージの出力

セキュリティ以外のタスクでは、次の内容を返します。

• Verdict：real issue、interop warning、implementation polish、scanner/client artifact のいずれか
• Severity：high、medium、low、info のいずれか
• Confidence：high、medium、low のいずれか
• Why it matters：相互運用性、セキュリティ、またはユーザーへの影響に結び付けた短い段落
• Evidence：主張を裏付ける正確な CLI の動作
• Missing evidence：重大度や確信度を引き上げる前に確認する必要がある事項

セキュリティレビューの出力

セキュリティレビューで指摘した各項目について、次の内容を返します。

• Verdict：real issue、interop warning、implementation polish、scanner/client artifact のいずれか
• Compliance severity：high、medium、low、info のいずれか
• Security severity：high、medium、low、info、pending のいずれか
• Confidence：high、medium、low のいずれか
• Attack scenario or pending rationale：Security severity が medium または high の場合は、攻撃者が誰で、何を必要とし、何を得るのかを答える2～3文で書き始めます。pending の場合は、不足している証拠を明記します。
• Verified via：主張を裏付けるフェーズと正確なコマンドまたは結果
• Evidence：主張を裏付ける正確な CLI の動作
• Missing evidence：重大度や確信度を引き上げる前に確認する必要がある事項

厳守事項

• toolsMetadata を MCP サーバーのフィールドと呼んではいけません。
• UI レンダリングに削除済みのアプリ/ウィジェットコマンドを使用しないでください。tools call --ui を使用し、生のリソース HTML には resources read --resource-uri ui://... を使用してください。
• tools call --ui でレンダリングを駆動できる場合に、Inspector API 呼び出しを手動でオーケストレーションしないでください。
• ユーザーがサーバー名を挙げたが特定のツールを挙げていない場合、tools list による検出を省略しないでください。
• prompts/list が実際に送信されサーバーが応答したという生の RPC 証拠がない限り、空のプロンプトリストからプロンプト対応を推測しないでください。
• ユーザーが認証済みサーバーサーフェスの調査を求めており、CLI がログインを完了できる場合、oauth_required で止まらないでください。可能な場合は認証を行い、ログイン後のコマンドを続行してください。
• apps conformance の合格結果を完全な SEP-1865 準拠として扱わないでください。現在のコマンドはサーバー側のみであり、ホストのライフサイクル、サンドボックスプロキシ、postMessage ブリッジの動作を証明するものではありません。
• outputSchema、コンテンツアノテーション、scopes_supported、scope ヒントなどの欠落したオプションメタデータを、MUST がない限り致命的な失敗として扱わないでください。
• OAuth RFC 違反と MCP プロファイルの選好を区別してください。
• 「サーバーが不正なリクエストを正しく拒否した」と「設計全体が安全である」を区別してください。
• --debug-out の成果物は、純粋なワイヤキャプチャではなく、集約された証拠エンベロープとして扱ってください。
• 欠落した scopes_supported や WWW-Authenticate 内の欠落した scope をセキュリティ問題として指摘しないでください。どちらもオプションです。
• 特定の不正な入力 1 つを拒否したというだけで、サーバーが「安全」であると主張しないでください。単一のネガティブテストは、より広範なセキュリティ態勢を証明するものではありません。
• oauth_invalid_token やリダイレクト不一致プローブの合格を、認可設計全体が安全である証拠として扱わないでください。これらのチェックは、送信された正確なケースのみを証明します。
• チェックリストのヒットだけで high のセキュリティ重大度を割り当てないでください。
• JWT の aud 不一致は、サーバーが別のオーディエンスやリソース向けに発行されたトークンを受け入れること、またはトークンを誤ってバインドすることを示さない限り、トークンパススルーの証拠にはなりません。
• plain PKCE のサポートは通常、ハードニングにすぎません。攻撃者がベリファイアを選んだ攻撃者所有クライアントの DCR フローと複合させることはできません。
• 悪意のある redirect_uri 値は、サーバーがそれらをフェッチすることを示さない限り SSRF ではありません。
• 公開された未認証アクセスは、それ自体では所見ではありません。動作が宣伝された態勢と一致するか、公開されたサーフェスが設計上安全かを確認してください。
• 匿名トライアルやレート制限付きアクセスは態勢上の注記であり、別個の重大度所見ではありません。
• 所見を複合させる場合は、複合攻撃パスを説明してください。無関係な所見を並べて、その組み合わせがより悪いと述べるだけにしないでください。
• verify_issuer_publication が失敗した場合、またはエラーが空の steps 配列を伴う単なる接続失敗である場合、xaa run の失敗をターゲットサーバーに対してトリアージしないでください。これらはローカルの発行者セットアップの問題です。--issuer-base-url は CLI のローカル署名鍵を提供する必要があります。
• xaa run 出力の not_advertised ケイパビリティ証拠を、レデンプションが成功した場合に失敗として扱わないでください。また、アドバタイズをレデンプションが成功する証拠として扱わないでください。アドバタイズは証拠であり、トークンエンドポイントの応答が判定です。unknown(メタデータキーが存在しない)は not_advertised(キーは存在するが値がない)よりも弱い証拠です。両者を混同しないでください。
• idJag.verified: true を、認可サーバーがアサーションを検証した証拠として扱わないでください。これは CLI が自身の発行者に対して自身のミントを検証しているだけです。
• 1 回の完了した xaa run から ID-JAG 準拠や安全な XAA 態勢を主張しないでください。それは 1 つの登録戦略に対する 1 つのハッピーパスを証明するにすぎません。
• --assertion-format saml を SAML ID-JAG を生成するものとして説明しないでください。これは ID アサーションのレッグと sub_id クレームを変更します。ID-JAG は常に JWT です。ID-JAG は有効な IETF Internet-Draft です。MUST/SHOULD クレームは RFC ではなくドラフトリビジョンに基づいてください。
• xaa run 出力の [REDACTED] 値を欠落データとして報告しないでください。また、レダクションされていない出力を要求しないでください。レダクションは設計によるものであり、サーバーが反映したシークレットにも適用されます。

リファレンスマップ

• references/cli-surface-notes.md コマンド固有の注意事項、アーティファクトの形式、ローカルでの補足情報、統合されたエラー、正規化された空の配列について参照してください。
• references/mcp-2025-11-25-interpretation.md 最新の MCP 仕様に照らした、機能、ライフサイクル、トランスポート、認可、ツール、リソース、プロンプトの解釈について参照してください。
• references/xaa-id-jag-interpretation.md xaa run の出力について参照してください。3 者間の信頼モデル、発行者の前提条件、機能証拠の意味、登録警告の分類、SAML の軸、Cross-App Access の検出結果の重大度の調整が含まれます。
• references/security-best-practices.md CLI コマンドに対応するセキュリティレビューの確認項目について参照してください。SSRF、Confused Deputy、PKCE、トークンパススルー、スコープの最小化、認証態勢の確認、セッションセキュリティを扱います。出典：https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices