--mcp-config（エムシーピー・コンフィグ）

Claude Code を2ヶ月以上使っていて、外部ツール（DB・API・社内システム）と連携した自作 MCP サーバーをセッション単位で繋ぎたい人向け

--mcp-config は claude を起動するときに後ろにつけて、「このセッション限定で MCP サーバーを読み込ませる」ための起動指定です。MCP は Claude Code に外部ツールや社内データベースを橋渡しする仕組みで、普段は恒久設定として登録して使います。それを「今回のセッションだけ」「この JSON ファイルだけ」つなぎ込みたい場面で叩くのがこれ。

恒久登録した設定はディスクに残り続けるのに対し、--mcp-config はセッションを閉じたら綺麗に消える。お試し・スポット連携・チーム共有前の検証に向いています。

噛み砕くと

イメージとしては「会議室に持ち込み資料を一時的に持ち込む」感覚です。普段の会議室には常設の本棚＝恒久登録された MCP サーバーがあり、メンバー全員がいつでも参照できる状態になっている。--mcp-config はそこに「今日の打ち合わせのために、私の手元にあるこの分厚い資料を一時的に置きます」と差し込む動き。

会議が終われば資料は持ち帰る。常設本棚はいじっていないので、明日の会議には影響しない。

大事な前提：JSON ファイルか JSON 文字列を用意してから叩く

この起動指定を叩くだけでは何も起きません。--mcp-config の後ろには、MCP サーバー定義を書いた JSON ファイルの場所か、JSON 文字列そのものを渡す必要があります。中身の書式は「ルートに "mcpServers" キーがあり、その下にサーバー名と接続情報が並ぶ」構造で固定。

つまり叩く前にやることは2つ。「JSON を書く」「保存先を決めるか、1行 JSON 文字列をクリップボードに用意する」。これが整っていないと、起動した瞬間に JSON パースエラーで弾かれます。

「料理レシピDB MCP サーバーを1セッション限定で読ませる」を例に、実際の手順を見る

題材は「自分のパソコンにあるレシピDBファイルを、自作の MCP サーバー経由で Claude Code から検索できるようにする」。恒久登録はしたくない、今回の記事下書きを書く間だけ使いたい、というケースで進めます。

ステップ1: 自作 MCP サーバーを用意する

すでに node /Users/me/recipe-mcp/server.js という形で起動できる自作 MCP サーバーがある前提で進めます。レシピを SQLite から読み出して「鶏胸肉を使う料理を検索」みたいな道具を Claude Code に提供する作りです。

ここの作り方自体は本題ではないので省略。手元で node server.js を直接叩いて、エラーなく起動することだけ確認しておきます。

ステップ2: 接続定義の JSON を書く

プロジェクトのルートに recipe-mcp.json を作って、こう書きます。

{
  "mcpServers": {
    "recipe-db": {
      "type": "stdio",
      "command": "node",
      "args": ["/Users/me/recipe-mcp/server.js"],
      "env": {
        "RECIPE_DB_PATH": "/Users/me/recipes.sqlite"
      }
    }
  }
}

3つだけ押さえれば書けます。"type" は「どうやって繋ぐか」の指定で、自分のパソコンで動かすプログラムなら stdio。"command" と "args" は「Claude Code がこの MCP サーバーを起動するときに叩くコマンドそのもの」。"env" は MCP サーバー側のプログラムに渡したい設定値で、ここでは「DBファイルの場所」を RECIPE_DB_PATH という名前で渡しています。

ステップ3: Claude Code を --mcp-config 付きで起動する

ターミナルを開いて、JSON を置いたフォルダで次の1行を叩きます。

$ claude --mcp-config ./recipe-mcp.json

起動すると Claude Code が recipe-mcp.json を読み込み、recipe-db という名前の MCP サーバーを裏で立ち上げます。ここで JSON 書式が間違っていれば起動時に弾かれるので、すぐ気付ける構造になっています。

ステップ4: /mcp で読み込まれているか確認する

起動できたら、Claude Code の中で /mcp と叩きます。読み込み中の MCP サーバー一覧が出るので、recipe-db が「connected」状態で出ていれば成功。

「failed」表示なら node server.js 側のエラーが出ているはずなので、ターミナルのログを遡って確認。よくあるのは「DBファイルの場所が間違っている」「権限がない」あたり。

ステップ5: 実際に道具として使わせる

「鶏胸肉を使うレシピを recipe-db から3つ探して、それぞれの調理時間と材料を一覧にまとめて」と Claude に依頼します。Claude は recipe-db 経由で SQLite を検索しに行き、結果を返してくれる。そこから「ブログ記事の下書きを作って」と続ければ、DBにあるレシピを根拠に文章を組み立ててくれます。

ここで初心者がやりがちな勘違いがある。recipe-db を読み込ませた＝Claude が勝手に DB を覗き始める、ではない。Claude はあくまで「道具として使える」状態になっただけで、こちらが「DBを使って」と頼まないと触りません。

ステップ6: セッションを閉じる

Ctrl-D や /exit で Claude Code を閉じる。次に claude を後ろに何もつけずに起動すると、recipe-db はもう読み込まれません。~/.claude.json にも何も書き込まれていない。完全に「今回のセッション限定」で動いていました。

つまり --mcp-config は何をしてくれるのか

