MCP Inspectorの使い方｜ツールを単体テストして接続エラーを調べる

MCPサーバーを作成したものの、Claude DesktopやAIエージェントから接続すると、

MCP server disconnected
Connection failed
Tool not found

といったエラーが発生することがあります。

このとき、Claude DesktopやVS CodeなどのHostアプリだけを使って原因を調べると、

MCPサーバーが悪いのか

Host側の設定が悪いのか

stdioの起動コマンドが悪いのか

環境変数が不足しているのか

MCP Protocolの互換性なのか

Toolそのものが失敗しているのか

を切り分けにくくなります。

そこで利用したいのがMCP Inspectorです。

MCP InspectorはMCP公式のテスト・デバッグツールで、Hostアプリを介さずMCPサーバーへ直接接続できます。

現在のMCP InspectorはWeb UIだけでなく、CLIとTUIも同じ@modelcontextprotocol/inspectorパッケージから利用できます。Web版ではTools、Resources、Promptsなどを確認しながら、Protocol、Network、stdioのConsoleを同時に監視できます。

特に便利なのが、MCPツールを1つずつ単体で実行できることです。

たとえばClaude Desktopでは失敗するsearch_documentsをInspectorから直接実行して成功するなら、

MCP Server: 正常

Tool: 正常

Claude Desktopとの接続・設定: 要確認

と原因を絞れます。

この記事では、2026年版のMCP Inspectorを使ってstdio・Streamable HTTPのMCPサーバーへ接続し、Toolを単体テストしながら接続エラーを切り分ける方法を解説します。

MCP Inspectorとは

MCP Inspectorは、Model Context Protocol公式のMCPサーバーテストツールです。

2026年8月現在のInspectorはV2系へ移行しており、1つの@modelcontextprotocol/inspectorパッケージからWeb、CLI、TUIの3種類を利用できます。旧V1系はLegacy扱いとなっています。

通常はWeb版を使うのが分かりやすいでしょう。

npx @modelcontextprotocol/inspector

CLIなら、

npx @modelcontextprotocol/inspector --cli

TUIなら、

npx @modelcontextprotocol/inspector --tui

です。

公式ドキュメントではWeb版が最も機能の多いInspectorとして位置付けられており、CLIはCIや自動テスト、TUIはブラウザを使わないインタラクティブな確認に向いています。

MCPのstdioとStreamable HTTPという2つのTransportについてはMCPのstdioとStreamable HTTPの違い｜ローカル・リモート構成の選び方で詳しく解説しています。この記事では基本的にWeb版を使います。

MCP Inspectorの必要環境

現在のMCP Inspector V2にはNode.js 22.19.0以上が必要です。

インストールして常駐させる必要はなく、npxから直接起動できます。

最初にNode.jsのバージョンを確認します。

node -v

たとえば、

v22.19.0

以上なら現在の必要条件を満たします。

古いNode.jsを使用していてInspector自体が起動しない場合、MCPサーバーを調べる前にNode.jsを更新します。

MCP Inspectorを起動する

まず引数なしで実行できます。

npx @modelcontextprotocol/inspector

InspectorのWebサーバーが起動すると、ターミナルへブラウザ用URLが表示されます。

現在のWeb Inspectorでは、バックエンドAPIがローカルプロセスを起動できるため、起動ごとにセッショントークンで保護されています。

そのため、ターミナルへ表示されたURLをそのまま開きます。

単純にブラウザへ、

手入力しない方がよい例

http://localhost:6274

localhost

と手入力するより、Inspectorが出力したトークン付きURLを利用するのが確実です。Inspectorはページロード時にもトークンを復元できる仕組みを持っています。

stdioサーバーならコマンドごとInspectorへ渡す

ローカルMCPサーバーをstdioで起動している場合は、Inspector起動時にMCPサーバーのコマンドを直接渡せます。

たとえばMCPサーバーが、

node build/index.js

で起動するなら、

npx @modelcontextprotocol/inspector node build/index.js

とします。

Inspector自身が、

Inspector
↓
node build/index.js を起動
↓
stdin / stdoutでMCP接続

という構成を作ります。

公式Quickstartでも、この方法がローカルstdioサーバーを検査する基本形として案内されています。

TypeScriptなら先にビルドする

TypeScriptでMCP Serverを書いており、

src/index.ts

しか存在しない場合は、実際の起動方法に合わせます。

たとえば、

