記事一覧
MCPホスティング

MCP Inspector CLIとは?MCPサーバーをCIで自動テストする方法【終了コード一覧・2026年版】

MCP Inspectorの--cliモードでMCPサーバーをCIテストする方法を解説。tools/list・tools/callの使い方、終了コード0〜11の意味、--stored-auth-only、--strict、--loadによる負荷ゲート、GitHub Actionsの例、よくあるハマりどころとFAQまでまとめました。

最終更新:2026年11月10日 / 対象:MCP Inspector 2.x(@modelcontextprotocol/inspector)、MCP仕様 2026-07-28

結論(30秒で読める要約)

  • MCP Inspectorは、MCPサーバーをテスト・デバッグするための公式ツールです。Web・CLI・TUIの3つのクライアントが1つのパッケージに入っています。
  • CIで使うのは --cli モードです。1回の実行で1つのメソッドを呼び、結果を出して終了します。
  • 終了コードが失敗の種類ごとに分かれています(3 = 認証が必要、4 = 到達不能、5 = ツールのエラーなど)。そのため、シェルで分岐しやすいです。
  • CIでは --stored-auth-only を必ず付けます。付けないと、OAuthのブラウザ認証を待つ動きになる場合があります。
  • 最小構成は「tools/list で期待するツールがあるか確認 → 無害なツールを1つ tools/call する」の2ステップです。

目次

  1. MCP Inspectorとは
  2. Web・CLI・TUIの比較
  3. CLIの基本コマンド
  4. 終了コード一覧
  5. CIで使うフラグ
  6. GitHub Actionsでの実装例
  7. よくあるハマりどころ
  8. リモートMCPサーバーを検証する場合
  9. FAQ

1. MCP Inspectorとは

MCP Inspectorとは、Model Context Protocol(MCP)のサーバーをテスト・デバッグするための公式の開発者ツールです。パッケージ名は @modelcontextprotocol/inspector で、インストールせずに npx で動かせます。公式ドキュメントでは Node.js 22.19.0 以上が必要とされています。

AIクライアント(Claude、Cursorなど)に繋いで試すと、モデルの判断が間に入るため、失敗の原因がサーバーにあるのかモデルにあるのか切り分けにくくなります。Inspectorはモデルを介さずにMCPのリクエストを直接送るので、サーバー側の問題だけを確認できます。

2. Web・CLI・TUIの比較

3つのクライアントは同じコアの上に作られています。トランスポート、設定ファイル、OAuthの保存状態は共通です。

クライアント 起動方法 向いている用途
Web npx @modelcontextprotocol/inspector ブラウザでリクエストを1件ずつ見る。最も機能が多い
CLI npx @modelcontextprotocol/inspector --cli CI、シェルスクリプト、コーディングエージェントからの検証
TUI npx @modelcontextprotocol/inspector --tui ブラウザなしで対話的に操作する

開発中の手動確認はWeb、自動テストはCLIと使い分けるのが基本です。

3. CLIの基本コマンド

サーバーの指定方法は3通りです。

# stdioサーバー:起動コマンドをそのまま渡す
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list

# リモート(Streamable HTTP)サーバー
npx @modelcontextprotocol/inspector --cli https://example.com/mcp --transport http --method tools/list

# 設定ファイルから名前で指定
npx @modelcontextprotocol/inspector --cli --config ./mcp.json --server myserver --method tools/list

ツールを呼ぶときは --tool-name と --tool-arg を使います。

npx @modelcontextprotocol/inspector --cli node build/index.js \
  --method tools/call --tool-name get_weather --tool-arg city=Tokyo --format json

主なメソッドは次のとおりです。

--method 必要な追加フラグ 用途
initialize なし 接続だけ確認し、serverInfo やcapabilitiesを取得
tools/list なし ツール一覧。--strict でスキーマ検査をゲート化
tools/call --tool-name ツールの実行
resources/list / resources/read resources/read は --uri リソースの確認
prompts/list / prompts/get prompts/get は --prompt-name プロンプトの確認

--tool-arg の値はJSONとして解釈されます。count=1 は数値として送られます。文字列のまま送りたい場合は --tool-args-json '{"zip":"10001"}' を使います。ただし、ツールの入力スキーマで型が決まっていれば、その型に変換されます。

--format json を付けると、標準出力に余計なバナーが出ず、JSONが1つだけ出ます。jq に渡すときは必ず付けます。

4. 終了コード一覧

CIで一番役に立つのが終了コードです。失敗の種類ごとに番号が決まっています。

