MCPサーバーを自作インストールさせる：3つのホスト、3つのメカニズム、落とし穴

MCPサーバーのセットアップは、いまだにJSONファイルを手動で編集することが多く、ホストごとにファイルや形式が異なります。その煩わしさから、開発者は本来使いたいサーバーを実行できずにいます。この記事では、3つのホストとそのインストールメカニズム、そしてつまずきやすい落とし穴を解説します。

3つのホスト、3つの仕組み

• VS Code: 実際のAPIがあります——registerMcpServerDefinitionProvider。package.jsonでプロバイダーを宣言し、実行時にサーバー定義を返します。VS Codeは同意プロンプトを表示。設定ファイルの編集は不要。最もクリーンですが、VS Code拡張機能の出荷が必要です。
• Cursor: ネイティブAPIはありません。.cursor/mcp.jsonにルートキーmcpServersで直接書き込みます。
• Claude Code: CLIを使用します。ファイルを手書きしてはいけません。例：
  claude mcp add --transport stdio --scope <user|local> --env … <name> -- node <path>

注意すべき6つの落とし穴

1. そのJSONファイルはあなた専用ではない。 Cursorのmcp.jsonにはユーザーの他のサーバーも入っています。読み込み、エントリを結合、無関係なキーは保持——上書きしないでください。
2. 不正なファイルに耐える。 ファイルが存在するが不正なJSONの場合、空とみなして上書きしてはいけません。読み取り/パーミッションエラーも同様に再スローします。「読めなかった」を「何もない」と扱うと設定が破損します。
3. バックアップ＋アトミック書き込み。 既存ファイルを触る前にコピー、一時ファイルに書き込み、ターゲットにリネーム。書きかけのmcp.jsonはエディタを壊します。
4. 2回目のインストールはエラーではなく何もしない。 Claude CLIはエントリが既にあるとエラーにするので、removeしてadd。ファイルホストではサーバー名でキー付けしてその場で置き換え。再実行は重複ではなく収束するように。
5. スコープで全てが変わる。 ユーザーレベルかプロジェクトレベルかで設定場所やサーバー要件（例：明示的なデータディレクトリ vs 上方発見）が変わる。意図的に選ぶこと。
6. 最新維持は自身の責任。 登録されたバージョンは出荷したものから乖離する。「インストールされているものは同梱バージョンか？」を確認し、クリーン再インストールパスを用意。ワンボタンでインストール、更新、最新の状態を表示。

教訓：手動セットアップは、人間がスニペットを貼り付けるだけでは絶対パス、適切なスコープ、環境変数、安全なマージ方法を知らないために失敗する。インストールコードはそれを知っている。