npm run build

によって、

build/index.js

が生成される構成なら、

npx @modelcontextprotocol/inspector node build/index.js

です。

Claude Desktopなど本番Hostが、

{
  "command": "node",
  "args": [
    "C:\\mcp\\my-server\\build\\index.js"
  ]
}

で起動するなら、Inspectorでもできるだけ同じCommandとArgumentsを再現します。

「Inspector専用の別起動方法」を使うと、本番環境だけで発生する問題を再現できない場合があります。

Windowsでは絶対パスでも確認する

MCPサーバーが、

node build/index.js

では動くのにClaude Desktopでは起動しない場合、Working Directoryが違う可能性があります。

MCP公式のDebugging Guideでも、stdioサーバーをHostから起動した場合はWorking Directoryが開発時のターミナルと同じとは限らないため、Commandやファイル参照には絶対パスを利用することが推奨されています。

WindowsならInspectorから次のように確認できます。

npx @modelcontextprotocol/inspector node "C:\work\my-mcp\build\index.js"

これで動くなら、

node build/index.js

という相対パスがHost環境で解決できていない可能性があります。

–cwdでWorking Directoryを再現できる

InspectorにはstdioサーバーのWorking Directoryを指定する--cwdがあります。

たとえば、

npx @modelcontextprotocol/inspector --cwd "C:\work\my-mcp" node build/index.js

とできます。

MCPサーバー内部で、

readFile("./config.json");
dotenv.config();

など相対パスを利用している場合、Working Directoryによって結果が変わる可能性があります。

Inspectorで--cwdを変更して再現できるなら、接続エラーの原因をかなり絞れます。

環境変数もInspectorから渡せる

MCPサーバーがAPIキーなどを必要とする場合は、

MCPサーバーは起動する
↓
Tool実行時だけ失敗する

ということがあります。

Inspectorではstdioサーバーへ-e KEY=VALUEで環境変数を渡せます。

たとえば、

npx @modelcontextprotocol/inspector -e API_KEY=test-key node build/index.js

とします。

複数なら繰り返します。

npx @modelcontextprotocol/inspector ^
  -e API_KEY=test-key ^
  -e API_BASE_URL=https://example.com ^
  node build/index.js

Windowsのコマンドプロンプトなら^、PowerShellなら1行にするかPowerShell向けの改行記法へ変更します。

公式Debugging Guideでも、stdioサーバーがHostから起動された場合に利用できる環境変数は実行環境によって異なるため、必要な値を明示的に設定して確認する方法が案内されています。

.envがあるだけでは安心できない

プロジェクト直下に、

.env

があっても、MCPサーバーが必ずそのファイルを読み込むとは限りません。

たとえば、

process.env.API_KEY

を直接参照しているだけなら、.envファイルの存在だけで環境変数へ読み込まれるわけではありません。

さらにWorking Directoryが変われば、相対パスで.envを探している処理が失敗する場合もあります。

Inspectorから、

npx @modelcontextprotocol/inspector -e API_KEY=test-key node build/index.js

では成功するのに、

npx @modelcontextprotocol/inspector node build/index.js

では失敗するなら、環境変数周辺を重点的に確認できます。

サーバー自身の引数には–を使う

MCPサーバー自身にも、

--config

などのオプションがある場合は注意が必要です。

Inspectorにも--configというオプションがあるため、そのまま書くとInspector側の引数として解釈される可能性があります。

現在のInspectorでは、裸の--より後ろを対象stdioサーバーの引数として渡せます。

たとえば、

npx @modelcontextprotocol/inspector node build/index.js -- --config ./server.json --verbose

です。

これなら、

--config ./server.json

はInspectorではなく、

node build/index.js

側へ渡ります。

Streamable HTTPサーバーへ接続する

リモートMCPサーバーやローカルHTTPサーバーなら、Server URLを指定します。

たとえば、

待ち受け先の例

http://localhost:3000/mcp

localhost

でMCPサーバーが待ち受けている場合は、

npx @modelcontextprotocol/inspector \
  --server-url http://localhost:3000/mcp \
  --transport http

とします。

現在のInspectorではhttpがStreamable HTTPを表します。

公式ドキュメントでも、リモートHTTPサーバーは--server-urlと--transport httpで指定できます。

HTTPヘッダーも指定できる

認証付きMCP Serverでは、

Authorization: Bearer ...

