8-1 Claude Code MCP とは｜設定と仕組みを徹底解説

このレッスンで身につくこと

このレッスンは第 8 章「MCP 連携」の 入口 です。MCP を実際に使い倒すのは 8-2 / 8-3 で扱うので、ここではまず MCP が何者で、なぜ「Claude Code 時代の標準プロトコル」と呼ばれるのか を腹落ちさせます。

所要時間 — 約 60 分（読むだけなら 30 分） / 難易度 — ★★★☆☆

MCP が誕生した背景 — M × N 問題

MCP は 2024 年 11 月に Anthropic が発表 し、その後オープンソース化されたプロトコルです。一言で言うと AI エージェント × 外部ツールの「組み合わせ爆発」を共通プロトコルで終わらせるため に作られました。

MCP 登場前 — 毎回ゼロから書いていた

MCP 以前、AI エージェントに外部ツールを使わせるには ツールごと・LLM ごとに作り直し が必要でした。Slack なら Slack API、GitHub なら GitHub API を読み、それを Claude / GPT / Gemini それぞれ別フォーマット で関数定義し直す。

これが M（ホスト数）× N（ツール数） の組み合わせ爆発、いわゆる M × N 問題。M ホスト × N ツールを別実装すると、開発者全員が同じ車輪を再発明する地獄になります。

MCP 登場後 — M + N に圧縮された世界

MCP はこれを USB-C 方式 で解決します。コネクタ規格を 1 つに統一して、ノート PC・スマホ・モニターを全部繋げられるようにしたのと同じ発想です。

ツール提供者 → MCP サーバーを 1 つ実装
ホスト       → MCP クライアントを 1 つ実装

→ M + N の実装で済む
→ 新ホストが出ても既存サーバー全部使える
→ 新ツールが MCP 公開すれば全 AI から即使える

2026 年現在、Anthropic だけでなく OpenAI、Google、Microsoft、IDE 各社（Cursor、Zed、Continue など） が MCP をサポートしており、AI エージェント時代の 事実上の標準 となりました。

「OpenAPI で良くない？」への答え

「Web API には既に OpenAPI があるじゃないか」とよく聞かれますが、答えは OpenAPI は AI 用に設計されていない です。

• OpenAPI は「人間が REST API を読む / クライアントを生成する」前提のスキーマ
• AI に渡すには、ツール説明・認証フロー・ストリーミング応答などの抽象が足りない
• AI ホスト側の「呼び方の標準」が定義されていない

MCP は最初から AI エージェントが扱いやすい単位 で、Tools / Resources / Prompts という 3 つの抽象を備えています。

MCP の正体 — クライアント / サーバー / トランスポート

MCP の中身は 3 つの登場人物 で構成されます。

• ホスト（Host） — ユーザーが直接触るアプリ。Claude Code、Claude Desktop、Cursor / Zed / Continue などが該当。「ユーザーの指示を LLM に渡し、必要なら MCP 経由でツールを呼ぶ」司令塔
• クライアント（Client） — ホスト内部の接続管理オブジェクト。「MCP サーバー 1 つにつきクライアント 1 つ」が並行起動。/mcp で見えるサーバー状態はクライアント越しの観測値
• サーバー（Server） — 外部ツールを Tools / Resources / Prompts として公開 する独立プログラム。Claude Code はサーバーの中身を一切知らず、自己申告された Tools 定義 を LLM に渡すだけ

MCP Server の 3 プリミティブ

Tools     副作用ありの関数（create_issue, send_message, ...）
Resources 副作用なしの読み取り（DB スキーマ, ドキュメント, ファイル）
Prompts   事前定義されたプロンプトテンプレート（レビュー手順, etc.）

Claude Code が最もよく使うのは Tools。Resources / Prompts はまだ対応サーバーが少なく、Tools のみのサーバーが大半です。

トランスポート（通信路）の 3 種類

クライアントとサーバーは JSON-RPC 2.0 でやりとりしますが、それを運ぶ「通信路」には次の 3 種類があります。

「ローカル MCP は stdio、クラウド提供は HTTP 系」と覚えれば、まずは十分です。

JSON-RPC 2.0 ベースの通信 — リクエスト / レスポンスの実例

MCP の通信は JSON-RPC 2.0 です。JSON-RPC は「JSON で関数呼び出しを表現する」シンプルな規格で、Web 開発者にもなじみやすい形をしています。

通信は次の 3 段階で進みます。

