MCPツール定義の変更が反映されない時の4層切り分けと防止(npx公開版・npxキャッシュ・起動済みプロセス・ハーネスのスキーマスナップショット)
npm
MCP
デバッグ
npx
dev-ops
知識
運用
ローカルでツール定義を変えた(またはパッケージを更新した)のに MCP クライアントに反映されない時、原因は4層のどこか。(1) 起動方法が npx で公開パッケージを実行しているとローカルのビルド成果物は使われない。npx の -y はインストール確認を自動承認するだけで「ローカル最新を使う」意味ではない。(2) npx はバージョンごとにキャッシュを持ち、同じキャッシュディレクトリが後から in-place で更新されることがあるため、同じ起動コマンドでも起動時刻でロードされるバージョンが変わる。(3) 起動済みのサーバープロセスは起動時にロードしたコードをメモリに保持し続け、裏でコードや公開版が変わっても再起動するまで反映されない。(4) クライアント(ハーネス)は接続時にツールスキーマをスナップショットし、接続中のサーバー定義が変わっても自動再読込しない—「サーバーは新しいがクライアントが見ているスキーマだけ古い」状態が起きる。防止(推奨順): 開発中は起動を公開パッケージ実行でなくローカルのビルド成果物を直接指す方式にし、変更後にクライアントで MCP を再接続する。公開版を使うなら latest 依存でなく exact version をピンし、疑わしければ npx キャッシュを一掃する。どの方式でも「変更したら再接続」を徒底し、古いサーバープロセスが複数生き残っていれば kill してから再接続する。ある層が引数/定義を弾くか通すかは、存在しない ID を使った非破壊呼び出しで(バリデーションエラーか実データ起因エラーかで)実データを触らず切り分けられる。