MCP Inspectorの設定ファイル形式と環境変数一覧

catalogとconfig、2つのファイルの役割はどう違うか

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

--catalogはInspector自身の作業用サーバー一覧です。ファイルが存在しなければ自動で作成・初期化され、Web版の画面からサーバーの追加・削除を直接書き込めます。既定のパスは~/.mcp-inspector/mcp.jsonで、MCP_CATALOG_PATH環境変数でも変更できます。一方の--configは読み取り専用のセッションで、ファイルへの書き込み・初期化・移行は一切行われません。存在しないパスを指定するとエラーで止まります。

2つは排他利用で、両方を同時に指定するとどのクライアント(Web / CLI / TUI)でも同じエラーで拒否されます。個々のサーバーを1つだけ指定したいときは、ファイルを介さず--server-urlやstdioのコマンドを直接渡す「アドホックターゲット」という第三の経路もあります。

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

Web版の初回起動で自動生成されるcatalogだけ、サンプルサーバーが2つ(filesystem-server-defaultとeverything-server-default)入った状態で作られます。CLIとTUIは非対話的・一覧駆動のクライアントで、サンプルが並んでいてもノイズになるだけなので{ "mcpServers": {} }という空の状態で生成されます。この初期化はファイルが存在しないときにだけ動き、読み取り専用の--configでは絶対に発生しません。

mcpServersスキーマとprotocolEraフィールドの中身

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のいずれかを取るフィールドで、既定値はlegacyです。2026-07-28のMCP仕様改訂より前の挙動として扱うか、改訂後の挙動として扱うかをトランスポート(stdioかHTTPか)とは独立に決めます。なぜ既定がautoではなくlegacyなのかは公式ドキュメントが明言していて、デバッグツールが勝手にプロトコルを確率で決めるのは不適切という判断です。server/discoverによる自動判定は、無応答なlegacyのstdioサーバー相手だと単に固まって見えるため、autoやmodernへの切り替えは利用者の明示的な操作に限定されています。フィールドの詳細な挙動差(ログ・タスク・サブスクリプションの表示違い)はMCP Inspectorの新旧バージョン互換性の仕組みで扱っています。

もう1つのmodernLogLevelは、modernプロトコルでのログレベルを制御するサーバー単位のフィールドです。既定値はdebug。Inspectorはデバッグツールなので最も詳細なレベルにあえて振ってあり、うるさいと感じたらmodernLogLevel: "off"のようにサーバーごとに下げます。

設定を保存するとき、既定値と同じフィールドはファイルから省かれます。これはInspectorが差分を最小限に保つための挙動で、手で編集したcatalogファイルをコミットして共有する運用と相性がよく、無関係な差分がPRに混ざりません。

サーバー選択に関わるフラグは3クライアント共通

--catalog / --config / --server / --transport / --server-url / --cwd / -e / --headerは、Web・CLI・TUIそれぞれが個別に定義していますが、挙動はほぼ揃っています。差が出るのは--serverだけで、Web版とCLIは1つの名前付きサーバーを選びますが、TUIはファイル内の全サーバーを読み込んで対話的に選ばせます。--headerはアドホックなHTTP/SSEサーバーに対してのみ有効です。

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

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

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

環境変数はどの層が読むかで4グループに分かれる

環境変数はフラグと同じ分担で、ランチャー本体・CLI/TUI・Webバックエンドの3層プラスOAuth関連フォールバックに分かれます。同じ名前の変数が層をまたいで意味を変えることはありません。

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

CLIとTUIが読む変数

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

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

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

MCP_INSPECTOR_API_TOKENは、起動URLに埋め込まれるトークンをスクリプトから固定したいときに使います。CI上で毎回同じトークンを使い回して自動テストを回す用途に向いています。トークンの照合順序自体はindex.htmlに注入される値・クエリ文字列・sessionStorageの3段構えで、通常のブラウザ操作では意識する必要がありません。

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

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

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

このイメージは既定で--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で動かすときは--no-healthcheckを付けます(どちらもWebサーバーを持たないため)。

ネットワーク越しに公開するときに組み合わせる環境変数

Inspectorは既定でlocalhostにしかバインドしません。バックエンドがローカルマシン上でプロセスを起動する権限を持つ以上、ネットワークへの公開は意図して選ぶ操作だという前提です。ワイルドカードアドレス(0.0.0.0・::等)へのバインドはDANGEROUSLY_BIND_ALL_INTERFACES=trueを明示しない限り拒否されますが、特定の1つのアドレスへのバインドはオプトイン不要で許可されます。全インターフェースを一度に晒すDNSリバインディング攻撃の標的になる構成と、意図した1箇所だけを晒す構成とを区別しているためです。

ALLOWED_ORIGINSはスキーム(http://やhttps://)を含めないと警告付きで無視され、空文字を指定してもチェックが無効になるわけではなく既定値へフォールバックします。オリジン検証そのものをオフにするスイッチは存在しません。

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

設定を書かずに済ませる方法もある

catalogやconfigを手書きする以外に、Web版の画面からClaude Desktop・Cursor・Cline・VS Codeの既存設定ファイル、あるいはレジストリのserver.jsonをインポートする経路も用意されています。ゼロからmcpServersのJSONを書き起こす前に、すでに動いている設定を流用できないか確認する価値があります。自作サーバーの実装そのものはMCPサーバー自作ガイド、MCPプロトコル全体の位置づけはMCPとはで扱っています。

catalogとconfigの使い分けが実務で意味すること

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

ALLOWED_ORIGINSが既定リストを置き換える(マージしない)という仕様も同じ方向を向いています。リバースプロキシの背後でInspectorを動かすときに、意図せず既定のオリジンが残ってアクセス制御の抜け穴になる事態を避けています。ただし置き換え方式である以上、localhost向けの既定を維持したいなら自分で明示的に含める必要があり、指定を最小限にしたつもりが逆に穴を広げるケースには注意が要ります。

まとめ

MCP Inspectorの設定は「書き込み可能なcatalog」と「読み取り専用のconfig」という2ファイル制と、ランチャー・CLI/TUI・Webバックエンドの3層に分かれた環境変数群で構成されています。自作サーバーのチーム共有には読み取り専用の--config、個人の作業環境には--catalogを使い分けるのが基本方針です。Webバックエンドを外部に公開する構成にするときは、DANGEROUSLY_OMIT_AUTHとDANGEROUSLY_BIND_ALL_INTERFACESの同時指定だけは避けてください。基本操作フローそのものはMCP Inspectorの使い方にまとめてあります。