MCP Inspectorの環境変数・ポート・設定ファイル形式の一覧

MCP Inspectorのポートや設定の疑問は、先に次の表で引けます。詳しい理由は各節にあります。

編集した設定が反映されない:catalogとconfigの違い

MCP Inspectorがサーバー一覧を読み込む方法は--catalogと--configの2つのフラグに分かれています。どちらも中身は同じmcpServersスキーマですが、Inspector自身がファイルを書き換えるかどうかが根本的に違います。この違いを取り違えると「編集したはずの設定が反映されない」「ファイルが勝手に書き換わった」というつまずきに直結します。

2つは排他利用で、両方を指定するとWeb・CLI・TUIのどのクライアントでも同じように拒否されます。アドホックターゲット(ファイルを介さず--server-urlやstdioのコマンドを直接渡す方法)とも組み合わせられません。

# 自作サーバーを書き込み可能なcatalogとして開く
mcp-inspector --catalog ./mcp.json
 
# 他人のClaude Desktop設定を読み取り専用で開く
mcp-inspector --config ~/Library/Application\ Support/Claude/claude_desktop_config.json

Web画面に出るサーバー一覧が編集できるかどうかは、起動方法で決まります。

自動生成の中身はクライアントによって違います。Web版の初回起動だけは、サンプルサーバーが2つ(filesystem-server-defaultとeverything-server-default)入った状態で作られます。前者は/tmpを対象にした@modelcontextprotocol/server-filesystem、後者は@modelcontextprotocol/server-everythingをnpxで起動する定義です。

CLIとTUIは非対話的・一覧駆動のクライアントで、サンプルが並んでいてもノイズになるだけなので{ "mcpServers": {} }の空の状態で生成されます。この初期化はファイルが存在しないときにだけ動きます。

なお、Webページ冒頭のコード例では、npx @modelcontextprotocol/inspectorの行に「空の状態で起動し、画面からサーバーを追加する」という趣旨のコメントが付いています。同じページの起動方法の表は、初回起動でサンプル2台を入れるとしています。実際の初回起動は、後者のサンプル入りです。

mcpServersスキーマの書き方と既定値

catalogとconfigの両方が読み書きするファイルは、一般的なMCPクライアントの設定ファイルと同じmcpServersオブジェクトの形をしています。サーバーごとにInspector固有のフィールドを重ねて持てます。

{
  "mcpServers": {
    "my-stdio-server": {
      "command": "node",
      "args": ["build/index.js"],
      "env": { "API_KEY": "..." }
    },
    "my-modern-server": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "protocolEra": "modern",
      "modernLogLevel": "info",
      "headers": { "X-Tenant": "acme" },
      "roots": [{ "uri": "file:///Users/me/project", "name": "project" }]
    }
  }
}

protocolEraはサーバーごとにlegacy / auto / modernのいずれかを取るフィールドです。2026-07-28のMCP仕様改訂より前の挙動として扱うか、改訂後の挙動として扱うかを、トランスポート(stdioかHTTPか)とは独立に決めます。同じHTTPのURLを、legacyのサーバーとしてもmodernのサーバーとしても調べられます。

既定がautoでなくlegacyなのは、デバッグツールが接続時に勝手に探りを入れるべきでないからです。server/discoverは応答しないlegacyのstdioサーバー相手だと固まって見え、読みたい通信記録も汚れます。そのためautoやmodernに切り替えるのは、利用者が明示した場合に限られます。ログ・タスク・サブスクリプションの表示違いはMCP Inspectorの新旧バージョン互換性の仕組みで扱っています。

modernLogLevelはmodernプロトコルでのログレベルを決めるサーバー単位のフィールドです。デバッグツールなので最も詳細なdebugが既定で、うるさいときは"off"のようにサーバーごとに下げます。

保存時には、既定値と同じフィールドはファイルから省かれます。手で編集したcatalogをコミットして共有する運用では、無関係な差分がPRに混ざりません。

起動フラグの読まれ方:ランチャーが取るのは2つだけ

mcp-inspectorはランチャーで、自分では2種類のフラグしか読みません。--web / --cli / --tui(クライアントの選択。省略すると--web)と、-h / --helpです。残りの引数はすべて選ばれたクライアントに渡されます。

