サービスServices制作実績Works自社ツールToolsブログBlogチームTeam会社概要Company
お問い合わせ
← ブログ一覧
AI11分

MCP Inspectorとは？MCPサーバーを検証する公式CLIツールをv2で実際に動かした

  • #MCP Inspector
  • #Model Context Protocol
  • #CLI

MCPサーバーを自分で書いていると、「ハンドシェイクは成功しているのか」「ツールの一覧は想定どおり返っているのか」をいちいちClaude Codeなどの本番クライアントにつないで確認するのは手間がかかります。この隙間を埋めるのが、Model Context Protocolの公式チーム（modelcontextprotocol GitHub organization）が公開している検証ツール「MCP Inspector」です。公式リポジトリのREADMEは、これを「Deterministic testing tools for MCP servers」と位置づけています。

この記事は、公式GitHubリポジトリ（modelcontextprotocol/inspector）のREADMEとdocs/配下の各ドキュメントを一次情報として、実際にこのクラウド環境へ@modelcontextprotocol/inspectorをインストールし、自作の小さなMCPサーバーに対してCLIモードで接続・ツール呼び出しを試した記録です。公式ドキュメントサイト（modelcontextprotocol.io）はこの検証環境のネットワークポリシー上アクセスできなかったため、サイト上の記載は参照せず、GitHubリポジトリ内の記述のみを一次情報としています。

MCP Inspectorとは：4つの顔を持つ単一パッケージ

READMEによると、@modelcontextprotocol/inspectorというnpmパッケージ1つで、次の4通りの使い方ができます。

  • Web：Vite・React・Mantineで作られたシングルページアプリ（Node製バックエンド付き）。ブラウザから手動でMCPサーバーを操作・確認する用途
  • CLI：自動化・CI・エージェントのフィードバックループ向けのコマンドラインクライアント
  • TUI：Inkで作られたターミナル上の対話型UI
  • mcpdo（実験的機能）：1回だけ接続し、名前付きの接続に対してローカルデーモン経由で多数のコマンドを打てる接続CLI

今回はこのクラウド環境がGUIを持たないため、自動化向けのCLIモードを中心に検証しました。

インストールして実際に動かす

READMEにはNode.js >=22.19.0が必要と明記されています。このクラウド環境にはNode.js v22.22.0が入っており、要件は満たしていました。npmでインストールします。

mkdir mcp-inspector-test && cd mcp-inspector-test
npm init -y
npm install @modelcontextprotocol/inspector

エラーなく完了し、npmレジストリのnpm view @modelcontextprotocol/inspector versionでも最新版は2.13.0でした。これはGitHub Releasesページの記載（2026年10月28日公開）と一致しています。インストールされたパッケージのpackage.jsonを見ると、inspector・mcp-inspector・mcpdoという3つのコマンドがbinに登録されていました。

自作のMCPサーバーに対してCLIモードを試す

検証用に、ツールを1つだけ持つ最小限のstdio MCPサーバーを@modelcontextprotocol/sdkで書きました。

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "lexia-test-server", version: "1.0.0" });

server.registerTool(
  "echo",
  {
    title: "Echo",
    description: "Echoes back the given text",
    inputSchema: { text: z.string() },
  },
  async ({ text }) => ({
    content: [{ type: "text", text: `echo: ${text}` }],
  }),
);

const transport = new StdioServerTransport();
await server.connect(transport);

このサーバーに対して、まず--method initializeでハンドシェイクだけを確認しました。

npx mcp-inspector --cli node server.js --method initialize
{
  "serverInfo": { "name": "lexia-test-server", "version": "1.0.0" },
  "protocolVersion": "2025-11-25",
  "capabilities": { "tools": { "listChanged": true } }
}

次に、ツール一覧とツール呼び出しを機械可読な--format jsonで確認しました。

npx mcp-inspector --cli node server.js --method tools/list --format json
{"result":{"tools":[{"name":"echo","title":"Echo","description":"Echoes back the given text","inputSchema":{"type":"object","properties":{"text":{"type":"string"}},"required":["text"],"$schema":"http://json-schema.org/draft-07/schema#"},"execution":{"taskSupport":"forbidden"}}]}}
npx mcp-inspector --cli node server.js \
  --method tools/call --tool-name echo \
  --tool-args-json '{"text":"hello lexia"}' --format json
{"result":{"content":[{"type":"text","text":"echo: hello lexia"}]}}

