Claude Code MCP実践2026:.mcp.jsonと40ツール上限を回避する設計

Claude Code に MCP サーバーを片っ端から繋いだら、エージェントが急に間違ったツールを選ぶようになった。先週、自分の開発環境でまさにこれをやらかしました。GitHub、Postgres、Playwright、Sentry、Linear、Notion…合計で 80 個近いツールが Claude の視界に入っていたんです。

結論から言うと、MCP は数ではなく構成で効かせるものでした。この記事では、.mcp.json のスコープ設計、Streamable HTTP への移行、そして 2026 年現在の Tool Search を踏まえた「実用ラインの 4〜6 サーバー構成」を、実際に動くコマンド付きで整理します。

結論:MCP は「足し算」ではなく「常時オンの 4〜6 個」で組む

最初に答えを出します。Claude Code の MCP サーバーは、常時オンで 4〜6 個、プロジェクトごとに必要なものだけ追加で有効化、というのが 2026 年 6 月時点で私が落ち着いた構成です。

理由は単純で、Anthropic 自身が Tool Search で改善したものの、可視ツールが増えすぎるとモデルのツール選択精度が落ちるからです。codersera の 2026 年 5 月時点の解説によると、Claude Code は早期 2026 年に上限を引き上げたものの、可視ツールが 50 を超えたあたりからモデルが間違ったツールを選び始める傾向が残っていると指摘されています。GitHub サーバー単体で約 20 ツール、Playwright で約 25 ツールあるので、雑に 4 個入れた時点でリーチします。

つまり「全部入り」をやめて、常駐 5 個+プロジェクトスコープで切り替えという設計に切り替えるのが、2026 年版の MCP 運用の現実解です。

なぜ Claude Code MCP は今、設計が問われるのか

MCP は Anthropic が 2024 年 11 月にリリースした後、2025 年 12 月に Linux Foundation に寄贈され、2026 年 5 月時点で公開 MCP サーバーは 2,300 を超えました。エコシステムは爆発的に拡大しています。

ただ、大半は実質メンテされていないデモ実装です。Build Fast with AI の調査では、2,300 のうち本番運用に耐えるサーバーはごく一部で、開発者向けの実用スタックは GitHub + Filesystem + Context7 の 3 つで日常ワークフローの 80% をカバーできる、という現実的なラインが示されていました。

ここで効いてくるのが Tool Search です。The Prompt Shelf の解説によると、Claude Code は接続済みサーバーから全ツール定義を毎回プロンプトに積むのではなく、タスクに応じて関連ツールだけを取得する仕組みになっていて、コンテキスト削減はクライアントによっては 85〜95% に達するそうです。これは大きい。とはいえ、無制限ではない、というのが今回の主題です。

.mcp.json のスコープを3層で設計する

ここからが実務の核心です。Claude Code には MCP 設定のスコープが 3 つあります。

local(~/.claude.json):自分のマシンだけで使える。トークン入りのサーバーはここ
project(.mcp.json):リポジトリにコミットしてチーム共有
user:全プロジェクトで共通

私はこの3層を、こう使い分けています。

project スコープ:.mcp.json に「サーバー名と起動方法だけ」を置く

.mcp.json はリポジトリにコミットされるので、ここに API トークンを書くのは事故の元です。codersera のガイドでも、.mcp.json と .cursor/mcp.json は多くのチームでリポジトリにコミットされるため、env ブロックでシェル変数や .envrc を参照する形にして、トークンを直書きしないことが強く推奨されています。

