Claude Code MCP 入門｜.mcp.json で外部サービスに直接つなぐ

「Claude に『この API を叩いて』と頼んでも、結局は自分が curl して、結果をチャットに貼り直している」「.mcp.json を team に commit したいけれど、API キーをどこに書けばいいか分からない」「Context7 や Playwright が人気らしいけれど、入れたら何が変わるのかピンと来ない」。Claude Code を毎日使い始めた段階で必ずぶつかる壁が、外部サービスとの接続です。本記事ではその出口にあたる MCP（Model Context Protocol） を、Anthropic 公式仕様と shanraisshan さんのコミュニティ運用例で扱います。

シリーズ #09 設定階層を理解すれば事故らないで .claude/settings.json の 5 階層スタックを押さえました。本記事はその上に立つ「外との接続」レイヤーです。

TL;DR
API を curl で叩く生活、いつまで続ける？
MCP server が Claude と外部 API の橋渡しをする
公式仕様: 3 つの transport と 3 つの scope
- transport: どうやって繋ぐか
- scope: どこに書くか
Claude が MCP server を呼ぶまでの流れ
実例: .mcp.json
- リモート HTTP サーバを CLI で追加する
API キーの扱い ─ 直書きせず環境変数展開する
- .claude/settings.json 側の MCP 関連キー
踏みやすい罠 4 つ
今週やる 1 つ ─ Context7 を 1 行で追加する
まとめ

TL;DR

MCP は Anthropic が公開した「AI 〜外部サービス」のオープン規格（公式仕様 / Claude Code docs）
押さえる軸は 2 つ: transport 3 種類（stdio / http / sse は廃止）× scope 3 種類（Project / User / Subagent、優先順位は Subagent > Project > User）
API キーは .mcp.json に直書き禁止。${VAR} 形式で環境変数展開
入れすぎ厳禁。日常 3〜5 個（Context7 + Playwright + 業務固有）に絞る
今週やる 1 つ: .mcp.json に Context7 を 4 行追加するか、claude mcp add --transport stdio context7 -- npx -y @upstash/context7-mcp を 1 行叩く

API を curl で叩く生活、いつまで続ける？

Claude Code は強力ですが、チャットの中で「Notion の DB を読んで」「Sentry のエラー一覧を見て」と頼んでも、そのままでは届きません。Claude には Notion API も Sentry API も「使える道具」として登録されていないからです。

結局こうなります。

自分で curl を叩く → 結果を Claude のチャットに貼る → Claude に解析させる
Jira のチケットを開く → タイトルと本文をコピーする → Claude に貼って「これを実装して」と頼む
Figma のデザインを書き出す → 画像を貼る → Claude に説明させる

このコピペ往復が日常になると、Claude Code を使っている意味が薄れます。「Claude が直接 Notion を読めればこの作業は要らないのに」と感じ始めたら、それが MCP を入れるサインです。

MCP server が Claude と外部 API の橋渡しをする

MCP は Model Context Protocol の略で、Anthropic が公開した「AI と外部ツールを繋ぐオープン規格」です（MCP 公式仕様）。Anthropic 公式ドキュメントの Connect Claude Code to tools via MCP には、こう書かれています。

Connect a server when you find yourself copying data into chat from another tool, like an issue tracker or a monitoring dashboard. Once connected, Claude can read and act on that system directly instead of working from what you paste.

問題追跡ツールや監視ダッシュボードなどの別のツールからチャットにデータをコピーしている場合は、サーバーに接続します。接続すると、クロードは貼り付けたものから作業するのではなく、そのシステムを直接読み取って操作できるようになります。

Notion・Jira・GitHub・Sentry・Figma など、コピペで往復しているサービスを 1 つずつ MCP server に置き換えていけば、Claude のチャットがそのまま作業机になります。

公式仕様: 3 つの transport と 3 つの scope

MCP の全体像は transport（接続方式）3 種類 と scope（設定の置き場所）3 種類 の 2 軸で押さえられます。

transport: どうやって繋ぐか

公式ドキュメントの Installing MCP servers では 3 つの選択肢が並んでいますが、実質 2 つに絞ってよいことが書かれています。

transport	仕組み	公式の扱い
stdio	ローカルプロセスを spawn（`npx` / `python` / バイナリ）	推奨（ローカルツール・カスタムスクリプト）
http	リモート URL に HTTP 接続（streamable-http）	推奨（クラウドサービス）
sse	サーバから一方向にイベントを流す方式	廃止

公式から原文どおり引用します。

The SSE (Server-Sent Events) transport is deprecated. Use HTTP servers instead, where available.