コード 意味
0 成功
1 使い方の誤り、または想定外のエラー
2 ツールにMCP AppのUIがない(--app-info 使用時)
3 認証が必要(HTTP 401/403など)
4 サーバーに到達できない(DNS、接続拒否、タイムアウト)
5 ツールのエラー(isError: true)、またはツールが見つからない
6 --strict でツールスキーマの重大な問題が見つかった
7〜9 --verify によるスキルの検証で問題が見つかった
10 --load の負荷テストでエラー率またはp99の閾値を超えた
11 サーバーがHTTP 429(レート制限)を返した

0以外で終了したとき、標準エラー出力にJSONが1行出ます。code には auth_required、unreachable、tool_is_error などの名前が入ります。

{"error":{"code":"auth_required","message":"Unauthorized","status":401,"url":"https://example.com/mcp"}}

tools/call が isError: true を返した場合、結果は出力されますが終了コードは 5 になります。そのため && で繋いだ後続の処理は止まります。

5. CIで使うフラグ

フラグ 効果 使う場面
--stored-auth-only 対話的なOAuthを始めず、保存済みトークンがなければすぐ auth_required で失敗 CIでは必須
--format json 標準出力をJSON 1つだけにする jq で検証するとき
--strict tools/list のスキーマ移植性の問題を検査し、重大なら終了コード 6 ツール定義の品質ゲート
--load tools/call を並列で繰り返し呼び、レイテンシとエラー率を集計 簡易な負荷テスト
--load-max-p99 / --load-max-error-rate 閾値を超えたら終了コード 10 性能の回帰検知

負荷テストの例です。200回呼び、p99が500msを超えたら失敗にします。

npx @modelcontextprotocol/inspector --cli https://example.com/mcp --transport http \
  --method tools/call --tool-name get_weather --tool-arg city=Tokyo \
  --load --load-requests 200 --load-max-p99 500

6. GitHub Actionsでの実装例

ビルドしたstdioサーバーに対して、期待するツールがあるか確認し、1つ呼んでみる例です。

name: mcp-smoke-test
on: [push, pull_request]

jobs:
  smoke:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci && npm run build

      - name: ツール一覧に get_weather があるか
        run: |
          set -euo pipefail
          npx -y @modelcontextprotocol/inspector@2 --cli node build/index.js \
            --method tools/list --format json --stored-auth-only \
            | jq -e '.result.tools | map(.name) | index("get_weather")' > /dev/null

      - name: ツールのスキーマ検査
        run: npx -y @modelcontextprotocol/inspector@2 --cli node build/index.js --method tools/list --strict > /dev/null

      - name: 無害なツールを1回呼ぶ
        run: |
          npx -y @modelcontextprotocol/inspector@2 --cli node build/index.js \
            --method tools/call --tool-name get_weather --tool-arg city=Tokyo --format json

ポイントは3つです。

  • Inspectorのバージョンを固定する(例は @2。厳密にしたいならパッチ版まで固定)。
  • setup-node のバージョンは、Inspectorの要件(22.19.0以上)を満たすものにする。
  • 本番データではなく、副作用のないツールとテスト用の入力を使う。

失敗の種類で処理を変えたい場合は、終了コードで分岐します。

if out=$(npx @modelcontextprotocol/inspector --cli "$URL" --transport http --method tools/list 2>err.json); then
  echo "$out"
else
  case $? in
    3) echo "認証が必要です" ;;
    4) echo "サーバーに到達できません" ;;
    *) jq .error < err.json ;;
  esac
fi

7. よくあるハマりどころ

症状 原因 対処
CIのジョブが進まない、または auth_required で落ちる OAuthが必要なサーバーに、トークンなしで接続している --stored-auth-only を付け、トークンは別途用意する
サーバー自身のフラグがInspectorに食われる CLIでは、サーバーの引数が -- の前、Inspectorのオプションが後という区切りがある サーバーがフラグを取る場合は -- で区切る。WebやTUIとは区切り方が違うので、コマンドを使い回さない
tools/list は通るのに tools/call が失敗する 一覧の取得は「見つかる」ことしか証明しない 必須引数、入力スキーマ、権限を確認する
期待した機能やタブがない プロトコルの世代(legacy / 2026-07-28のmodern)が合っていない --protocol-era を明示する。既定は legacy
数値のつもりが文字列で届く(またはその逆) --tool-arg はJSONとして解釈される 型を厳密にしたいときは --tool-args-json を使う
Linuxのコンテナで秘密情報が平文で残る キーチェーンがない環境では ~/.mcp-inspector/secrets.json に保存される 暗号化キーを指定するか、使い捨てのランナーで実行する

8. リモートMCPサーバーを検証する場合