いずれも終了コードは0でした。ドキュメント（docs/cli-smoke-testing.md）には、ツール呼び出しの結果がisError: trueになった場合は終了コードが5になり、&&で連結したCIパイプラインでも見逃されない設計だと説明されています。終了コードは0（成功）から6（--strictでのスキーマ互換性エラー）まで区分されており、失敗の理由はstderrの最終行に1行のJSON（ErrorEnvelope）として出力されるとのことです。--strict --format jsonを付けて同じtools/listを実行してみましたが、今回の最小サーバーではschemaFindingsは出力に含まれず、スキーマ上の問題は検出されませんでした。

設定ファイル：複数サーバーをまとめて指定する--config

docs/mcp-server-configuration.mdによると、--configで渡すファイルは「Inspectorが書き込まない読み取り専用のセッションファイル」で、トップレベルにmcpServersオブジェクトを置き、そのキーがサーバー名になります。typeはstdio・http・sseのいずれかです。実際に次のファイルを作って動作を確認しました。

{
  "mcpServers": {
    "local": {
      "type": "stdio",
      "command": "node",
      "args": ["server.js"]
    }
  }
}

このファイルを指定してWeb UIを起動すると、次のようなログが出力されました（--configのパスを渡すとWeb UIが既定の起動モードになります）。

[mcp-inspector] The OS keychain is not available, so secrets will be kept in: File (unencrypted) at /root/.mcp-inspector/secrets.json — fell back from the OS keychain.
[mcp-inspector] Keychain error: zbus error: Failed to connect to address `unix:path=/run/user/0/bus`: No such file or directory (os error 2)

MCP Inspector Web is up and running at:
   http://127.0.0.1:6274?MCP_INSPECTOR_API_TOKEN=（トークン文字列）
   Sandbox (MCP Apps): http://127.0.0.1:6275/sandbox

このクラウド環境にはOSキーチェーン（D-Bus）が無いため、secretsの保存先が自動的にファイル（暗号化なし、パーミッション0600）にフォールバックする様子が実際に確認できました。これはdocs/secret-storage.mdに書かれている既定の挙動どおりです。一方で、この検証ではWeb UIの起動ログを確認するところまでで、ブラウザから実際に操作する画面までは試していません。本記事で詳しく検証したのは、ヘッドレス環境でも完結するCLIモードです。

v1からv2での変更点

docs/v1-to-v2-migration.mdには、v2が単なるマイナーアップデートではなく書き直し（rewrite）だと明記されています。主な変更点は次のとおりでした。

  • Node.jsの要件が>=22.7.5から>=22.19.0に上がった
  • v1では4つに分かれていたパッケージが、@modelcontextprotocol/inspector1つに統合された
  • v1にあったMCPプロキシ（ポート6277）が廃止され、UIは単一のサーバー（ポート6274）で動くようになった
  • サーバー一覧の保存先が、ブラウザのlocalStorageから~/.mcp-inspector/mcp.jsonなどのカタログファイルに変わり、Web・CLI・TUIで共有されるようになった
  • 新しい起動モードとして--tuiが追加された
  • 認証トークンの環境変数名がMCP_PROXY_AUTH_TOKENからMCP_INSPECTOR_API_TOKENに変わった（旧名は非推奨のフォールバックとして残る）
  • --configの意味が変わり、v2では読み取り専用になった。書き込みが必要な場合は新しい--catalogを使う

v1にまだ依存している場合は、npx @modelcontextprotocol/inspector@v1-latestで起動できるとREADMEに案内があります。ただしv1系はセキュリティ修正のみで新機能は追加されない、とも明記されています。

CIでの使い方：スモークテストという位置づけ

docs/cli-smoke-testing.mdは、MCP Inspectorを「コミットやデプロイごとに数秒で、サーバーが生きていてMCPを話すかを確認する」CIの仕組みとして使う方法を具体的に説明しています。ポイントをいくつか拾うと次のとおりです。

  • CIでは@2のような範囲指定ではなく、npx --yes @modelcontextprotocol/inspector@2.13.0 --cliのように正確なバージョンを固定することが推奨されている
  • --connect-timeoutは必ず指定し、既定値（アドホック実行で15000ms）に頼らないようにする。0を指定するとタイムアウトが無効になりCIが止まる恐れがある
  • 対話型OAuthはブラウザを開いて最大15分待機するため、CIでは--stored-auth-onlyで「保存済みトークンだけで試し、無ければ即座に終了コード3で終わる」ようにする
  • 出力に秘密情報らしき文字列が含まれていないかをgrepで確認する手順も、簡易なチェックとして紹介されている