SSE (Server-Sent Events) トランスポートは非推奨になりました。利用可能な場合は、代わりに HTTP サーバーを使用してください。

古い Blog 記事や Reddit ポストを見て SSE 設定で組むと、後でやり直しになります。HTTP か stdio の 2 択と覚えれば十分です。

scope: どこに書くか

MCP サーバは 3 つの場所に書けます。

scope	設定場所	用途
Project	`.mcp.json`（リポジトリ root）	チーム共有・git commit
User	`~/.claude.json` の `mcpServers` キー	自分の全プロジェクトに効く個人サーバ
Subagent	subagent frontmatter の `mcpServers` フィールド	特定 subagent 専用

shanraisshan さんの整理では、優先順位を Subagent > Project > User とまとめています。同じ名前のサーバが複数の scope に書かれた場合、subagent の定義が最も強く、user の定義が最も弱い、という関係です。

CLI から追加する場合、claude mcp add のデフォルトは local（個人のプロジェクトローカル）です。--scope project で .mcp.json 行き、--scope user で ~/.claude.json 行きを明示できます。

Claude が MCP server を呼ぶまでの流れ

flowchart TD
    A["Claude Code 起動"] --> B["スタートアップ時に<br/>.mcp.json と ~/.claude.json を読む"]
    B --> C{transport}
    C -->|stdio| D["子プロセスを spawn<br/>（npx @upstash/context7-mcp など）"]
    C -->|http| E["リモート URL に接続<br/>（https://mcp.notion.com/mcp など）"]
    D --> F["Claude に tool を登録<br/>mcp__<server>__<tool>"]
    E --> F
    F --> G["Claude がチャットで呼び出し"]
    G --> H["MCP server が外部 API を実行"]
    H --> I["結果が Claude に返る"]

ポイントは右側の mcp__<server>__<tool> という命名規則です。MCP で追加した tool は permission rule の中でこの形で識別され、allow / deny でホワイトリスト・ブラックリスト管理できます。

実例: `.mcp.json`

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@0.0.70"]
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@2.1.8"]
    },
    "deepwiki": {
      "command": "npx",
      "args": ["-y", "deepwiki-mcp@0.0.6"]
    }
  }
}

3 サーバすべて stdio transport（npx で子プロセスを spawn） です。それぞれの役割はこうなっています（ claude-mcp.md より）。

Context7: 最新のライブラリドキュメントをコンテキストに取り込む。学習データが古いせいで Claude が実在しない API を返してしまう事故を防ぐ
Playwright: ブラウザ自動化。スクリーンショット・フォーム操作・UI 機能の自律テスト
DeepWiki: GitHub リポジトリの構造化された wiki 風ドキュメントをフェッチ

「とりあえず 3 つ入れる」ところから始めたいなら、この組み合わせは現実的な雛形です。各パッケージはバージョン pin（@2.1.8 のような）してあるので、チーム内で実行結果が揺れません。

リモート HTTP サーバを CLI で追加する

.mcp.json に手で書く代わりに、Anthropic 公式 CLI で追加することもできます。公式から原文どおり引用します。

# Basic syntax
claude mcp add --transport http <name> <url>

# Real example: Connect to Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Example with Bearer token
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

--header フラグで認証ヘッダを渡せます。Notion / Asana / Airtable など、Anthropic の公式 Directory（claude.ai/directory）に並んでいる連携先は、ほぼこの形で追加できます。

API キーの扱い ─ 直書きせず環境変数展開する

.mcp.json をチームに commit するなら、認証情報の扱いを最初に決めておきます。推奨は同じで、.mcp.json には環境変数を展開する形で書き、実値はリポジトリの外に置くやり方です。

{
  "mcpServers": {
    "remote-api": {
      "type": "http",
      "url": "https://mcp.example.com/mcp?token=${MCP_API_TOKEN}"
    }
  }
}

${MCP_API_TOKEN} は実行時に環境変数から展開されます。team メンバーはそれぞれ自分のシェル（.envrc / .zshrc / .bashrc）か direnv で MCP_API_TOKEN を設定し、.envrc 自体は .gitignore に入れて commit しません。

`.claude/settings.json` 側の MCP 関連キー

シリーズ #09 で扱った .claude/settings.json の 5 階層スタックの中で、MCP サーバの auto-approval を制御する 3 つのキーがあります。

キー	型	役割
`enableAllProjectMcpServers`	boolean	`.mcp.json` の全サーバを auto-approve
`enabledMcpjsonServers`	array	名前指定で auto-approve
`disabledMcpjsonServers`	array	名前指定で reject

permission rule では tool 単位に mcp__<server>__<tool> 形式で制御できます。