• やってくれる: 指定した JSON に書かれた MCP サーバーを、このセッションだけ Claude Code に読み込ませる。恒久設定にあるサーバーがあれば、それと並べて使える
• やってくれる: スペース区切りで複数の JSON を同時指定できる。例えば claude --mcp-config ./a.json ./b.json のように2つ並べる。同名サーバーが被ったら後勝ち
• やってくれない: 恒久保存。セッションを閉じれば設定は消える。恒久化したければ claude mcp add を別に叩く
• やってくれない: 既存の恒久設定を無視する動き。それをやりたいときは --strict-mcp-config を組み合わせて、「今回指定したものだけ使う」モードに切り替える
• 意味が薄い場面: 毎日同じ MCP サーバーを使う、チーム全員で共有したい、というケース。これは .mcp.json や settings.json 経由で恒久登録した方が運用が楽

使いどころ3シナリオ（具体題材で再現）

シナリオ1: 取材記事の執筆で「今回だけ」社内DBを参照したい

例えば社内の「過去取材ログDB」を Claude Code から検索できる MCP サーバーが社内で配られている。普段は使わないけれど、今回の特集記事を書く2日間だけ参照したい。恒久登録すると ~/.claude.json に資格情報まで書き込まれて気持ち悪い、というときに --mcp-config ./interview-db.json で2日間だけ繋いで、終わったらファイルごと削除すれば痕跡は残らない。

シナリオ2: 公開前の MCP サーバーを手元で検証する

自作 MCP サーバーを書いて、社内の Claude Code 利用者に配る前に「ちゃんと動くか」を確認したい場面。claude mcp add で恒久登録すると、検証が終わった後に claude mcp remove で消す手間が増える。--mcp-config ./draft-server.json で読ませれば、駄目だったらセッションを閉じて JSON を直して、また起動し直すだけ。1サイクル30秒で試行錯誤できます。

シナリオ3: チームへの配布前にクリーン環境で動作確認

チームに「.mcp.json を Git で共有する」運用を提案する前に、自分の手元では既存の恒久設定が邪魔して「他の人の環境でも本当に動くのか」が読みづらい。そこで --strict-mcp-config と組み合わせて claude --strict-mcp-config --mcp-config ./team-shared.json と叩くと、恒久設定を完全に切って、配布予定の JSON だけが読み込まれた状態を再現できる。チームメンバーの初日の見え方がそのまま再現される。

初心者が踏みやすい落とし穴

• JSON 文字列を直接渡すときのクォート。ファイルを介さず claude --mcp-config '{"mcpServers":...}' のように1行で渡すこともできますが、ターミナルでダブルクォートとシングルクォートが混じると壊れる。長い設定はファイルにした方が事故が少ないです
• 恒久登録と二重に読み込まれている。すでに claude mcp add で同名サーバーを登録済みのまま --mcp-config で同じ名前を指定すると、後勝ちで上書きされます。挙動が予想と違ったら /mcp でどっちが効いているか確認
• --strict-mcp-config と混同。前者は「追加読み込み」、後者は「これだけ使う」。何でもかんでも --strict-mcp-config をつけると、普段使っている他の MCP サーバーが急に消えて「動かない」と慌てることになる
• 複数 JSON 指定でマージ順を勘違い。--mcp-config ./a.json ./b.json としたとき、同名サーバーは後の b.json が勝つ。順序を入れ替えると挙動が変わるので、意識して並べる
• "type" 指定漏れ。stdio が初期値なので省略しても動くケースは多いですが、http や sse で繋ぐ場合は "type": "http" を明示しないと stdio として解釈されて即エラー。書式違いのサーバーを混ぜるときは "type" を毎回明示しておくと事故が減る
• ${VAR_NAME} 未設定で起動失敗。JSON 内で "env": { "API_KEY": "${API_KEY}" } のように書けるパソコン側の設定値の展開機能は、起動時のターミナルにその変数が無いと空文字になるのではなく Claude Code が JSON の読み込み自体に失敗して起動できなくなる。落としどころが欲しいときは "${API_KEY:-dummy}" のようにコロンハイフンの後ろにデフォルト値を書くと、変数が未設定でも dummy が入って起動は通る。起動前に echo $API_KEY で中身を確認する癖をつけると安全
• JSON のシンタックスエラーで起動失敗。末尾カンマ、ダブルクォート抜け、ブロック閉じ忘れあたりが起きやすい。書いたら一度 cat recipe-mcp.json | python -m json.tool 等で構文を通しておくと、Claude Code 側で謎エラーに悩まされない

書き方

claude --mcp-config <JSONファイルの場所 または JSON文字列> [<2つめ> <3つめ> ...]

やってみるとこうなる

入力

claude --mcp-config ./recipe-mcp.json

出力例

起動時に recipe-mcp.json が読み込まれ、Claude Code 内で /mcp を叩くと recipe-db が「connected」で出る。
セッション内で「鶏胸肉を使うレシピを recipe-db から3つ探して」のような依頼ができるようになる。
Ctrl-D で終了すると recipe-db は読み込み状態から外れ、~/.claude.json にも書き込まれない。

関連項目

• --strict-mcp-config（ストリクト・エムシーピー・コンフィグ）
• MCP（エムシーピー）
• /mcp-command（準備中）
• settings.json（セッティングス・ジェイソン）
• /claude-mcp-add（準備中）

公式ドキュメント

https://code.claude.com/docs/en/cli-reference