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ステップです。
目次
- MCP Inspectorとは
- Web・CLI・TUIの比較
- CLIの基本コマンド
- 終了コード一覧
- CIで使うフラグ
- GitHub Actionsでの実装例
- よくあるハマりどころ
- リモートMCPサーバーを検証する場合
- 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を足していくのがおすすめです。