{
  "permissions": {
    "allow": [
      "mcp__context7__*",
      "mcp__playwright__browser_snapshot"
    ],
    "deny": [
      "mcp__dangerous-server__*"
    ]
  }
}

「Context7 の全 tool は無条件で許可、Playwright は screenshot だけ許可、危険サーバは全拒否」のように、ホワイトリスト・ブラックリストを team の .claude/settings.json で組み上げられます。第4層に書けばチーム共有、第3層 .claude/settings.local.json に書けば自分専用、と #09 の階層に従います。

踏みやすい罠 4 つ

罠 1: API キーを `.mcp.json` に直書きして commit する

最も多い事故です。"url": "https://api.example.com/mcp?token=sk-xxxxxxxxxx" のように実値を書いて git push すると、公開リポなら数分で botに発見されます。社内リポでも組織内全員に見えます。実値は環境変数経由で渡し、.mcp.json には ${VAR} だけ書くを徹底します。

git diff で commit 前に必ず確認するか、git-secrets のような pre-commit hook を入れて自動検出するのが現実解です。

罠 2: MCP server を入れすぎてコンテキストを食う

“Went overboard with 15 MCP servers thinking more = better. Ended up using only 4 daily.” — r/mcp

「多い＝良いと考えて 15 台の MCP サーバーを使いすぎました。最終的には毎日 4 台しか使用しませんでした。」 — r/mcp

各 MCP server は tool 一覧をコンテキストに乗せるので、入れすぎると Claude の判断が鈍ります。日常 3〜5 個に絞り、月 1 回見直して使っていないサーバは外す運用が合理的です。

最初に入れて損のない組み合わせは「Context7（最新 docs）+ Playwright（ブラウザ操作）+ 業務固有 1 つ」あたりです。

罠 3: 古い記事を真似て SSE transport を選ぶ

MCP は 2024 年から急速に進化しているので、ネット上には SSE 前提の解説が大量に残っています。今から組むなら公式ドキュメントどおり HTTP か stdio の 2 択に絞ります。SSE で書いても動きはしますが、deprecated が外れたタイミングで書き換えが発生します。

判別の手順:

接続先サーバが http エンドポイントを公開していれば --transport http
ローカルで実行する npm パッケージや Python スクリプトなら --transport stdio
SSE しか提供していない古いサーバは、HTTP 版が出るまで使わないか、提供元に問い合わせる

罠 4: scope ごとの優先順位を取り違える

「subagent 内で MCP サーバを上書きしたつもりが、効いていない」。.mcp.json（Project）と subagent frontmatter mcpServers の両方に同じ名前のサーバを書くと、優先順位は Subagent > Project > User の関係なので subagent 側が勝ちます。逆に「Project に書いた便利サーバが subagent で使えない」と感じたら、その subagent の frontmatter が同名のサーバを上書きしている可能性があります。

active な MCP server を確認するときは、Claude Code 内で /mcp を実行します。各サーバの接続状態と利用可能な tool が一覧できるので、scope の競合を疑う前にここを見るのが早いです。

今週やる 1 つ ─ Context7 を 1 行で追加する

「とりあえず 1 個試したい」なら Context7 が最短です。Next.js / React / FastAPI / Django のような変化の速いフレームワークの最新ドキュメントを、Claude のコンテキストに直接取り込めます。学習データが古いせいで Claude が実在しない API を作り出してしまう事故が劇的に減ります。

リポジトリ root に .mcp.json を作って、これだけ書きます。

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    }
  }
}

CLI 派なら 1 行で済みます。

claude mcp add --transport stdio context7 -- npx -y @upstash/context7-mcp

その日のうちに「React Server Components の最新パターンを教えて」と聞いてみます。Context7 を入れる前は学習データに残っている古い API を返していた質問が、最新のドキュメントに基づいた答えに変わるのを体感できます。

まとめ

MCP は Claude Code を「チャットだけのアシスタント」から「外部サービスに直接手を伸ばせる作業机」に変える仕組みです。押さえる軸は 2 つだけで、transport（stdio / http、SSE は廃止） と scope（Project / User / Subagent、優先順位は Subagent > Project > User）。.mcp.json をチームに commit するときは認証情報を環境変数展開して直書きしない、サーバは日常 3〜5 個に絞る、SSE は選ばない ─ この 3 点で運用は安定します。

シリーズ #09 で扱った .claude/settings.json の 5 階層と組み合わせれば、「team 共有の MCP サーバを .claude/settings.json で auto-approve しつつ、危険な tool は deny で塞ぐ」といった運用も組めます。Phase D の入口として、今週中に Context7 を 1 個入れるところから始めるのが現実的な一歩です。