MCP Inspector 実践ガイド：MCP サーバーのテストとデバッグ

MCP Inspector は、Model Context Protocol サーバーをテスト・デバッグするための公式開発者ツールです。npx @modelcontextprotocol/inspector を実行するとブラウザ UI が開き、任意の stdio または Streamable HTTP サーバーに接続して、ツールの呼び出し、リソースの読み取り、プロンプトのレンダリング、生の JSON-RPC トラフィックの確認ができます。同じパッケージには、CI 向けのスクリプト可能な CLI（--cli）とターミナル UI（--tui）も含まれています。

本ガイドは Inspector の現行 v2 系（執筆時点で 2.11）を対象にしています。ポート 6277 のプロキシや MCP_PROXY_AUTH_TOKEN に言及している古いチュートリアルは v1 のものです——違いは以下で説明します。

MCP Inspector とは（v2 で何が変わったか）

Inspector は、人間の開発者向けに作られたリファレンス MCP クライアント です。サーバーを Claude や Cursor などのホストに組み込んで、ツールが表示されない理由を推測する代わりに、Inspector で直接接続すれば、サーバーが何を公開し何を返しているかを正確に確認できます。

公式ドキュメントによると、現在は 1 つのパッケージ・1 つのバイナリに 3 つのクライアントが含まれています：

移行ガイドにある v2 の主な変更点：

• Node 22.19.0 以上が必要です。 古い Node でもインストールはできますが、後でわかりにくい形で失敗します——まず node -v を確認してください。
• プロキシは廃止されました。 v1 は 6274 で UI、6277 でプロキシを動かしていました。v2 は 6274 の Web サーバー 1 つだけです（MCP Apps 用のサンドボックスが 6275 で別に動きます）。
• サーバー一覧はカタログファイル（~/.mcp-inspector/mcp.json）に保存され、Web・CLI・TUI で共有されます。ブラウザの localStorage ではなくなりました。
• 認証トークンの名前が変わり、MCP_INSPECTOR_API_TOKEN になりました（旧名もフォールバックとして使えます）。
• v1 が必要な場合 は npx @modelcontextprotocol/inspector@v1-latest で固定します。

Inspector を起動する

インストールは不要です。Node 22.19 以上で：

# サーバーなしで Web UI を開き、Servers タブからサーバーを追加する
npx @modelcontextprotocol/inspector

# ローカルの stdio サーバーを指定して Web UI を開く
npx @modelcontextprotocol/inspector node build/index.js

コマンドは起動ごとのセッショントークンを含む URL を表示し、ブラウザで開きます。localhost:6274 を手入力せず、表示された URL を使ってください——バックエンドはマシン上でプロセスを起動できるため、すべての API 呼び出しがこのトークンで保護されています。ブラウザタブを自動で開きたくない場合は MCP_AUTO_OPEN_ENABLED=false を設定します。

初回起動時、Web クライアントはカタログに 3 つのサンプルサーバー（/tmp に限定されたファイルシステムサーバー、"everything" リファレンスサーバー、ホスト型のサンプルサーバー）を登録するので、自分のサーバーをつなぐ前に操作を試せます。

stdio サーバーに接続する

ローカルサーバーの場合は、起動コマンドを位置引数として渡します。Inspector 自身のフラグの後ろがサーバーコマンドになります：

# 開発中のサーバー
npx @modelcontextprotocol/inspector node build/index.js

# 公開済みの npm サーバー
npx -y @modelcontextprotocol/inspector npx @modelcontextprotocol/server-filesystem ~/Desktop

# uvx 経由で公開済みの Python サーバー
npx @modelcontextprotocol/inspector uvx mcp-server-git --repository ~/code/my-repo

# 環境変数とサーバーのフラグ
npx @modelcontextprotocol/inspector -e API_KEY=xxx -- node build/index.js --verbose

環境変数は -e KEY=value、サーバーの作業ディレクトリは --cwd <path> で指定します。Web と TUI クライアントでは、-- 以降はすべてサーバーコマンドに渡されます。Filesystem サーバーは tools・resources・roots 機能を一通り試せるので、最初のテスト対象として最適です。

Streamable HTTP（リモート）サーバーに接続する

リモートサーバーの場合は URL を渡します。Inspector はパスの末尾 だけ からトランスポートを推定します：

# パスが /mcp で終わるので Streamable HTTP と推定される
npx @modelcontextprotocol/inspector --server-url https://api.example.com/mcp --transport http

# それ以外のパスでは --transport が必要
npx @modelcontextprotocol/inspector --cli https://api.example.com/v1 --transport http --method tools/list

# 静的な API キーや Bearer ヘッダー
npx @modelcontextprotocol/inspector --cli https://api.example.com/mcp \
  --header "Authorization: Bearer $TOKEN" --method tools/list

末尾のスラッシュ（/mcp/）も判定不能扱いになる点に注意してください。v1 はこの場合に黙って SSE にフォールバックしていましたが、v2 は推測しません。Web UI の Servers タブからサーバーを追加し、Server Settings でヘッダー、タイムアウト、OAuth を設定することもできます。

Web UI で Tools・Resources・Prompts をテストする

接続後、タブバーにはサーバーの機能がサポートするものだけが表示されます：