などのHeaderが必要なことがあります。

InspectorではHTTP／SSEサーバーへ--headerを指定できます。

たとえば、

npx @modelcontextprotocol/inspector \
  --server-url http://localhost:3000/mcp \
  --transport http \
  --header "Authorization: Bearer test-token"

です。

認証なしなら接続できるのに本番URLだけ失敗する場合は、HeaderやOAuth設定を疑えます。

まずinitializeが成功するかを見る

Inspectorへ接続したら、いきなりToolを実行するのではなく接続そのものを確認します。

MCP ClientとServerは接続時にProtocolやCapabilitiesを確認します。

Inspector CLIなら、

npx @modelcontextprotocol/inspector \
  --cli \
  node build/index.js \
  --method initialize

を実行できます。

現在のCLIではinitializeを接続確認用Probeとして利用でき、Server Info、Protocol Version、Capabilities、Instructionsなどを確認できます。

これが失敗するなら、Tool以前の問題です。

起動コマンド

Transport

Protocol Version

認証

Server初期化

などを確認します。

Web版ではProtocolタブを見る

Web InspectorにはProtocolタブがあります。

ここではMCPで実際に送受信されたJSON-RPCのRequest、Response、Notificationを確認できます。

接続時には、

initialize

やProtocol Negotiationに関する通信を確認できます。

Toolを実行すれば、

tools/call

のRequestとResponseも確認できます。

「画面にはConnection failedとしか出ない」という場合でも、Protocolタブを見ることでMCPレベルのエラーコードを確認できることがあります。

2026-07-28ではProtocol Eraにも注意する

現在のInspector V2にはServerごとに、

legacy
auto
modern

というProtocol Era設定があります。

2026-07-28版MCPではProtocolに大きな変更があったため、Inspectorは旧世代と新世代を明確に区別しています。

Inspectorの初期値はlegacyです。

autoでは最初にserver/discoverを試し、Modern Serverでは新仕様へ接続し、対応していなければLegacyへフォールバックします。

modernでは2026-07-28へ固定され、対応していないServerなら明示的に失敗します。

最新SDKで2026-07-28対応サーバーを開発している場合は、Server SettingsからProtocol Eraを確認します。

Inspectorではなぜlegacyが標準なのか

「最新仕様なのに、なぜInspectorの初期設定がmodernではないのか」と疑問に感じるかもしれません。

これはInspectorがデバッグツールだからです。

公式ドキュメントでは、autoで自動ProbeするとLegacy stdio Serverで待機が発生したり、調査したいProtocol Transcriptへ余計なProbeが混ざったりするため、意図しない通信を避ける目的でLegacyを標準にしていると説明されています。

新仕様を検証したいときは、自分でModernへ切り替えます。

UnsupportedProtocolVersionErrorが出る場合

現在のMCP Debugging Guideでは、Protocol互換性がない場合にUnsupportedProtocolVersionErrorのエラーコード-32022が返り、ServerがサポートしているVersionをError Dataから確認できます。

たとえばInspectorをModernへ固定して接続できない場合、

Inspector: 2026-07-28

MCP Server: 旧Protocolのみ

という組み合わせになっていないか確認します。

逆に最新ServerをテストしているのにInspectorをLegacy接続している場合も、期待したCapabilitiesが見えない可能性があります。

Toolsタブでtools/listを確認する

接続に成功したらToolsタブを開きます。

MCP Serverがtools Capabilityを公開していれば、Tool一覧が表示されます。

現在のWeb Inspectorでは、各ToolについてDescription、Input Schema、Annotationsなどを確認でき、Schemaから生成されたフォームへ値を入力して直接Tool Callできます。

たとえばServer側で、

search_documents
get_customer
create_report

を公開しているなら、Inspectorにも同じ名前が表示されるはずです。

表示されなければ、

Tool登録前にServerを起動していないか

registerToolが実行されているか

Capabilityが正しいか

Protocol Eraが合っているか

古いビルドファイルを起動していないか

を確認します。

CLIならtools/listだけを確認できる

Web UIを開くまでもなくTool一覧だけ確認したい場合、CLIが便利です。

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

現在のInspector CLIは1回のMCP Requestを実行して結果を出力し、そのまま終了するため、開発時のSmoke Testにも利用できます。

JSONで確認するなら、

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

です。

これを使えば、

Toolsタブに表示されない

というUI問題なのか、

Server自体がToolを公開していない