単体のGUIツールというより、CIに組み込むことを前提に終了コードやJSON出力の形式まで整えられている点が、他の多くのGUI系デバッガとは異なる印象でした。

セキュリティ関連の更新（2.13.0・2.12.0）

GitHub Releasesページによると、確認時点（2026年10月30日）での最新版は2026年10月28日公開の2.13.0で、直前の2.12.0（10月21日）と合わせてセキュリティ関連の変更が続いていました。

  • 2.13.0：OAuthの送信先について、リンクローカルアドレスやクラウドのメタデータ用アドレスへの接続を防ぐガードを追加。CLIに負荷試験用のしきい値オプション（エラー率・p99レイテンシ）と--load-connectionsを追加。MCP TypeScript SDKを2.4.0に更新し、公開済みのアドバイザリに対応するundici・fast-uriの版に更新。加えて、npm経由で実行する場合はパッチ済みのNode.js（22.23.4、24.22.1、26.12.1以降）を使うよう注意が追加されている
  • 2.12.0：URLを開く処理をhttp(s)に限定。本番用WebサーバーがHostヘッダーを検証し、許可リスト外のホストには403を返すように変更（リバースプロキシ向けにMCP_INSPECTOR_ALLOWED_HOSTSを追加）。/api/fetchプロキシの上流レスポンス本文を4 MiBに制限。Web UIをHTTPSで提供する任意のTLS設定を追加

この検証環境のNode.jsはv22.22.0で、2.13.0のリリースノートが挙げる「パッチ済み」バージョン（22.23.4以降）には達していませんでした。今回は信頼できる自作のローカルサーバーに対してのみ接続したため実害はありませんでしたが、本番やCIでMCP Inspectorを使う場合は、リリースノートの案内どおりNode.jsのバージョンを合わせておくほうが安全です。

ライセンス

リポジトリのLICENSEファイルは単一のライセンスではなく、3種類を併記した構成でした。新規コードおよび再ライセンスに同意した貢献にはApache License 2.0、再ライセンスに同意していない従来の貢献にはMCP発足時からのMITライセンス（著作権表示そのまま）、仕様を除くドキュメントにはCC-BY-4.0が適用されます。Apache-2.0部分は特許訴訟を起こした場合にその貢献者の特許ライセンスが終了する条項を含み、配布時にはNOTICEファイルでの帰属表示が必要です。

向いている場面・向いていない場面

  • 向いている：自分でMCPサーバーを実装していて、Claude Codeなど本番クライアントにつなぐ前にtools/listやtools/callを手早く確認したい場合。CIにMCPサーバーのスモークテストを組み込みたい場合も、終了コードと--format jsonがそのまま使えます
  • 向いていない：ストリーミングやセッション依存のメソッド（logging/tailなど）、レンダリングが必要なMCP Appのウィジェット確認。公式ドキュメントの「対象外」セクションにも、CLIモードの対象から明確に外れると明記されています

まとめ

MCP Inspectorは、MCPサーバーの動作確認を「ブラウザでクリックして試す」から「CLIで自動化してCIに組み込む」まで一通り揃えた公式ツールでした。実際にこのクラウド環境へインストールし、自作のstdioサーバーに対してinitialize・tools/list・tools/callをCLIモードで実行して正しい応答が返ることを確認できたほか、OSキーチェーンが無い環境でsecretsの保存先が自動的にファイルへフォールバックする挙動も実際のログで確認できました。一方でWeb UI・TUIの操作画面そのものや、認証が必要なMCPサーバーに対する挙動は今回は確認できていません。v2になってNode.jsの要件や終了コードの意味が変わっているため、v1からの移行を検討している場合はdocs/v1-to-v2-migration.mdを先に読んでおくのが安全です。

参考にした一次情報

関連記事

まずは、やりたいことを聞かせてください

「何から手をつければいいか分からない」段階でも大丈夫です。 ご相談・お見積りは無料。碧南近郊なら直接伺います。

お問い合わせ090-1742-3456