1. initialize で握手

接続開始時、クライアントが ==initialize を投げ、サーバーが自分のプロトコルバージョンと capabilities を返します。バージョン不一致なら /mcp がエラー== になります。

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2026-02-01",
    "capabilities": { "tools": {} },
    "clientInfo": { "name": "claude-code", "version": "1.5.0" }
  }
}

2. tools/list でツール一覧取得

Claude Code は ==tools/list で使えるツール一覧を取得。サーバーは JSON Schema 付きの定義== を返し、Claude Code はこれを LLM のプロンプトに含めて「使えるツール」を知らせます。

{
  "tools": [
    {
      "name": "list_issues",
      "description": "Get a list of issues from a GitHub repository",
      "inputSchema": {
        "type": "object",
        "properties": {
          "owner": { "type": "string" },
          "repo": { "type": "string" },
          "state": { "enum": ["open", "closed", "all"] }
        },
        "required": ["owner", "repo"]
      }
    }
  ]
}

3. tools/call で実行

ユーザーが「Issue 一覧を見せて」と指示すると、Claude モデルが ツールと引数を組み立て、クライアントが ==tools/call を発行。サーバーは外部 API を叩き、結果を content 配列== で返します。

MCP と OpenAPI / Function Calling の違い

よく混同される 3 概念を整理します。

一言ずつでまとめると、OpenAPI は「REST API の説明書」、Function Calling は「LLM プロバイダが提供するツール呼び出し API」、MCP は「AI ホスト × ツール提供者の間に立つ独立した接続プロトコル」です。

Function Calling は 同じ LLM プロバイダの中だけで完結 する一方、MCP は プロバイダの外 に立つので Claude / GPT / Gemini どれからでも同じサーバーを呼べます。Function Calling だけの世界では ChatGPT / Claude / Gemini 用に書き直しが必要ですが、MCP では サーバーを 1 個書くだけで全 AI から呼べます。

MCP サーバー内部では最終的に REST API（OpenAPI で記述された外部 API） を叩くことも多く、MCP は OpenAPI の上に乗る "AI 用のフロントエンド"。両者は競合ではなく補完関係です。

Claude Code との関係 — .mcp.json と claude mcp add

Claude Code は MCP に ホスト側 として参加します。設定の入り口は User / Project / Local の 3 ファイル（詳細は次章）。基本フォーマットは次の通りです。

{
  "mcpServers": {
    "<server-key>": {
      "command": "npx",
      "args": ["-y", "<package-name>", "<arg1>", "..."],
      "env": { "<ENV_VAR>": "<value>" }
    }
  }
}

• ==<server-key>== — Claude Code 内部で識別する任意の名前
• ==command / args== — 起動コマンドと引数（パッケージ名・許可ディレクトリ・接続文字列）
• ==env== — サーバープロセスに渡す環境変数（API キー等）

リモート MCP は "transport": "http" と "url" の形。CLI からの追加もできます。

# stdio
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /Users/me/docs

# HTTP（リモート MCP）
claude mcp add --transport http context7 https://mcp.context7.com/mcp

# スコープ指定
claude mcp add --scope project linear -- npx -y linear-mcp

設定後、Claude Code を再起動して /mcp を実行すると、接続中のサーバーが一覧表示されます。✓ が成功、✗ がエラーです。

> /mcp

✓ filesystem  (3 tools)
✓ github      (12 tools)
✗ postgres    (connection failed)

公式 MCP サーバー 8 種類 — 用途別マップ

MCP サーバーは 2026 年時点で公式・コミュニティ合わせて 1000 種類以上 あります。ここでは初学者がまず把握しておくべき 公式 8 種 を用途別に紹介します。

選び方のコツ は、自分の業務で「今いちばん手作業で面倒だ」と感じているツールに対応するサーバーを 1 つだけ試すこと。たくさん入れて満足するのではなく、1 つ深く使い込む ところから入りましょう。

その他の人気サーバー（参考）

公式以外でも、次のような MCP サーバーが急速に普及しています。

サーバーの最新一覧は公式 MCP Servers Registry（github.com/modelcontextprotocol/servers）と、コミュニティ運営の Smithery（smithery.ai）でカテゴリ別に検索できます。

設定の 3 スコープ — User / Project / Local の使い分け

Claude Code では MCP サーバーを 3 つのスコープ で管理できます。スコープによって 設定の場所・共有範囲・優先順位 が変わります。