実践的なテストの流れ：

1. Tools を開いてツールを選び、正しい呼び出しと、わざと誤った呼び出し（必須フィールドの欠落、型の誤り）の両方を試します。良いサーバーは、モデルが自己修正できるような明確なツールエラーを返します。
2. クリックしながら Protocol を見ます。モニタリンググループをピン留めすると、Tools の横に右サイドバーとして常に表示されます。
3. 何かが静かに失敗したら、Console（stdio）または Network（HTTP）を確認します——スタックトレースや 401 はそこに出ます。
4. Resources で MIME タイプとテンプレートの解決を確認します。リソースとツールのどちらにすべきか迷ったら、MCP の resources と tools の違いを参照してください。

Tools タブは スキーマの移植性 の問題——技術的には有効でも一部の実際のクライアントが拒否する JSON Schema——も警告してくれます。サーバーを公開する前に確認する価値があります。

サーバーごとの Server Settings では、roots、ヘッダー、タイムアウト、OAuth 項目、そしてページネーションのテスト用の「Fetch Lists One Page at a Time」トグルを設定できます。多数のツールを公開するサーバーでは便利です（MCP のツール検出を参照）。

スクリプト化：CI とエージェント向けの CLI モード

CLI モードは接続して 1 つの --method を実行し、結果を出力して終了します。モードフラグは先頭に置く必要があります：

# ツールの一覧
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list

# key=value 形式の引数でツールを呼び出す
npx @modelcontextprotocol/inspector --cli node build/index.js \
  --method tools/call --tool-name mytool --tool-arg key=value --tool-arg count=3

# 引数を 1 つの JSON オブジェクトで渡す（型変換なし）
npx @modelcontextprotocol/inspector --cli node build/index.js \
  --method tools/call --tool-name mytool --tool-args-json '{"id":"012"}'

# リソースとプロンプト
npx @modelcontextprotocol/inspector --cli node build/index.js --method resources/list
npx @modelcontextprotocol/inspector --cli node build/index.js --method prompts/list

# jq 向けの機械可読出力
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list --format json | jq '.result.tools[].name'

サポートされるメソッドには initialize、tools/list、tools/call、resources/list、resources/read、resources/templates/list、prompts/list、prompts/get などがあります。自分で書いていない設定ファイル（たとえばクライアントの mcp.json）からサーバーを選ぶには、読み取り専用の --config と --server を組み合わせます：

npx @modelcontextprotocol/inspector --cli --config ./mcp.json --server myserver --method tools/list

CLI には安定した終了コードがあり、CI のスモークテストに向いています：

失敗時には stderr に 1 行の JSON エラーを書き出します。v1 との違いに注意してください：以前はツール呼び出しが失敗しても終了コード 0 でしたが、v2 では 5 で終了します。そのため、これまで黙って通っていた CI パイプラインが失敗し始めることがありますが、それが正しい挙動です。

認証と OAuth

MCP の認可を使うサーバーでは、Inspector が OAuth フローを処理してくれます：

• Web UI：Server Settings で OAuth（クライアント ID／シークレット、スコープ、リフレッシュトークン）を設定します。登録すべき Redirect URI はそこに表示され、デフォルトは http://localhost:6274/oauth/callback です。
• CLI と TUI：401 を受け取ると、CLI は http://127.0.0.1:6276/oauth/callback でループバックのコールバックを起動し、認可 URL を表示してブラウザを開き、サインイン後に再試行します。--callback-url で上書きできます。
• CI：--stored-auth-only を使えば、ブラウザを待つことなく auth_required（終了コード 3）ですぐに失敗します。
• 静的キー：--header "Authorization: Bearer ..." を渡すだけです。

トークンは利用可能であれば OS のキーチェーンに保存されます。キーチェーンのないマシン（ヘッドレス Linux、コンテナ）では ~/.mcp-inspector/secrets.json にフォールバックしますが、このファイルは キーを指定しない限り暗号化されません。共有マシンでは注意し、MCP セキュリティのベストプラクティスも参照してください。

よくあるエラーと対処法

Docker では、公式イメージ ghcr.io/modelcontextprotocol/inspector:latest をループバックでのみ公開してください：docker run --rm -p 127.0.0.1:6274:6274 ghcr.io/modelcontextprotocol/inspector:latest。

Inspector と実際のクライアントの使い分け

Inspector は「サーバーは正しく動いているか？」——スキーマ、結果、エラー、認証、ページネーション——を確かめるために使います。そのうえで実際のホストに移り、「モデルはそれをうまく使えるか？」——ツールの説明、命名、コンテキストのコスト——を確かめます。この 2 つ目のステップは Claude Code、Codex、ChatGPT のセットアップガイドで解説しています。Inspector では動くのにクライアントでは動かない場合、原因はほぼ必ずクライアント側（設定、認証、スキーマの扱い）にあります。

次のステップ

• MCP.so ディレクトリからサーバーを選び、Inspector で接続してみましょう——GitHub MCP Server、Playwright MCP、Context7 はドキュメントが充実していて試しやすい対象です。
• サーバーの CI に CLI のスモークテスト（--method tools/list --format json）を追加しましょう。
• ツールが多い、または変化するサーバーを作っているなら、次は MCP のツール検出を読んでください。