注意点は2つあります。クライアントを複数指定するとSpecify at most one of --web, --cli, or --tui.で失敗します。また、ランチャーのフラグは先頭に置く必要があり、ランチャーが知らない引数に当たった時点で解析が止まり、以降はそのままクライアントへ転送されます。mcp-inspector --cli --helpのようにモードと一緒に渡した--helpは、CLI側のヘルプとして表示されます。

クライアントごとに差が出るのは、--server(TUIだけ対話で選ぶ)と--header(Webはアドホック指定のHTTP/SSEのみ)です。--catalog / --config / --transport / --server-url / --cwd / -eはWeb・CLI・TUIで挙動が揃っています。--methodのようにCLIだけが持つフラグもあります。

• --server <name>:Web版とCLIは名前付きの1台を選ぶ。TUIはファイル内の全サーバーを読み込み、対話で選ばせる
• --header "Name: Value":HTTP/SSEサーバー用で繰り返し指定できる。Web版ではアドホックなHTTP/SSEサーバーのときだけ有効
• --transport / --server-url:アドホックターゲット専用
• --dev:Web版だけのフラグ。ビルド済みバンドルの代わりにViteの開発サーバーを動かす。Inspector自体を触るとき用

CLIの--headerは、Web版と違ってファイル由来のサーバーにも効きます。ファイル内のheadersをその実行だけ上書きし、タイムアウトとOAuthの設定はそのまま残ります。

自分のサーバーに引数を渡す--

ファイル内ではなく、位置引数で指定したstdioサーバーに追加の引数を渡したいときは--セパレータを使います。Web版とCLIだけがこの区切りに対応し、以降の文字列をすべてターゲットのコマンド自身への引数として転送します。

mcp-inspector node build/index.js -- --config /etc/myserver.conf --verbose

セパレータが無いと、--configはInspector自身の読み取り専用フラグとして先に消費されてしまい、ターゲットのサーバーには届きません。

環境変数はどの層が読むかで3つに分かれる

環境変数はフラグと同じ分担で、ランチャー本体・CLIとTUI・Webバックエンドの3層に分かれます。

ランチャー本体が読む変数

DEBUG=0のような変数がシェルに残っていても、スタックトレースが意図せずオンにはなりません。

CLIとTUIが読む変数

MCP_CATALOG_PATHがアドホック指定時に無視されるので、シェルの設定ファイルでexportしておいても、mcp-inspector node build/index.jsのような一回きりの起動が邪魔されません。

CLIとTUIにはOAuthクライアント設定用のフラグも5つあり、Web版が画面のClient Settingsダイアログで扱う内容と同じです。

OAuthのコールバックはクライアントごとに違います。Webは開いたオリジンに追随し、既定はhttp://127.0.0.1:6274/oauth/callback、CLIとTUIはhttp://127.0.0.1:6276/oauth/callbackです。認可サーバーはリダイレクトURIを完全一致で照合し、localhostと127.0.0.1を別のURIとして扱います。事前登録が要るIdPでWebとCLIを併用するなら、2つとも登録します。

--callback-urlにはループバックホスト(127.0.0.1かlocalhost)しか指定できません。ローカルのコールバックリスナーが認可コードを平文のhttpで受け取る仕組みのため、それ以外のホストは常に拒否され、上書きするフラグも存在しません。

Webバックエンドが読む変数

セッショントークンを固定する