のかも切り分けられます。

ToolをInspectorから単体実行する

Toolsタブから対象Toolを選択します。

たとえば、

get_weather

が、

{
  "city": "Tokyo"
}

を受け取るなら、フォームへTokyoを入力して実行します。

このときInspectorは実際に、

tools/call

をMCP Serverへ送ります。

Tool ResultはTools画面に表示され、Structured Content、Embedded Resource、画像などにも対応しています。

ここでToolが成功すれば、

MCP Server: 正常

Tool登録: 正常

Tool内部処理: 正常

まで確認できます。

Hostアプリ側だけで発生する問題へ調査範囲を絞れます。

CLIからToolを直接実行する

Tool単体テストはCLIでもできます。

たとえば、

get_weather

へ、

city=Tokyo

を渡すなら、

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

です。

Inspector CLIでは--tool-arg key=valueを繰り返してArgumentsを渡せます。値はJSONとして可能な範囲で変換されるため、count=1ならNumberとして扱われます。

文字列の012が12になる問題に注意する

CLIの--tool-argには注意点があります。

現在のInspector CLIは値をJSON Parseして型変換します。

そのため、文字列として、

012

を渡したつもりでも、期待する型と食い違う可能性があります。

郵便番号や商品コードなど、型を厳密に維持したい場合は--tool-args-jsonを使います。

たとえば、

npx @modelcontextprotocol/inspector \
  --cli \
  node build/index.js \
  --method tools/call \
  --tool-name find_address \
  --tool-args-json "{\"zip\":\"0123456\"}"

とします。

Windows PowerShellではQuoteの扱いが異なるため、Shellに合わせて調整します。

Tool Errorと接続エラーを分けて見る

Inspector CLIは終了コードも細かく分かれています。

現在のCLIでは、成功はExit Code 0、認証が必要な場合は3、DNS・Connection Refused・TimeoutなどServerへ到達できない場合は4、tools/callがisError: trueになった場合やToolが存在しない場合は5です。

この区別は非常に便利です。

たとえば、

Exit 4

なら、

Toolのコード

を調べる前に接続を確認します。

一方、

Exit 5

ならServerとは通信できているため、

Tool名

Arguments

Tool内部処理

を確認します。

Connection refusedならサーバーが待ち受けているか確認する

Streamable HTTPで、

ECONNREFUSED
fetch failed

になる場合、最初にMCPサーバー自体が起動しているか確認します。

たとえば、

接続先の例

http://localhost:3000/mcp

localhost

へ接続するつもりなのにServerが、

localhost:3001

で起動していればInspectorは接続できません。

Inspector CLIではDNS、Connection Refused、Timeout、fetch failedなどの到達不能エラーはServer Unreachableとして分類されます。

MCP Protocolを調べる前に、

Host

Port

Path

を確認します。

404ならMCP Endpointを確認する

Streamable HTTP Serverでは、URLのPathを間違えているケースもあります。

Serverが、

正しいEndpoint

http://localhost:3000/mcp

localhost

で待ち受けているのに、

間違ったEndpoint

http://localhost:3000

localhost

へInspectorを接続すれば、通常の404になる可能性があります。

Web InspectorのNetworkタブではHTTP Status、Request Header、Response Header、Bodyを確認できます。

ProtocolタブだけでなくNetworkタブも見ることで、

MCP Protocol Error
か
HTTP 404

なのかを切り分けられます。

401・403なら認証を確認する

Remote MCP Serverが認証必須なら、Inspectorからも認証が必要です。

CLIでは401・403やOAuth要求などがAuthentication RequiredとしてExit Code 3に分類されます。

単純なBearer Tokenを使う開発サーバーなら、

npx @modelcontextprotocol/inspector \
  --server-url https://example.com/mcp \
  --transport http \
  --header "Authorization: Bearer test-token"

のように確認できます。

OAuth対応ServerについてはInspector自身にもOAuth Flowがあります。

認証なしでローカルServerへ接続できるのにRemote Serverだけ失敗するなら、MCP Toolより先に認証を確認します。

NetworkタブでHTTPを確認する

Streamable HTTP接続ではNetworkタブが特に重要です。

現在のWeb InspectorのNetworkタブでは、HTTP Status Code、Request Header、Response Header、Bodyなどを確認できます。Modern ProtocolではMCP標準Headerも分かりやすく表示されます。