ローカルでは通るのに、リモートにデプロイすると失敗することはよくあります。原因はたいていビジネスロジックではなく、ルーティング、認証、公開URLのどれかです。CIでは、ローカルのstdioテストに加えて、デプロイ後のURLにも同じ tools/list を投げると、こうした問題を早く見つけられます。

NodeFlareは、stdioで動くMCPサーバーをリモートのStreamable HTTPエンドポイントに変換してホストするサービスです。NodeFlareでホストしたサーバーも、発行されたURLを --transport http で指定すれば、この記事と同じ手順でCIから検証できます。

9. FAQ

MCP Inspectorとは何ですか?

MCPサーバーをテスト・デバッグするための公式ツールです。@modelcontextprotocol/inspector というnpmパッケージで、Web・CLI・TUIの3つのクライアントを持っています。

MCP Inspectorのインストールは必要ですか?

不要です。npx @modelcontextprotocol/inspector で直接起動できます。Node.js 22.19.0以上が必要です。

MCP InspectorのCLIモードとWeb UIの違いは?

Web UIはブラウザでリクエストを1件ずつ確認するためのものです。CLIモードは1回の実行で1つのメソッドを呼んで終了するため、CIやスクリプトでの自動テストに向いています。

MCP InspectorをCIで使うときに必須のオプションは?

--stored-auth-only です。これを付けると、ブラウザでのOAuth認証を始めず、保存済みトークンがなければすぐに失敗します。あわせて --format json を付けると結果を検証しやすくなります。

MCP Inspectorの終了コード3と4の違いは?

3 はサーバーが認証を求めている(HTTP 401/403など)ことを示します。4 はDNSエラーや接続拒否、タイムアウトなどでサーバーに到達できないことを示します。

tools/callでツールがエラーを返したらどうなりますか?

結果は出力されますが、終了コードは 5 になります。そのため、CIのステップはそこで失敗として扱われます。

リモートのMCPサーバーもMCP Inspectorでテストできますか?

できます。URLを渡して --transport http を指定します。設定ファイルを使う場合は --config と --server で指定します。

MCP Inspectorで負荷テストはできますか?

簡易的なものはできます。tools/call に --load を付けると、並列で繰り返し呼んでレイテンシとエラー率を集計します。--load-max-p99 などで閾値を決めれば、超えたときに終了コード 10 で失敗させられます。

まとめ

  • CIでのMCPサーバーのテストは、MCP Inspectorの --cli モードで十分に組めます。
  • --stored-auth-only と --format json を付け、終了コードで失敗の種類を判断します。
  • まずは「tools/list で存在確認 → 無害なツールを1回 tools/call」から始め、必要に応じて --strict や --load を足していくのがおすすめです。

参考資料

NodeFlare

MCP専用ホスティングサービス

GitHubにあるMCPを簡単デプロイ・簡単運用で最適化
無料で始める

他の記事

MCPトークン2026年11月17日

ツール引数は出力トークン:MCPのトークン消費で見落とされる「書く側」のコスト(write_fileとedit_fileを実測・2026年版)

MCPのツール引数は出力トークンで、単価は入力の5倍、キャッシュも効きません。公式Filesystemサーバーで1行の変更がwrite_file 5,549トークン対edit_file 49トークンになった実測、Sonnet 5.5・Opus 5.5・Fable 5.2での料金試算、ツール間の書き写し、max_tokensでの中断、書き直しの損益分岐、置換ツールのコードまで。

MCPセキュリティ2026年11月17日

MCPのきめ細かな認可:スコープでは防げないBOLAを、オブジェクト・引数・項目単位のチェックで止める【MCP Security 2026】

ツール単位のスコープでは防げない、MCPツールのオブジェクト・引数・項目単位の認可を解説。仕様の「スコープだけで十分とみなすのは誤り」、公式Python SDKを含む2026年のCVE3件、チェックの置き場所、8つのルール、検証済みPythonコード(スコープのみ4/14、多層14/14)とCedarポリシー(12/12)。

MCPホスティング2026年11月17日

Hugging Face SpacesはまだMCP Hostingに無料で使える?Gradioのmcp_server=Trueを2026年の有料化後に検証(Gradio 6.32)

2026年のHugging Face SpacesでのMCP Hosting。新規のGradio SpaceはZeroGPU以外PROが必要、無料ハードウェアは48時間でスリープ、Gradioのキューは既定で1件ずつ。Gradio 6.32で検証した /gradio_api/mcp/ の使い方、188 MB・1回約60 msの実測、Space名の接頭辞、ZeroGPUの上限、費用、Claude Code・Cursorの接続を解説。

MCP Inspector CLIとは?MCPサーバーをCIで自動テストする方法【終了コード一覧・2026年版】 | Blog | Nodeflare