Claude CodeにMCPサーバーを追加する作業自体は、claude mcp add を1回叩けば終わります。設定の本体はコマンドではなく、その後ろにある2つの判断です。どのスコープ（local / project / user）に置くか、そして何台まで足すか。この記事では追加の手順を一通り押さえたうえで、この2つの判断軸まで含めて整理します。
想定読者は、Claude Codeを使い始めて「MCPサーバーを繋ぐと何ができるのか」「設定ファイルはどこに書くのか」を知りたい人。コマンドはコピーして使える形で書きますが、手順の丸暗記より「どこに設定が保存され、誰に共有されるか」の構造を持ち帰ってもらうのが狙いです。
MCPとは何を繋ぐ仕組みか
MCP（Model Context Protocol）は、AIアプリケーションに外部のツールやデータソースを差し込むためのオープンな共通規格です。仕様はmodelcontextprotocol.ioで公開されています。Claude Codeから見ると、MCPサーバーを1台繋ぐたびに、そのサーバーが提供するツール群（データベースを読む、課題管理サービスを操作する、など）がエージェントの道具箱に追加される、と捉えれば十分です。
設定方法の一次情報はClaude Code公式ドキュメントのMCPページです。この記事のコマンドと仕様の記述もここを正としています。
Claude Code公式: Connect Claude Code to tools via MCPLearn how to connect Claude Code to your tools with the Model Context Protocol.code.claude.com
追加の基本: claude mcp add
ローカルでプロセスとして起動するタイプ（stdio型）のサーバーは、起動コマンドをそのまま渡します。-- より後ろがサーバーの起動コマンドです。
# 例: ローカルのstdio型サーバーを追加
claude mcp add my-server -- npx -y some-mcp-server
# 環境変数が必要な場合は -e で渡す
claude mcp add my-server -e API_KEY=xxx -- npx -y some-mcp-server
リモートで動いているサーバー（SSE型・HTTP型）は、--transport とURLで指定します。認証ヘッダーが必要ならオプションで渡せます。
# HTTP型のリモートサーバー
claude mcp add --transport http my-remote https://example.com/mcp
# SSE型・ヘッダー付き
claude mcp add --transport sse my-sse https://example.com/sse --header "Authorization: Bearer TOKEN"
登録済みサーバーの一覧・詳細・削除はそれぞれ claude mcp list、claude mcp get <name>、claude mcp remove <name> です。追加そのものは、本当にこれだけで終わります。
コマンドを組み立てるのが面倒なときのための入口も2つ用意されています。設定をJSONのまま渡す claude mcp add-json <name> '<json>' と、Claude Desktopで設定済みのサーバーを取り込む claude mcp add-from-claude-desktop です。すでにどこかにMCPの設定資産がある人は、書き直すより持ち込む方が早い。詳細は前掲の公式ドキュメントにあります。
設定の本体①: 3つのスコープの使い分け
ここからが判断の話です。claude mcp add は --scope オプションで設定の保存先を3種類から選べます。省略時はlocalです。
- local: 自分だけ・このプロジェクトだけ。設定はユーザー側に保存され、リポジトリには入りません
- project: プロジェクトのルートに
.mcp.jsonとして保存され、リポジトリにコミットしてチームで共有できます - user: 自分の全プロジェクト共通。どのディレクトリでClaude Codeを起動しても使えます
# チームで共有したいサーバーはprojectスコープへ
claude mcp add --scope project team-server -- npx -y some-mcp-server
# どの作業でも使う汎用サーバーはuserスコープへ
claude mcp add --scope user my-tools -- npx -y some-mcp-server
使い分けの判断軸は「その接続は誰のものか」です。
- リポジトリの作業に必須の接続はproject。そのプロジェクトのDBスキーマを読むサーバー、プロジェクト専用の社内APIなど。設定がコードと一緒にバージョン管理され、新しいメンバーはcloneするだけで同じ道具箱になります
- 個人の好みの道具はuser。自分のメモツールや汎用ユーティリティをプロジェクトごとに入れ直すのは無駄なので、1回で全プロジェクトに効かせます
- 試している段階のものはlocal。チームに配る前の検証や、秘密情報を含む接続はまずlocalに置き、共有する価値が確定してからprojectへ昇格させる、という順番が安全です
もうひとつ知っておきたいのが、同じ名前のサーバーが複数のスコープに存在した場合の優先順位です。localがprojectより優先され、projectがuserより優先されます。つまり「チームの共有設定を、自分の手元だけ一時的に別の起動方法へ差し替える」ことがlocalスコープでできる。デバッグ用にログを増やしたサーバーを自分だけ使う、といった場面で覚えておくと便利です。
逆に言うと、秘密のAPIキーを直書きした設定をprojectスコープに置くのは事故です。.mcp.json はコミット対象なので、キーがリポジトリに入ります。これを避ける仕組みが次の環境変数展開です。
設定の本体②: .mcp.jsonのチーム共有と環境変数
projectスコープの実体は、プロジェクトルートの .mcp.json です。手で書いても構いません。
{
"mcpServers": {
"team-server": {
"command": "npx",
"args": ["-y", "some-mcp-server"],
"env": {
"API_KEY": "${TEAM_API_KEY}"
}
}
}
}
ポイントは ${TEAM_API_KEY} の部分で、.mcp.json は環境変数の展開に対応しています。ファイルに書くのは変数名だけにして、実際の値は各メンバーが自分の環境変数として持つ。これで「接続設定は共有するが、認証情報は共有しない」が成立します。設定はコードとして共有し、秘密は環境に逃がす。MCPに限らず使える型ですが、.mcp.json がコミット対象である以上、ここでは必須の型です。
なおprojectスコープのサーバーは、リポジトリを開いた人がそのまま無条件に実行するわけではなく、Claude Code側が使用前に承認を求めます。リポジトリ由来の設定が勝手にプロセスを起動しない、という向きのガードです。一度「使わない」と答えた選択をやり直したいときは、claude mcp reset-project-choices でプロジェクトの承認選択をリセットできます。
接続を確認する: claude mcp listと/mcp
繋いだら、動いているかを確認します。ターミナルからは claude mcp list で登録と接続状態を一覧できます。セッションの中からは /mcp コマンドで、各サーバーの状態やツール一覧を確認できます。
リモートサーバーがOAuth認証を要求するタイプの場合も、この /mcp から認証フローに入れます。ブラウザが開いてログインすると、以後はClaude Codeがトークンを管理します。「追加したのにツールが出てこない」ときは、まず /mcp で状態を見る。起動コマンドの誤り、環境変数の未設定、認証待ちのどれかであることがほとんどです。
サーバーは足すほど強くなるわけではない
ここが今回いちばん伝えたい判断です。MCPサーバーを繋ぐほどエージェントは強くなる、と考えたくなりますが、コストの構造は逆向きに効きます。
接続中のMCPサーバーのツール定義は、毎回のリクエストでモデルへ渡されるコンテキストに乗ります。ツールが多いほど、1ターンごとに消費されるトークンが常時増える構造です。しかも道具が増えるほど、モデルがどのツールを選ぶべきか迷う余地も増える。つまり「念のため繋いでおく」は、性能ではなくコストと迷いを足しています。
このツール定義の常時コストの相場観には、AIチャットのコスト設計を扱った別記事の「スキルのトークン消費は『仕組み』ではなく『本文の量』」の節でも触れています。MCPのツール定義が毎回のリクエストに乗る構造と、その目安の規模感はこちらでどうぞ。
Durable Objectsの高額請求は怖くない｜AIチャットのコストの本体はトークン代Cloudflare WorkersでSaaSにAIチャットを組み込むときの費用の見方を整理します。Durable Objectsの課金を実際に計算すると月16万チャットまで無料枠に収まり、請求の本体はモデルのトークン代でした。家計簿サービスの設計検討で出た試算とプラン逆算をまとめます。www.tentspace.net
運用の指針はシンプルで、いま進行中の作業で実際に呼ぶサーバーだけ繋ぐ。使っていないサーバーは claude mcp remove で外すか、localスコープに退避します。「入れたものは全部有効」ではなく、道具箱を作業ごとに編成し直す感覚です。
足すかどうかを迷ったときの質問は3つで足ります。
- いまの作業で実際に呼ぶ場面が言えるか。「いつか使うかも」しか出てこないなら、そのいつかが来てから追加すれば間に合います
- ビルトインの道具で代わりが利かないか。ファイル操作やシェル実行はClaude Codeが元から持っています。同じことしかしないサーバーは、定義の分だけ損です
- 出所を信頼できるか。これは次の節の話につながります
この3つを通ったサーバーだけ残すと、道具箱は自然と小さくなります。小さい道具箱は、コストが軽いだけでなく、モデルのツール選択も安定します。
権限と安全: 繋ぐ相手は選ぶ
最後に安全の話を2つ。
1つ目はツール単位の権限です。MCPサーバーのツールは、Claude Codeの権限設定で mcp__サーバー名__ツール名 の形式で個別に許可・拒否を制御できます。読み取り系ツールだけ自動許可し、書き込み系は都度確認にする、といった粒度の設計が可能です。権限設計の全体像は別記事にまとめています。
2つ目は、そもそも繋ぐ相手の選定です。公式ドキュメントにも、サードパーティのMCPサーバーは自己責任で利用するよう明記されています。MCPサーバーはエージェントの道具箱に直接ツールを差し込む存在なので、出所の分からないサーバーを繋ぐことは、出所の分からないコードを実行することと同じ重さがあります。特にWebから取得したコンテンツを扱うサーバーは、コンテンツ内に仕込まれた指示をエージェントが実行してしまうプロンプトインジェクションの入口になりえます。信頼できる提供元か、コードを読めるオープンソースか。繋ぐ前にここだけは確認してください。
コマンドは1行、設計は2つ
Claude CodeのMCP設定を整理すると、こうなります。
- 追加は
claude mcp add、確認はclaude mcp listと/mcp。手順はこれだけ - 判断①はスコープ。プロジェクト必須はproject（
.mcp.json＋環境変数展開）、個人の道具はuser、検証中はlocal - 判断②は台数。ツール定義は常時トークンを消費するので、いま使うサーバーだけ繋ぐ
- 権限は
mcp__サーバー名__ツール名単位で絞り、繋ぐ相手は出所を確認する
接続の先、つまりMCPサーバーを自分で作る側に回るときの設計は、公開制御を実装した記録があります。次の一歩はこちらへ。
自作MCPサーバーに「投稿し過ぎない」制限を実装した記録｜制限はプロンプトではなくサーバーに置くAIエージェントに投稿ツールを渡すと放っておくと公開し過ぎます。その制限をプロンプトではなく自作MCPサーバー側（Cloudflare WorkersのKV）に置いた実装記録。単純なカウントではなくreserve→commit/releaseの二段階にした理由と、失敗時に枠を戻す設計まで解説します。www.tentspace.net