たとえばTool Callで500が発生した場合、

Protocol: tools/call

Network: HTTP 500

の両方を確認できます。

Reverse Proxyや認証Middlewareで弾かれている場合は、MCP ServerのTool Handlerまで到達していない可能性もあります。

stdioではConsoleタブを見る

stdio接続ではNetworkタブの代わりにConsoleタブがあります。

Consoleには、Inspectorが起動したMCP Server Processのstderrが表示されます。

Serverで、

console.error(
  "MCP server started"
);

と出力すれば確認できます。

一方、

console.log(
  "MCP server started"
);

はstdio MCP Serverでは避けます。

stdioではstdoutがMCPのJSON-RPC通信に使われるため、通常ログをstdoutへ出すとProtocolを壊す可能性があります。

MCP公式ドキュメントでも、stdioサーバーのログはstderrへ出し、stdoutへ通常ログを書かないよう明示されています。

console.logが原因でMCPが壊れることがある

たとえばServer起動時に、

console.log(
  "Starting server..."
);

としていたとします。

stdioではInspectorがstdoutから、

Starting server...

を受け取ります。

しかしInspectorが期待しているのはMCPのJSON-RPC Messageです。

そのため、

Unexpected token
Invalid JSON
Connection closed

のような形で接続が失敗する可能性があります。

デバッグログは、

console.error(
  "Starting server..."
);

へ変更します。

InspectorのConsoleタブならstderrを見ながらToolsを操作できるため、stdioサーバーのデバッグに向いています。

Tool内部までログを入れる

Inspectorへ接続できるのにToolだけ失敗するなら、Tool Handler内部へログを入れます。

たとえば、

async function searchDocuments(
  query: string
) {
  console.error(
    "search_documents:start",
    { query }
  );

  const result =
    await database.search(
      query
    );

  console.error(
    "search_documents:complete",
    {
      count:
        result.length
    }
  );

  return result;
}

とします。

InspectorからToolを1回だけ実行すれば、

Tool CallがHandlerまで来ているか

DB検索前で止まったか

DB検索後で止まったか

を確認できます。

MCP公式のDebugging Guideでも、Server Startup、Resource Access、Tool Execution、Error、Performanceなどをログへ残すことが推奨されています。

Streamable HTTPではstderrがInspectorに出ない

stdioとStreamable HTTPではログの見え方が違います。

stdioではInspector自身がServer Processを起動するため、Consoleタブからstderrを取得できます。

Remoteまたは独立Processとして起動しているStreamable HTTP Serverでは、InspectorはそのProcessのstderrを取得できません。

公式Debugging Guideでも、Streamable HTTPではServer自身のログ基盤やOpenTelemetryなどを利用し、HTTP通信はNetwork Toolなどで確認する方法が案内されています。

したがってHTTP Serverで、

Consoleタブがない

のは異常ではありません。

Toolsが表示されないならCapabilityを確認する

InspectorのタブはServerが公開したCapabilitiesによって変わります。

ServerがTools Capabilityを公開していればToolsタブが表示されます。

PromptsならPrompts、ResourcesならResourcesです。

そのため、

接続はConnected

Toolsタブがない

場合は、Tool HandlerのエラーだけではなくServer Capabilityの登録を確認します。

Protocolタブから初期化結果を確認すると、Serverが何を公開しているか分かります。

tools/listは成功するのにtools/callだけ失敗する場合

これは接続自体はほぼ正常です。

initialize: 成功

tools/list: 成功

tools/call: 失敗

なら、重点的に確認するのはTool ArgumentsとTool内部処理です。

たとえばZod Schemaが、

z.object({
  userId:
    z.string().uuid()
})

なのに、

{
  "userId": "123"
}

を送ればInput Validationで失敗します。

InspectorのTools画面ではInput Schemaがフォームとして表示されるため、どのArgumentsが必要なのか確認しながら実行できます。

-32602 Invalid paramsを確認する

2026-07-28系では、不正なMCP Request ParameterなどでJSON-RPC-32602が返る場合があります。

公式Debugging Guideでは、Modern MCP Requestで必須となるProtocol VersionやClient Capabilitiesなどの_metaが不足している場合にも-32602 Invalid paramsが返ると説明されています。

Inspector V2ではModern Serverの-32602エラーを専用Panelで確認できるようになっています。

自作curlでMCP Requestを送って失敗する一方Inspectorでは成功するなら、InspectorのProtocolタブと自作Requestを比較すると原因を発見しやすくなります。

