MCP Inspectorの使い方 — 自作サーバーの動作確認とデバッグ手順

MCP Inspectorとは — 自作サーバーの動作確認に使う公式ツール

MCP Inspectorは、MCP(Model Context Protocol)サーバーの動作確認とデバッグに特化した公式ツールです。@modelcontextprotocol/inspectorという単一パッケージに、Web・CLI・TUIの3つのクライアントが同梱されており、npxでその場で起動できます。インストール作業は不要です。

自作したサーバーをClaude CodeやClaude Desktopにいきなり繋ぐと、失敗したときに原因の切り分けが難しくなります。クライアント側の問題なのか、サーバーの実装ミスなのか、認証の設定ミスなのかが混ざって見えるからです。MCP Inspectorはこの間に挟まり、サーバー単体を人間が操作できる形で見せてくれます。ツール呼び出しの引数と戻り値、JSON-RPCの生トラフィック、認証フローの途中経過まで、実際のクライアントに繋ぐ前に目視で確認できるのが最大の価値です。

2.1.0は2026年8月5日に公開されました。動作にはNode.js 22.19.0以上が必要です。サーバーを一から書く手順はMCPサーバー自作ガイドが扱う範囲です。MCPの仕組み自体はMCP実用ガイドにまとめてあります。本記事はInspectorでの動作確認とデバッグの手順に絞ります。

起動前に確認すること — 3つのクライアントの使い分け

mcp-inspectorバイナリはランチャーで、実際の処理は3つのクライアントのどれかに委譲されます。モードを選ぶフラグ(--web / --cli / --tui)はコマンドの先頭に置く必要があり、それ以降の引数はすべて選んだクライアントへそのまま渡されます。

3クライアントは同じ接続コアを共有しています。トランスポート、設定ファイルの読み方、ディスク上のOAuth状態はすべて共通です。Webでログインを済ませておけば、CLIやTUIから同じ認証状態を再利用できます。

Webクライアントで自作サーバーに接続する

stdio(標準入出力)方式のサーバーは、起動コマンドをそのまま引数に渡します。

npx @modelcontextprotocol/inspector node build/index.js

起動するとトークン付きのURLがターミナルに表示されます。そのURLをそのまま開いてください。localhost:6274を記憶から直接入力すると、Node側のAPIサーバーがトークン未一致で全リクエストを拒否します。バックエンドはローカルマシン上でプロセスを起動する権限を持つため、この認証は毎回のランダムトークンによるものです。固定したいときはMCP_INSPECTOR_API_TOKEN環境変数でトークンを指定できます。

接続後の画面は、サーバーが実際に持つ能力(capability)によって変わります。toolsがあればToolsタブが、resourcesがあればResourcesタブが、promptsがあればPromptsタブが現れます。よく使うのは次の3系統です。

• Tools: スキーマがフォームとして描画され、値を入力して呼び出すと結果が下に表示されます。引数の型ミスもここで即座に分かります
• Protocol: JSON-RPCのやり取りをリクエストとレスポンスの組で見せる生トラフィックのログです
• Console(stdioサーバーのみ): サーバープロセスの標準エラー出力です。多くのstdioサーバーは自分の診断情報をここに吐くため、接続が理由もなく失敗したときはまず確認します

Protocol・Network・Consoleを含む監視系タブは「ピン留め」すると右側の固定カラムに移動し、Toolsを操作しながら同時に見られます。

CLIクライアントで一発検証・CI組み込みをする

CLIは1回の起動につき1つのメソッドを実行して結果を返し、そのまま終了します。人間が画面を見る前提のWebと違い、シェルやCIパイプラインに組み込む前提の設計です。

npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list

ツールを呼ぶときは--tool-argと--tool-args-jsonの2通りがあり、挙動が違います。--tool-arg key=valueはJSONとしてパースするためcount=1は数値になり、"012"は12に変換されます。--tool-args-jsonは引数オブジェクトを丸ごと渡し、パースせず文字列のまま扱う仕様です。厳密な型を渡したいときは後者を選びます。

--format jsonを付けると、バナー無しのJSON一行だけが標準出力に流れ、jqにそのままパイプできます。非ゼロの終了コードは失敗の種類ごとに固定されているため、呼び出し側は文言をパースせずに分岐できます。

CI組み込みの典型形はこうなります。

mcp-inspector --cli --config ./ci-servers.json --server my-server \
  --stored-auth-only --method tools/list --format json \
  | jq -e '.result.tools | map(.name) | index("get_weather")' > /dev/null

--configは読み取り専用でファイルを一切書き換えません。自分の作業用サーバー一覧を編集したいときは--catalogを使い、他人の設定ファイルをそのまま読みたいときは--configを使う、と役割で分けます。

TUIクライアントをリモート・ヘッドレス環境で使う

TUIはターミナル内で完結するインターフェースで、SSH接続先やGUIを持たない検証環境に向きます。動作には実TTYが必要なので、ヘッドレスなCIジョブでは動きません。そこはCLIの役割です。

npx @modelcontextprotocol/inspector --tui node build/index.js

矢印キーまたはTabでタブを切り替え、cで接続、dで切断、EscかCtrl+Cで終了します。CLIと違って--server <name>で1台を指定するフラグが無く、設定ファイル内の全サーバーを読み込んで画面上のリストから選ぶ形です。OAuthが必要なサーバーではcを押すだけでブラウザでの認可フローが自動的に始まり、コールバックが返れば再度cを押さずに接続が完了します。