使い分けの指針

• User — どのプロジェクトでも使う共通サーバー（github, brave-search, context7）。自分の PAT・API キーが入っても他人に見られない
• Project — プロジェクト固有でチーム全員が同じ設定を使うべきもの（DB、デザインファイル、Sentry プロジェクト ID）。API キーは 環境変数経由 にしてファイルは Git コミット可能に
• Local — プロジェクト固有だが個人の上書き（個別 PAT、自分の検証環境）。==.gitignore に追加== して絶対にコミットしない

優先順位

複数スコープに 同じキー のサーバーが定義されている場合、Local > Project > User の順で優先されます。たとえば .mcp.json で db キーで本番 DB を定義し、自分だけ .claude/settings.local.json で同じ db キーを検証 DB に上書き、という使い方ができます。

この階層モデルは ==Git の .gitconfig や ESLint の .eslintrc== と同じ発想で、「グローバル → プロジェクト → ローカル」の順に上書きしていく感覚で馴染みやすいでしょう。

インストール実例 1 — filesystem MCP

最初は最も導入しやすい filesystem MCP。User スコープ（~/.claude/settings.json）に次を追記し、Claude Code を /quit で再起動します。

{
  "mcpServers": {
    "design-docs": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/me/Documents/design-docs"
      ]
    }
  }
}

==args の 3 つ目以降に「許可するディレクトリ」== を列挙。それ以外のパスは MCP サーバー側でブロックされ、Claude Code から見えません。再起動後、/mcp で ✓ design-docs (5 tools) と表示されれば成功です。

インストール実例 2 — github MCP

次は GitHub MCP。Issue / PR / コミットを自然言語で操作できます。

まず GitHub の Settings → Developer settings → Personal access tokens で PAT を発行。スコープは ==repo / read:org の最小限 に絞り、delete_repo などの破壊的スコープは付けない== こと。

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx" }
    }
  },
  "permissions": {
    "allow": ["mcp__github__list_issues", "mcp__github__get_issue"],
    "ask":   ["mcp__github__create_pull_request", "mcp__github__create_issue"],
    "deny":  ["mcp__github__delete_repository"]
  }
}

allow は確認なし（読み取り系）、ask は毎回確認（書き込み系）、deny は絶対に実行しない（破壊系）。「読み取りは自由、書き込みは確認、削除は禁止」の運用になります。

インストール実例 3 — postgres MCP

3 つ目は PostgreSQL MCP。DB スキーマを意識したコード生成が可能になります。

本番 DB を触らせるなら、まず 読み取り専用ユーザー を用意します。

CREATE USER claude_readonly WITH PASSWORD 'changeme';
GRANT CONNECT ON DATABASE app TO claude_readonly;
GRANT USAGE ON SCHEMA public TO claude_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO claude_readonly;

次に .mcp.json（Project スコープ、チーム共有）に追記します。

{
  "mcpServers": {
    "db": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://claude_readonly:${DB_PASSWORD}@localhost:5432/app"
      ]
    }
  }
}

${DB_PASSWORD} は 環境変数から差し込み ます。各メンバーが自分の .envrc などで設定する運用が安全です。

> users テーブルのスキーマを教えて
> 過去 7 日の新規登録数を日別で集計して

セキュリティと権限管理

MCP サーバーは Claude Code と同じ権限 でローカルプロセスとして起動します。便利な分、設定を誤ると本番 DB を破壊したり、機密情報を漏らしたりするリスクもあります。

MCP 導入時のチェックリスト

<Checklist id="lesson-8-1-security" items={["配布元の信頼性を確認した（公式・大手ベンダー製・Star 数の多い OSS を優先）","npm パッケージの package.json と main エントリを目視確認した","API キー・PAT は最小権限スコープに絞った（書き込み不要なら read-only のみ）","本番 DB に繋ぐ場合は読み取り専用ユーザーで接続している",".mcp.json をコミットする場合、シークレットは環境変数経由で渡している"]} />

mcp__* permissions で細かく制御

Claude Code は、各 MCP ツールを ==mcp__<server>__<tool> というキーで権限制御できます。危険な操作は ask か deny== にしておき、一括承認モード（--dangerously-skip-permissions）では絶対に使わない運用が安全です。

{
  "permissions": {
    "allow": ["mcp__github__list_issues", "mcp__postgres__query"],
    "ask":   ["mcp__github__create_pull_request", "mcp__slack__send_message"],
    "deny":  ["mcp__github__delete_repository", "mcp__filesystem__write_file"]
  }
}