Claude Desktopでは失敗してInspectorでは成功する場合

このパターンは重要です。

Inspector: 成功

Claude Desktop: 失敗

なら、MCP ServerやToolそのものよりClaude DesktopからServerを起動するときの条件を調べます。

特に疑うのは、

command

args

絶対パス

Working Directory

環境変数

Protocol互換性

です。

MCP公式Debugging Guideでも、接続問題ではServer Processが起動しているか確認したうえでInspectorを使って単体テストし、Protocol互換性やClient Capabilityを確認する流れが案内されています。

Inspectorで「正常な基準」を作り、Host側設定との差を比較します。

InspectorでもClaude Desktopでも失敗する場合

両方で失敗するなら、Server側を優先して確認できます。

Inspector: 失敗

Claude Desktop: 失敗

なら、

Server起動コマンド

依存パッケージ

ビルド

Tool登録

APIキー

Serverコード

Protocol Version

の可能性が高くなります。

まずターミナルからServerの起動コマンドそのものを実行します。

node build/index.js

ただしstdio ServerはクライアントからJSON-RPC Inputを待つため、何も表示されないこと自体は異常とは限りません。

重要なのは、起動直後にExceptionで終了していないかです。MCPサーバーの起動失敗そのものを詳しく調べる方法はMCPサーバーが起動しない原因｜Windowsのパス・環境変数・stdioを確認で解説しています。

Inspectorだけ失敗する場合はInspector設定も確認する

逆に、

Claude Desktop: 成功

Inspector: 失敗

ならInspectorの起動条件を確認します。

たとえばClaude Desktop Configでは、

{
  "env": {
    "API_KEY": "..."
  }
}

を設定しているのに、InspectorではそのEnvironment Variableを渡していないケースがあります。

Claudeでは正しいWorking Directoryが設定されている一方、Inspectorでは別Directoryから起動している可能性もあります。

Inspector側でも、

--cwd

と、

-e KEY=VALUE

を使ってHostと同じ条件を再現します。

古いbuild/index.jsを起動していないか確認する

TypeScript開発では、

src/index.ts

だけ修正し、

build/index.js

を再生成していないケースがあります。

Inspectorは、

node build/index.js

を実行しているため、編集前のJavaScript Serverへ接続します。

たとえば新しいToolを追加したのにTools一覧へ表示されない場合は、

npm run build

を実行してからInspectorを再接続します。

Inspectorを再起動しても、実行ファイルそのものが古ければToolは増えません。

Server Processがすぐ終了する場合

stdioサーバーへInspectorから接続すると、

Server disconnected

になり、ConsoleにはNode.jsのExceptionが出ることがあります。

MCP公式Debugging GuideではServer Startup Errorの代表例として、実行ファイルのPathミス、必要ファイル不足、Permission、Config Error、Environment Variable不足などが挙げられています。

たとえば、

Error: API_KEY is required

ならMCP Protocolの問題ではありません。

Inspectorから、

-e API_KEY=...

を渡すかServerのEnvironment管理を修正します。

CLIのExit Codeを使うと自動テストできる

Inspector CLIは手動確認だけでなくCIにも利用できます。

たとえばビルド後に必ずsearch_documentsが公開されていることを検査できます。

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

公式CLIは機械処理用のJSON出力と安定したExit Codeを提供しており、CIからMCP Serverの到達性やTool Errorを判定できます。

これにより、

コードを変更
↓
MCPサーバーをビルド
↓
Inspector CLIでtools/list
↓
Toolを単体実行
↓
成功したらDeploy

というテストフローを作れます。

ToolのSmoke Testを作る

たとえばhealth_checkという副作用のないToolを用意しておけば、Inspector CLIで疎通確認できます。

npx @modelcontextprotocol/inspector \
  --cli \
  node build/index.js \
  --method tools/call \
  --tool-name health_check \
  --format json

正常ならExit Code 0です。

Tool自身がisError: trueを返す場合、Inspector CLIはTool ErrorとしてExit Code 5を返します。

単純にProcessが起動したかではなく、

initialize

tools/list

tools/call

まで成功することを確認できます。

副作用のあるToolを本番データでテストしない

InspectorではToolを簡単に直接実行できます。

そのため、

delete_user
send_email
create_order
publish_post