こんな形にします。

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp",
      "headers": {
        "Authorization": "Bearer ${GITHUB_PAT}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

${GITHUB_PAT} の実体は .envrc(direnv)か、自分の ~/.zshrc に置く。これでリポジトリにコミットされても安全です。

local スコープ:自分専用の実験サーバー

業務で常用するサーバーは project、お試しで試したいものは local。claude mcp add のデフォルトが local なので、何も指定しなければ自分のマシンだけに残ります。

claude mcp add --transport stdio playwright-test \
  -- npx -y @playwright/mcp

プロジェクト全員に押し付ける前に、まず自分で試す。これだけで MCP サーバーが原因の謎不具合をかなり減らせます。

Streamable HTTP への移行は今やる

地味だけど 2026 年で一番効いた変更がこれです。リモート MCP サーバーは SSE から Streamable HTTP に切り替わりました。

複数の 2026 年版ガイドが揃って指摘していますが、SSE は早期 2026 年に廃止予定として位置付けられ、Streamable HTTP が Anthropic 公式の推奨トランスポートになっています。HTTP は OAuth 2.1 認証もサポートしていて、リモートで動かす MCP の事実上の標準です。

コマンドは --transport http を明示するだけ。

claude mcp add --transport http my-remote \
  https://mcp.example.com/v1

もし古い設定で --transport sse のまま動いているサーバーがあれば、提供元の HTTP エンドポイントを確認して移行しておくのが無難です。Claude Code バージョン 2.1.1 以降では、HTTP サーバーの追加に claude mcp add-json 形式が推奨されています(GitHub MCP 公式の Claude 用インストールガイドより)。

常時オンにする 5 サーバーを決める

私が 3 週間 Claude Code を回した結果、常駐させて損がなかった構成はこれでした。職種で多少変わると思うので、参考程度に。

1. GitHub MCP

Issue 読み込み、PR 作成、コードレビューの自動化。GitHub MCP 公式ドキュメントによると、Claude Code 2.1.1 以降は add-json で HTTP トランスポートを使い、https://api.githubcopilot.com/mcp を直接叩く形が主流です。Bearer トークンに GitHub PAT を渡すだけで動きます。

2. Postgres(または Supabase)

スキーマ確認と読み取り専用クエリだけでも生産性が変わります。Builder.io の解説でも、Postgres/Supabase のような直接データアクセス系は、本番の売上データ確認や 90 日購買がないユーザー抽出のような日常タスクに刺さると紹介されていました。書き込み権限は別ユーザーに分けて、Claude が触る接続は SELECT 限定にするのが鉄則です。

3. Playwright

UI 検証。ただし約 25 ツールを持ち込むので、Tool Search 任せにせず、必要なときだけプロジェクトスコープで有効化するのがおすすめ。

4. Sentry

プロダクションエラーをセッション内で直接確認できる。「ENG-4521 の機能が Sentry でどのくらいエラー出してる?」と聞ける状態は、コンテキスト切り替えが激減します。

5. Linear か Notion

チケットと仕様の参照。これは自分のチームで使っているものを選べばいい話です。

Filesystem サーバーは入れていません。Nimbalyst の 2026 年版ガイドでも、Claude Code が組み込みのファイルツールと権限ルール、サンドボックスを持っているため、専用の filesystem MCP は通常不要だと整理されています。シークレットを守りたいなら、permissions.deny と worktree を使うほうが先。

トラブルシュート:つながらない時に最初に見る3か所

設定を増やすと、必ず一度はハマります。私が今まで踏んだパターンはほぼこの 3 つに収まりました。

サーバーを追加したのに認識されない → Claude Code を完全に再起動する。ホストは起動時に設定ファイルを読み込み、変更を無視するので、リロードが必要です。
HTTP サーバーで -32000 server-not-found が出る → URL のパス末尾、Bearer トークンの有効期限、企業 Proxy 経由の場合は CA 証明書を確認。claude mcp list で登録状況、claude mcp test <name> で単体接続を確認できます。
macOS 初回起動でフォルダ権限のダイアログが出てそのまま失敗 → これは想定動作なので、権限を許可して再実行すれば動きます。Mac で MCP 経由のローカルツールを動かす時の通過儀礼みたいなものです。

それと、workspace というサーバー名は予約済みです。Claude Code 公式ドキュメントによると、この名前で設定されたサーバーはロード時にスキップされ、リネームを促す警告が出ます。地味だけど踏むと気づきにくい罠。

まとめ:今日からやる4つのアクション

長くなったので、明日の朝イチでできるアクションに絞ります。

今の .mcp.json を開いて、トークンが直書きされていないか確認する。あれば ${VAR} 形式に置換して .envrc に逃がす
接続中の MCP サーバー数を claude mcp list で数える。10 個超えていたら、プロジェクトスコープに移して常駐から外す候補を作る
SSE トランスポートのサーバーがあれば、提供元の HTTP エンドポイントに移行する(2026 年内に対応するのが安全)
Filesystem MCP を使っているなら、permissions.deny と worktree への置き換えを検討する

副業や個人開発で Claude Code を回しているなら、MCP は「便利な拡張」ではなく「設定ミスがそのまま事故になる箇所」です。逆に、ここをきちんと組めば、PR レビュー → DB 確認 → Sentry 確認 → チケット更新まで 1 セッションで終わります。私の場合、毎日 30 分くらい節約できている体感があります。

次は .mcp.json をリポジトリにコミットして、チームで共有するところまでやってみてください。共有された瞬間に、Claude Code が「自分の道具」から「チームのインフラ」に変わるので。

参考リンク

Claude Code Docs — Connect Claude Code to tools via MCP — MCP の公式仕様と workspace 予約名・自動再接続の挙動
GitHub — github-mcp-server install guide for Claude — Claude Code 2.1.1 以降の add-json 形式と HTTP トランスポート設定
The Prompt Shelf — Claude Code MCP Servers: The Complete Setup Guide for 2026 — Tool Search によるコンテキスト 85〜95% 削減の実測値
Codersera — The 15 MCP Servers Worth Wiring Into Claude Code and Cursor (2026) — 可視ツール 40〜50 個の上限と .mcp.json のシークレット管理
Nimbalyst — Claude Code MCP Setup: A Practical 2026 Guide — Filesystem MCP を入れない理由と権限ルールの優先順位
Build Fast with AI — Claude MCP Setup Guide 2026 — 2026 年 5 月時点の公開 MCP サーバー 2,300 超とエコシステムの位置付け