リモート MCP の OAuth 2.1

リモート MCP（HTTP 系）はネットワーク越しなので「誰として接続するか」を証明する必要があり、MCP 仕様では OAuth 2.1 が標準採用されています。

認可フローを簡略化すると次のステップです。

1. Claude Code が初回接続 → サーバーが 401 を返す
2. Claude Code が ブラウザを自動で開いて 認可画面に誘導
3. ユーザーがログイン・同意 → authorization_code 発行
4. Claude Code が PKCE 付きで access_token に交換
5. 以降は Bearer token を付けて MCP サーバーに再接続

取得したトークンは macOS Keychain / Windows Credential Manager に保存され、refresh_token で自動更新されます。

# 認可が必要なリモート MCP の追加
claude mcp add --transport http --oauth notion https://mcp.notion.com

よくあるトラブル

MCP の運用で頻発するトラブルを、原因と対処をセットで並べます。

/mcp で「error」と表示される

MCP サーバーの起動時にクラッシュしている 可能性が高いです。ターミナルでサーバーを直接実行してエラーを確認するのが最短ルートです。

GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx \
  npx -y @modelcontextprotocol/server-github 2>&1 | head -30

典型的な原因は 認証失敗（PAT スコープ不足） / Node.js のバージョン不一致（v18 未満） / 接続文字列のミス の 3 つです。

ツールが 0 個と表示される

サーバーは起動しているのに /mcp で (0 tools) の場合、原因は ==tools/list が空 か プロトコルバージョン不一致== です。古い MCP SDK だと 2024 年初期の仕様で止まっていることがあります。

npm install -g @modelcontextprotocol/server-github@latest

依存パッケージを 最新版にアップデート すると解決することが多いです。

設定が反映されない

MCP サーバーの設定は Claude Code の起動時に読み込まれます。ファイルを編集しただけでは反映されません。/quit で抜けてから再起動してください。

また、複数スコープの優先順位は Local > Project > User。「User で書いたのに Project の設定で上書きされている」ケースがよくあります。

JSON 構文エラー

.mcp.json や settings.json の編集ミスで多いのが 末尾カンマ や キーのクォート漏れ。python3 -m json.tool < ~/.claude/settings.json で構文チェックできます。

コミット事故 — API キーを Git に push してしまった

即時 Revoke が最優先です。GitHub PAT なら GitHub 上で revoke、Stripe Key なら Stripe ダッシュボードで revoke。新しいキーを発行し、.gitignore に追加して git filter-repo で履歴からも削除します。

これを防ぐには、最初から ==.mcp.json の env を ${VAR_NAME} 記法 にして、シークレットを ファイルに書かない== 運用が安全です。

まとめ

このレッスンで押さえてほしいポイントは次の 8 つです。

1. MCP は M × N 問題 を M + N に圧縮するオープンプロトコル。USB-C と同じ発想
2. 構成は ホスト / クライアント / サーバー の 3 役。通信は JSON-RPC 2.0
3. トランスポートは stdio（ローカル）と HTTP 系（リモート）の 2 系統
4. プリミティブは Tools / Resources / Prompts。主に使うのは Tools
5. OpenAPI / Function Calling とは目的が違う 補完関係
6. 設定スコープは User / Project / Local。優先順位は Local > Project > User
7. 公式 MCP 8 種（filesystem / postgres / github / google-drive / slack / brave-search / cloudflare / stripe）で大半をカバー
8. ==mcp__* permissions== で危険操作を ask or deny、シークレットは 環境変数経由

<Quiz question="MCP が解決する「M × N 問題」とは何ですか？" options={["M 個の AI ホストと N 個の外部ツールの組み合わせ爆発を、共通プロトコルで M + N に圧縮する問題","M 個のモデルが N 個のパラメータを最適化する計算量問題","M 個のメモリと N 個のネットワーク接続の同時利用問題"]} answer={0} />

<Quiz question="Claude Code の MCP 設定スコープの優先順位として正しいものは？" options={[ "Local > Project > User", "User > Project > Local", "Project > User > Local", ]} answer={0} />

次のレッスン 8-2: Notion・Google Drive 連携 では、Notion と Google Drive を Claude Code に接続する具体的なワークフロー を扱います。議事録の自動作成、DB 横断検索、スプレッドシート操作など業務直結の MCP 活用例を見ていきます。