などをProduction Environmentへ接続したままテストすると、本当に処理される可能性があります。

InspectorはToolのMock Simulatorではありません。

実際のMCP ClientとしてToolを呼び出します。

AIエージェントの無限ループを防ぐ方法で解説したHuman in the Loopが通常Host側に存在していても、Inspectorから直接Toolを呼べばそのHost側確認フローを通らない構成もあり得ます。

開発用DBやSandbox APIを使用します。

接続確認専用のToolを用意すると便利

MCP Serverの開発では、副作用のない診断Toolを1つ用意しておくと便利です。

たとえば、

health_check

です。

返す内容は単純で構いません。

{
  "status": "ok",
  "database": "ok"
}

必要なら外部APIの状態も確認します。

{
  "status": "ok",
  "database": "ok",
  "externalApi": "ok"
}

InspectorからこのToolだけを実行することで、

MCP通信は正常

Tool実行も正常

DB接続も正常

というところまで一度に確認できます。

ただしAPIキーなどのSecretをResultへ含めないようにします。

ProtocolタブとConsoleを同時に見る

Web InspectorにはMonitoring Sidebarがあります。

Tasks、Logs、Protocol、Network、Consoleなどを右側へ固定し、Tools画面を操作しながら通信を見ることができます。

stdio開発なら、

左: Tools

右: Console

にすると便利です。

Toolボタンを押した瞬間、

Tool Handler開始

DB問い合わせ

Tool Handler終了

というstderrログを確認できます。

Streamable HTTPなら、

左: Tools

右: Network

にしてHTTP StatusとHeadersを見る方法があります。

ProtocolタブではJSON-RPCの流れを見る

Toolを実行したらProtocolタブを確認します。

正常なら概念的には、

tools/call request
↓
tools/call response

となります。

失敗した場合も、

Requestは送られたがResponseが返っていない
か
Error Responseが返った

のかを区別できます。

MCPツールがタイムアウトする原因｜再試行・キャンセル・冪等性の設計で解説したTool Timeoutを調べる場合にも有効です。

Requestが送信済みなのにResponseだけ戻らないなら、Tool Handler内部や依存先APIで止まっている可能性があります。

NetworkタブでTimeoutを調べる

Streamable HTTPの場合、Tool CallがTimeoutするときはNetworkタブも確認します。

POST /mcp

が送られ、

Pending

のまま長時間残るなら、Server側が最終Responseを返せていない可能性があります。

すぐ、

500

が返るならTimeoutではなくServer Errorです。

401

なら認証です。

404

ならEndpointを疑います。

MCP InspectorのNetworkビューではHTTP Status、Headers、Bodyまで確認できるため、MCP Protocolより1段下のHTTP Layerを切り分けられます。

CLIには接続Timeoutもある

現在のInspector CLIには--connect-timeoutがあります。

CIなどで到達不能なServerを長時間待ちたくない場合に利用できます。

通常のTool実行時間と、

そもそもServerへ接続できない

という状態は別です。

CIでは特にConnection Failureを早く検出することで、Build Jobが不要に長時間停止することを防げます。

Proxy環境ではHTTP_PROXYも確認する

企業ネットワークなどProxy経由でRemote MCP Serverへ接続する場合、Inspector CLIおよびWeb Backendは一般的な、

HTTPS_PROXY
HTTP_PROXY
NO_PROXY

を利用できます。

ブラウザではアクセスできるのにInspectorからRemote MCPへ接続できない場合、企業ProxyやNO_PROXYの設定が影響している可能性があります。

逆にローカルの、

localhost

までProxyへ送られているなら、NO_PROXYを確認します。

Inspector Web自体が403になる場合

MCP ServerではなくInspector自身のWeb Backendが403になるケースもあります。

現在のInspector Webは、ローカルでProcessを起動できるBackendを持つためOriginとセッショントークンによる保護があります。

そのため起動時に表示されたURLではなく別Originからアクセスしたり、DockerでPort Mappingだけ変更したりすると、Inspector BackendへのRequestが拒否される場合があります。

MCP Serverの403なのかInspector Backendの403なのかを混同しないようにします。

通常のローカル開発では、起動時に表示されたURLをそのまま開くのが最も簡単です。

InspectorをLANへ無防備に公開しない

Inspector WebのBackendはstdio MCP Server Processを起動できるため、通常の静的Webページとは性質が異なります。