Webバックエンドは/api/*のすべてを起動ごとのトークンで守っています。起動時に表示されるURLにトークンが入っているので、localhost:6274を手で打たずにそのURLを開きます。

ブラウザ側は、index.htmlに注入されるwindow.__INSPECTOR_API_TOKEN__、クエリ文字列の?MCP_INSPECTOR_API_TOKEN=...、sessionStorageの順でトークンを探します。ページを再読み込みしたりブックマークから開いたりしても動くのは、先頭の注入値があるためです。

MCP_INSPECTOR_API_TOKENで固定すると、スクリプトから起動URLを組み立てられます。ディープリンクのhttp://127.0.0.1:6274/?serverUrl=<url>&transport=http&autoConnect=<token>では、autoConnectがCSRF対策の必須パラメーターで、起動したプロセスだけが知るトークンと一致しなければなりません。CIで自動テストを回すときに、同じ値を毎回使い回せます。

Dockerで動かすときは既定値がローカル運用と違う

イメージはghcr.io/modelcontextprotocol/inspectorとしてGitHub Container Registryに公開されており、linux/amd64とlinux/arm64に対応します。

docker run --rm -p 127.0.0.1:6274:6274 ghcr.io/modelcontextprotocol/inspector

公開ポートには必ず127.0.0.1:を付けます。省くとホストの全インターフェースに公開され、プロセスを起動できるバックエンドがLANに出ます。

このイメージは既定で--web起動・0.0.0.0:6274へのバインド・ブラウザ自動起動オフ・非rootユーザーで動きます。ローカル実行との最大の違いはDANGEROUSLY_BIND_ALL_INTERFACES=trueがあらかじめ設定されている点です。docker run -pでホストのポートへ転送する以上、コンテナ内ではワイルドカードアドレスへのバインドが必須になるためです。セッショントークンはコンテナのログから読むか、-e MCP_INSPECTOR_API_TOKEN=<値>で固定できます。

HEALTHCHECKはWeb UIを叩く設定です。--cliや--tuiにはWebサーバーが無いので、--no-healthcheckを付けます。ワンショットでツール一覧を取る例です。

docker run --rm --no-healthcheck ghcr.io/modelcontextprotocol/inspector \
  --cli --server-url https://api.example.com/mcp --transport http \
  --method tools/list

接続が403で拒否されるときの切り分け

Inspectorは既定で127.0.0.1(ループバック)にしかバインドせず、受け付けるオリジンもそのポートのループバックだけです。どちらも、バックエンドがプロセスを起動できる以上、安全側に固定された境界です。ワイルドカードアドレス(0.0.0.0・::等)へのバインドはDANGEROUSLY_BIND_ALL_INTERFACES=trueを明示しない限り拒否されますが、特定の1つのアドレスへのバインドはオプトイン不要で許可されます。全インターフェースを一度に晒す構成と、意図した1箇所だけを晒す構成を区別しているためです。

オリジンの不一致は、状況によって対処が分かれます。

ALLOWED_ORIGINSは既定リストを置き換えるので、残したいループバックの形も自分で並べます。公開用オリジンだけを指定すると、手元のlocalhostから開けなくなります。

ALLOWED_ORIGINS=http://localhost:6274,http://127.0.0.1:6274,http://192.168.1.50:6274

各要素にはスキーム(http://やhttps://)が必要で、無い値は警告付きで無視されます。空文字を指定してもチェックが無効になるわけではなく、既定値へ戻ります。オリジン検証そのものをオフにするスイッチはありません。

ループバック以外に公開するときは、MCP Appsにも注意が要ります。サンドボックスは別ポートを動的に使うため、MCP_SANDBOX_PORTで固定して転送しないと届きません。Dockerイメージが公開するのは6274だけです。サンドボックスのURLは常に平文のhttpなので、https://のページから開くとmixed contentとしてブロックされます。角括弧付きのIPv6リテラルもCSPのhost-sourceとして無効なため、ホスト名かIPv4アドレスで開きます。

設定を書かずに済ませる:既存設定のインポート

手書き以外の方法もあります。Web版のServers画面のAdd Serversから、Claude Desktop・Cursor・Cline・VS Codeの既存設定ファイルや、レジストリのserver.jsonを取り込めます。取り込みはアクティブなcatalogにマージされ、既存の項目は上書きされません。catalogに一切触れたくないときは、前掲のように--configで相手のファイルを読み取り専用で開く経路が使えます。サーバーに接続せず一覧だけ読みたいなら、CLIのservers/listです。

mcp-inspector --cli --catalog ~/.mcp-inspector/mcp.json --method servers/list

自作サーバーの実装そのものはMCPサーバー自作ガイド、MCPプロトコル全体の位置づけはMCPとはで扱っています。

共有設定と作業用一覧:2ファイル制の使いどころ

--configが読み取り専用に固定されているのは、制限というより設計判断と読めます。チームで1つのMCPサーバー設定をリポジトリで共有しているとき、各メンバーが--catalogで自分の作業用一覧にサーバーを足し引きしても、コミット済みの共有設定は影響を受けません。CIやオンボーディングで「リポジトリの設定をそのまま検証する」場面でも、--configならInspectorがファイルを書き換える事故が起きません。

まとめ

外部に公開するときに最初に触るのはALLOWED_ORIGINSで、MCP Appsを使うならMCP_SANDBOX_PORTの固定も要ります。DANGEROUSLY_で始まる変数は認証とバインド範囲の制限を外すもので、オリジンの不一致では使いません。基本操作はMCP Inspectorの使い方にあります。