OAuth認証が必要なリモートサーバーを検証する

リモートのMCPサーバーの多くは認可を要求します。Inspectorは3クライアントすべてで同じOAuthフローを実装しており、取得したトークンはディスク上で共有されるため、Webで一度ログインすればCLIやTUIからも使い回せます。仕組みの全体(401応答からのディスカバリー、PKCE付きトークン取得までの流れ)はリモートMCPのOAuth認証が扱う内容です。ここではInspector固有の挙動に絞ります。

コールバックURLはクライアントごとに違います。Webはメインアプリのlocalhost:6274/oauth/callbackが窓口です。CLIとTUIは衝突を避けるため、専用の127.0.0.1:6276/oauth/callbackを共有します。事前登録が必須なIdP(アイデンティティプロバイダー)を使うなら、このURLを一度登録しておけば繰り返し使えます。

CIのような非対話環境では、ブラウザを開いて15分待つような事態を避ける必要があります。

• --stored-auth-only: 対話的なOAuthを一切開始せず、保存済みトークンがあればそれを使い、無ければ即座にauth_requiredで失敗します。CI向けの選択肢です
• --use-stored-auth: 人間がWebクライアントで完了させたログインを再利用し、リフレッシュトークンがあれば先に更新してから使います
• --print-handoff: リモートVM上でCLIを動かしつつ、認可はローカルのブラウザで完了させたいときに使う情報一式(ディープリンクとポートフォワードのコマンド)を出力します

よくあるつまずきと対処

• localhost:6274を直接開いてトークンエラーになる場合: 起動時に表示されたトークン付きのURLを毎回そのまま開きます。ブックマークやページ再読み込みではトークンがindex.html側に埋め込まれているため引き続き動きます
• --configで指定したファイルを編集しても反映されない場合: --configは読み取り専用の仕様です。書き込みたい作業用の一覧は--catalogで開きます
• サーバー自身に渡したい引数がInspectorに横取りされる場合: node build/index.js -- --verboseのように--区切りを挟むと、それ以降はサーバーへそのまま渡ります
• stdioサーバーへの接続が理由もなく失敗する場合: 多くはサーバー側が理由を標準エラー出力に書いています。WebならConsoleタブ、TUIならoキーのタブをまず確認します
• CIでOAuthを求められて処理が止まる場合: --stored-auth-onlyを付け忘れると対話的フローに入り、TTYの無い環境では待ち続けます
• Dockerでポートを-p 8080:6274のように付け替えたら接続時に403になる場合: ブラウザのオリジンがコンテナ内部のポートと一致しなくなっています。ALLOWED_ORIGINSに付け替え後のオリジンを追加します

まとめ — 自作サーバーを検証する開発フロー

Inspectorを使う一連の流れは、CLIで固める形に収束させると再現性が高くなります。まず--method initializeで接続・ハンドシェイク・想定した機能の有無を1秒で確認する段階です。次にWebクライアントに移り、スキーマ駆動のフォームで実際にツールを呼び、結果とProtocolタブを並べて挙動を追います。不正な入力や必須引数の欠落、同時呼び出しといった境界条件も試し、失敗が意図した形で返るかまで確かめます。最後に、見つけた期待値をCLIの--format jsonとjq -eでCIのアサーションに固定するところまでが1つの流れです。

この一巡を終えれば、あとはClaude Codeへclaude mcp addで登録するだけです。登録の構文やスコープの違いはClaude Code MCP設定ガイドにまとめてあります。接続後に「繋がらない」で詰まった場合は、別の入口があります。設定・起動・認証・ツール表示の4層で切り分けるMCPサーバーに接続できないときの切り分け手順です。

よくある質問

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

不要です。npx @modelcontextprotocol/inspectorで毎回最新版がその場で起動します。ソースからビルドする場合を除き、事前のセットアップ作業はありません。

Web・CLI・TUIはどれか1つを選べばいいですか

用途で使い分けるのが基本です。3つは同じ接続コアとOAuth保存領域を共有しているため、Webでログインした認証状態をCLIやTUIからそのまま使い回せます。開発中はWebで探索し、固まった時点でCLIに落とす、という組み合わせが典型です。

リモートのHTTPサーバーも検証できますか

できます。--server-url https://api.example.com/mcp --transport httpのように指定します。Server-Sent EventsのSSEトランスポートにも対応済みです。

Claude Desktopの設定ファイルをそのまま読み込めますか

読み込みも可能です。Webクライアントの画面からClaude Desktop・Cursor・Cline・VS Codeの設定ファイルをインポートできます。または--config ~/Library/Application\ Support/Claude/claude_desktop_config.jsonのように、読み取り専用で直接開くこともできます。

Dockerで動かせますか

動きます。ghcr.io/modelcontextprotocol/inspectorイメージがlinux/amd64とlinux/arm64向けに公開済みです。docker run --rm -p 6274:6274 ghcr.io/modelcontextprotocol/inspectorで起動できます。コンテナはワイルドカードアドレスへのバインドが前提のため、通常のローカル起動とは異なりDANGEROUSLY_BIND_ALL_INTERFACES=trueが既定で設定されています。