現在のInspectorは標準ではLoopbackへBindし、0.0.0.0へのBindは明示的な危険設定なしでは拒否します。

単に、

社内の別PCから見たい

という理由で認証を無効化し、全Interfaceへ公開するのは避けます。

Inspectorは開発用ツールとしてローカルで使用するのが基本です。

MCP Inspectorで接続エラーを調べる順番

MCPで問題が発生したときは、最初からTool内部のコードを追うより、接続レイヤーから順番に絞ると効率的です。

最初にMCP Serverの起動Commandをターミナルで確認します。

次にInspectorから同じCommandでstdio Serverを起動するか、Streamable HTTPのEndpointへ直接接続します。

接続できたらProtocolタブで初期化を確認します。

その次にtools/listでToolが公開されていることを確認します。

最後に対象Toolだけをtools/callで実行します。

つまり、

Server Process
↓
MCP Connection
↓
Protocol
↓
tools/list
↓
tools/call
↓
Tool内部処理

の順番で確認します。

公式MCP Debugging Guideでも、接続問題ではClient Log、Server Process、InspectorによるStandalone Test、Protocol互換性の順で確認する方法が案内されています。

「接続できない」と「Toolが失敗する」を分ける

Inspectorを使う最大のメリットは、この2つを分離できることです。

たとえば、

initialize: 成功

tools/list: 成功

tools/call: 失敗

なら、Connection問題ではありません。

Tool内部を調べます。

一方、

initialize: 失敗

なら、

DB検索ロジック

まで追う必要はありません。

Server Startup、Transport、認証、Protocol Compatibilityを調べます。

原因のレイヤーを1つずつ下げていくことが重要です。

MCP Inspector CLIをCIへ組み込む

MCP Serverを継続的に開発するなら、Inspectorを手動デバッグだけで終わらせずCIにも利用できます。

公式Inspector CLIは、Serverへ接続して1つのMethodを実行し、機械処理可能なOutputとExit Codeを返すよう設計されています。公式ドキュメントでもCIからtools/listを実行して必要なToolが存在することを確認する例が掲載されています。

たとえば、

npm test
↓
npm run build
↓
Inspector tools/list
↓
Inspector health_check
↓
Deploy

という流れにできます。

これにより、

ローカルではToolが出ていたのにDeploy後に登録されていない

といった問題を早期に発見できます。

MCP Inspectorに関するよくある質問

まとめ

MCPサーバーで接続エラーが発生したときは、Claude DesktopやAIエージェントだけで原因を追い続けるより、MCP InspectorでServerを単体テストするほうが切り分けやすくなります。

現在の公式MCP InspectorはWeb、CLI、TUIの3モードを1つの@modelcontextprotocol/inspectorパッケージから利用でき、Web版なら、

npx @modelcontextprotocol/inspector

で起動できます。Node.js 22.19.0以上が必要です。

stdio MCP Serverなら、

npx @modelcontextprotocol/inspector node build/index.js

のようにServer起動Commandをそのまま渡します。

Streamable HTTPなら、

npx @modelcontextprotocol/inspector \
  --server-url http://localhost:3000/mcp \
  --transport http

のように接続できます。

接続後はいきなりTool内部を調べるのではなく、

Serverが起動する
↓
initializeが成功する
↓
tools/listが成功する
↓
対象Toolが存在する
↓
tools/callが成功する

という順番で確認します。

stdioならConsoleタブでServerのstderr、Streamable HTTPならNetworkタブでHTTP通信を確認し、ProtocolタブではJSON-RPCレベルの通信を確認できます。

Inspectorでは--cwdによるWorking Directory変更や-e KEY=VALUEによるEnvironment Variable指定もできるため、本番Hostの起動条件を再現できます。

また、2026-07-28対応ServerではInspectorのProtocol Eraにも注意します。Inspectorはデバッグ時の余計なProbeを避ける目的でLegacyが初期値となっており、新仕様を明示的に検証する場合はModernへ変更できます。

MCP Inspectorを使う目的は単に「Toolボタンを押して動くか確認する」ことではありません。

Server Process、Transport、Protocol、Tool Discovery、Tool Executionを1層ずつ分離し、「どこまでは正常なのか」を確定することが最大のメリットです。

HostアプリでMCP接続エラーが発生したら、最初にInspectorで同じMCP Serverを単体起動し、initialize → tools/list → tools/callの順で確認すると、原因へたどり着きやすくなります。