第9章サブエージェントと MCP

第9章は、Code を「1人の AI」として使うのではなく、「複数の AI を並列で使う」「外部サービスと連携させる」というレベルに進む章です。

ここまでで作業の基礎は全部入っているので、第9章の内容は「できるとさらに便利」というポジショニング。僕自身、訪看アプリを作る過程で必要になって覚えた、という順序でした。

扱う内容：

サブエージェントという、Code の中で別働隊を動かす仕組み
MCP（Model Context Protocol）の本質
自分が必要とする MCP の見極め方
実例として Supabase MCP と GitHub MCP

「使わなくても進める」けど、「使うと選択肢が広がる」、そんな章です。

9-1. サブエージェントの概念：コンテキスト分離の意義

【学習目標】

サブエージェントが何か、なぜ必要かを理解する
コンテキスト分離のメリットを実感する

【前提知識】

第8章まで完了していること
6-1 でコンテキストウィンドウを理解していること

【概念解説】

第6章で「コンテキストウィンドウには上限がある」と学びました。長いセッションだと、Code がだんだん「変になる」現象も見ました。

これを別のアプローチで解決するのが、サブエージェントという仕組みです。

サブエージェントとは

メインの Code（メインエージェント）が、自分の中に「別働隊」を作って、特定のタスクをそちらに任せる仕組み。

イメージで言うと、

[メインエージェント（あなたと会話している Code）]
  ├── サブエージェント1（ファイル調査担当）
  ├── サブエージェント2（コードレビュー担当）
  └── サブエージェント3（ドキュメント生成担当）

メインは指揮官。サブが実働部隊。

なぜ別働隊が必要か

たとえば「このプロジェクト全体のコードをレビューして、改善点をまとめて」と依頼したとします。

メインだけでやろうとすると、

全ファイルを順に読み込む
コンテキストウィンドウが一気に圧迫される
後の会話に影響が出る

これをサブエージェントに任せると、

サブが全ファイルを読み込む（サブ専用のコンテキストウィンドウを使う）
サブが結果（改善点のサマリ）だけメインに返す
メインのコンテキストは消費されない

結果、メインは身軽なまま、大規模な調査もできる。

何ができるようになるか

サブエージェントを使うと、こんなことが楽になります。

巨大なファイル群を調査する
複数の独立したタスクを並列で進める
「探索」と「実装」を分離する
メインのコンテキストを温存しながら、追加調査を走らせる

ただし、初心者は使わなくても進める

僕も訪看アプリを作る過程では、サブエージェントを能動的に使ったことはほぼないです。Code が自動的に「これはサブエージェントにやらせよう」と判断する場面はありましたが、自分から指示することはなかった、と感じています。

なので、第9章の内容は「こういう仕組みがある、と知っておく」レベルで充分。

【ハンズオン手順】

▼ ブラウザ側でやること

ブラウザに次のように打って、自分の理解を確かめる

Claude Code のサブエージェント機能を、人間の組織に例えて
説明してください。「メインエージェント」と「サブエージェント」が
どう協力するのか、初心者にも分かるように。

「指揮官と実働部隊」「マネージャーと部下」のような比喩が返ってくる
自分にしっくりくる例を頭に入れておく

【つまずきポイント】

サブエージェントは「使わないと困る」ものではない。普通の作業はメインだけで進めます
サブを増やしすぎると逆に混乱。必要な時だけ使うのが鉄則

【確認問題】

サブエージェントを使うメリットは何ですか？
メインとサブのコンテキストウィンドウは、共有されますか？

【次のレッスンへの橋渡し】

サブエージェントの概念が見えました。次は、それを呼び出す具体的な仕組み「Task ツール」と「ブランチ／フォーク」について。

9-2. Task ツールと `/branch` `/fork`

【学習目標】

サブエージェントを呼び出す3つの方法を知る
「ブランチ」と「フォーク」の違いを区別する

【前提知識】

9-1 でサブエージェントの概念を理解していること

【概念解説】

サブエージェントを使う方法は、主に3つあります。

1. Task ツール（Code が自動で使う）

Code は内部的に「Task ツール」というのを持っていて、必要な時に勝手にサブエージェントを起動します。

たとえば「このプロジェクトの全ファイルを調査して」のような依頼の時、Code は自動で Task ツールを使ってサブエージェントを立ち上げ、調査だけをやらせます。

これは意識しなくていい仕組み。Code が判断します。

2. /branch（手動でセッションを分岐させる）

現在のセッションから「枝分かれ」する仕組み。

[今のセッション]
   ↓ /branch
[分岐したセッション] ← 親のコンテキストを引き継ぐが、独立して動く

何が嬉しいかというと、

「今のセッションで実験的に何かを試したい」時
失敗しても本流のセッションに影響しない
「if this then that」のような分岐シミュレーションがやりやすい

たとえば、「現在の実装をベースに、別のアプローチも試したい」という時に /branch で枝分かれします。

3. /fork（手動でセッションを複製する）

/branch と似ていますが、こちらは「完全な複製」を作ります。

[今のセッション]
   ↓ /fork
[完全に独立したセッション] ← 親と全く同じ状態からスタート、その後は別物

主な用途は、

「同じ状態から、複数のアプローチを並列で試したい」
「ある状態を保存して、別の実験を進めたい」

僕の実体験では、訪看アプリで RLS Policy（データベースのアクセス制御）の修正を進める時に、Code が /fork を使っているのを見ました。「同じ問題に対して、複数の解決策を並行検討する」シーンで便利。

ブランチとフォークの違い（簡単な整理）

	`/branch`	`/fork`
親との関係	親に紐づいた枝分かれ	完全に独立した複製
用途	「もし○○だったら？」のシミュレーション	「同じ起点から、別の道」
戻る	元のセッションに戻りやすい	戻る概念がない

これ、Git の「ブランチ」と「フォーク」とは別物なので注意。Git のブランチとフォークも別の意味があります（混乱しがちですが、別世界の話）。

初心者は知っておくだけでOK

僕は「実際に /branch や /fork を意識して使ったことはほぼない。Code が勝手にサブエージェントを動かしてるのを見るだけだった」と言っています。

なので、本章のここは「こういう仕組みがあるよ」を頭に入れるだけで充分。実際に必要になる場面はかなり先です。

【ハンズオン手順】

▼ Code 側でやること（Task ツールを観察する）

Code に大きめの依頼を出す（例：「このプロジェクトの全 HTML ファイルを読んで、改善案を5つ提案してください」）
Code の応答の中で「サブエージェントを起動しました」「Task を実行中」のような表示が出る場合がある
これが Task ツールでサブエージェントが動いている瞬間です

▼ Code 側でやること（コマンド一覧で確認）

/ だけ打って、コマンド一覧を表示
/branch /fork などのコマンドが見えるはず
それぞれのヘルプを見るだけでOK（実際に実行する必要はなし）

▼ スクショ伴走のチェックポイント

サブエージェントが動いている画面のスクショ
/branch /fork のヘルプ表示

【つまずきポイント】

/branch /fork を覚えなくていい。Code が必要な時に勝手に使うものだと思っておけばOK
Git のブランチ・フォークと混同しない。別の概念です

【確認問題】

Code が自動でサブエージェントを起動する仕組みは何と呼ばれますか？
/branch と /fork の違いを、自分の言葉で説明してください

【次のレッスンへの橋渡し】

サブエージェントの世界の俯瞰が終わりました。ここからは MCP の話に入ります。

9-3. MCP の本質を再確認 — どんなときに必要か、どんなときに不要か

【学習目標】

MCP が必要な場面と不要な場面を判別できる
「全部入れちゃおう」が罠だと理解する

【前提知識】

2-6 で MCP の概要を知っていること

【概念解説】

第2章で MCP の概要を「CLI で叩けないサービスへの橋」として紹介しました。改めて、もう少し深く見ていきます。

MCP が必要な場面

Claude Code は、ターミナル経由でできることは何でもできる。
でも、ターミナルから直接触れないサービスは別。
そういうサービスを Claude が操作するための「橋」が MCP。

具体的な「ターミナルから直接触れないサービス」の例：

Notion：ページの作成・編集・読み取り
Slack：メッセージの送受信
Stripe：決済関連の操作
Linear / Jira：チケット管理
Figma：デザインファイルの操作
Notion：ドキュメントの読み書き

これらは、ブラウザでログインして使うサービス。Claude Code が「裏でログインして操作」するためには、MCP が必要です。

MCP が不要な場面（あえて使わない）

逆に、MCP を入れる必要がない場面もあります。

GitHub：ターミナルから git コマンドで操作できるので、MCP なしでも push 可能
Cloudflare Pages：GitHub 連携の自動デプロイなので、特別な操作不要
ファイル操作：Claude Code の本来の能力

つまり、「すでに自然に使えているサービス」には MCP を入れないのが原則。

「30個入れちゃおう」は罠

MCP マーケット（GitHub などで公開されている MCP）には、数百種類の MCP があります。便利そうに見えるけど、全部入れる必要はないどころか、入れない方がいい。

理由は3つ。

Claude が選択肢で混乱する
- 「あれ、これは MCP A でやる？それとも MCP B でやる？」と判断に時間がかかる
自分が把握できない
- 何の MCP を入れたか忘れる
セキュリティリスク
- 多くの MCP は外部開発者が作ったもの。信頼できないものを入れるとリスク

僕の MCP 選び

僕が訪看アプリで MCP を導入した時の基準：

そのプロジェクトで本当に必要か？
頻繁に使うか？（年に1回しか使わないなら不要）
公式または信頼できる提供元か？

この3つ全部 ◎ の時だけ導入。それ以外はノー。

【ハンズオン手順】

▼ ブラウザ側でやること

ブラウザに次のように打って、自分のプロジェクトに必要な MCP を考える

私は HTML/CSS/JavaScript と Supabase を使って Web アプリを
作っています。デプロイは Cloudflare Pages、コード管理は GitHub です。
このプロジェクトで MCP を入れるべきか、入れるならどれか、教えてください。

ブラウザが「○○なら入れる価値あり、○○は不要」と整理してくれる
自分のプロジェクトに本当に必要なものを選別

▼ スクショ伴走のチェックポイント

ブラウザの MCP 選定アドバイスのスクショ

【つまずきポイント】

SNS で話題の MCP に飛びつかない。「みんなが使ってる」と「自分に必要」は別の話
「便利そうだから」で入れると、すぐ忘れる。本当に必要になってから入れる

【確認問題】

MCP が必要なサービスの典型例を3つ挙げてください
MCP を「全部入れる」のが推奨されない理由を3つ挙げてください

【次のレッスンへの橋渡し】

必要性の見極めができました。次は、自分が使うサービスの MCP だけを入れる原則を、もう少し具体的に。

9-4. 自分が使うサービスの MCP だけ入れる原則

【学習目標】

MCP 選定の判断軸を具体的に持つ
「必要になったら追加する」流儀を身につける

【前提知識】

9-3 で MCP の必要性判断ができていること

【概念解説】

「使う MCP だけ入れる」原則を、もう少し具体化します。

MCP を入れるべきタイミング

[特定のサービスを使い始める]
↓
[Code 経由で操作したくなる]
↓
[頻繁に使うことが分かる]
↓
[初めて MCP を導入]

最初から「念のため」で入れない。実際に困ってから入れる。

典型的な MCP 導入の流れ

たとえば「Notion で議事録を管理しているのを、Code から書き換えたい」と思った時：

ブラウザに「Code から Notion を操作したい。MCP は必要？」と聞く
ブラウザが「Notion MCP を入れると、Code から Notion ページを操作できます」と教えてくれる
Notion MCP のインストール手順をブラウザに聞く
手順に従って Code に設定する
Code を再起動して、Notion 操作が使えるか確認

MCP の設定ファイル：.mcp.json

MCP は .mcp.json というファイルで管理されます。プロジェクトフォルダの中に置いておく、設定ファイル。

中身はこんな感じ：

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-notion"],
      "env": {
        "NOTION_API_KEY": "..."
      }
    }
  }
}

このファイルを Code が読んで、起動時に MCP サーバーを立ち上げます。

設定は Code に任せていい

.mcp.json の中身を手書きする必要はないです。Code に依頼すれば書いてくれます。

Notion MCP を使いたい。.mcp.json に設定を書いてください。
API キーは XXX です。

これで Code が .mcp.json を作る・更新します。

「自分のプロジェクト専用」と「グローバル」

MCP の設定は、

プロジェクト固有：そのフォルダの .mcp.json
グローバル：ホームディレクトリの設定ファイル

があります。普通はプロジェクト固有でOK。「全プロジェクト共通で使いたい」と思った時だけ、グローバルに移動。

僕の実例：訪看アプリでの MCP

僕は訪看アプリで、最終的に2つの MCP だけを入れています。

Supabase MCP：データベースの中身を Code から直接見たり書き換えたりするため
GitHub MCP：イシュー管理や PR 操作のため（後で入れた）

それ以外は不要でした。「シンプルに必要なものだけ」が僕のやり方。

【ハンズオン手順】

▼ ブラウザ側でやること（自分の MCP リストを作る）

ブラウザに次のように打つ

これから1ヶ月、Web アプリの開発と運用をします。
頻繁に使うサービス：
- GitHub
- Cloudflare Pages
- Supabase
- Notion（ドキュメント管理）

この中で MCP を入れるべきものはどれですか？理由付きで教えてください。

ブラウザがアドバイスを返す
その結果をメモ

▼ Code 側でやること（実際に MCP を1つ入れてみる、任意）

アドバイスを踏まえて、1つ選ぶ
Code に「○○ MCP を導入してください」と依頼
Code が手順を提示
認証情報（API キーなど）が必要な場合は、ブラウザで取得方法を確認しながら進める
完了したら Code を再起動して動作確認

▼ スクショ伴走のチェックポイント

.mcp.json ができた状態のスクショ
初めて MCP 経由で操作できた瞬間のスクショ

【つまずきポイント】

「Notion MCP を入れたら Notion をフルに使える」とは限らない。MCP によって機能の範囲が違います。事前に「Notion MCP で何ができるか」をブラウザに確認
API キーや認証情報の管理に注意。.mcp.json を GitHub に Public で push するとキーが漏洩します。.gitignore に追加するか、環境変数を使うのが安全

【確認問題】

MCP 設定ファイルの名前は何ですか？
MCP は最初から全部入れるべきですか、必要になったら入れるべきですか？

【次のレッスンへの橋渡し】

選び方が分かりました。次は具体例として、Supabase MCP と GitHub MCP を見ていきます。

9-5. 実例：Supabase MCP / GitHub MCP の導入

【学習目標】

Supabase MCP と GitHub MCP の代表的な使い道を知る
導入の流れをイメージできる

【前提知識】

9-4 で MCP 選定の判断軸を理解していること

【概念解説】

具体的な MCP の中身を2つだけ見ていきます。これがあると「ああ、これは便利かも」と実感できます。

Supabase MCP

Supabase（データベース）を、Code から直接操作できるようにする MCP。

何ができるか

データベースの中身（テーブル一覧、レコード）を Code から直接見られる
SQL を Code 経由で実行できる
RLS Policy などの設定を Code から変更できる

何が嬉しいか

これがない世界では、データベースを触りたい時はこういう流れになります：

1. Code に「○○というデータが必要」と伝える
2. Code が SQL を提案
3. ブラウザで Supabase の管理画面を開く
4. SQL Editor を開く
5. Code からコピーした SQL を貼り付け
6. 実行
7. 結果をスクショして Code に返す

これが、Supabase MCP を入れると：

1. Code に「○○というデータが必要」と伝える
2. Code が自分で SQL を組み立てて実行、結果を返す

僕が感動したシーン

僕が訪看アプリで RLS Policy（誰がどのデータを見られるかの設定）を修正した時、Supabase MCP のおかげで一気に修正できました。

それまでは「Code が SQL を出す → 自分が Supabase 管理画面にコピペ → 結果スクショ」を10回繰り返していた作業が、MCP を入れてから「Code に依頼して結果を見る」だけで完結するようになった。作業時間が体感1/5以下に。

GitHub MCP

GitHub の各種操作を、Code から直接できるようにする MCP。

何ができるか

GitHub のイシュー（タスク管理用のもの）の作成・閲覧・編集
プルリクエストの作成・レビュー
リポジトリ情報の確認

いつ必要になるか

普通の git push だけなら GitHub MCP は不要。でも、

GitHub の「Issues」を Code から管理したい
プルリクエストのレビューを Code に手伝わせたい
複数のリポジトリを横断的に管理したい

こういう場面で GitHub MCP が活きます。

導入の流れ（共通）

どの MCP も、導入の流れはほぼ同じです。

1. ブラウザで「○○ MCP の導入手順を教えて」と聞く
2. 必要な認証情報（API キーなど）を取得
3. Code に「○○ MCP を入れたい」と依頼
4. Code が .mcp.json を更新
5. Code 再起動
6. 動作確認

これだけ。インストール時の手順は Code とブラウザに任せ、自分はコピペとスクショで対応するのは、ここまでで何度もやってきた基本パターンと同じです。

【ハンズオン手順】

▼ ブラウザ側でやること（Supabase MCP を調べる）

ブラウザに次のように打つ

Supabase MCP は何ができますか？
具体的な使用例と、導入の手順を初心者向けに教えてください。

ブラウザが回答
自分のプロジェクトで Supabase を使うなら、導入を検討

▼ Code 側でやること（Supabase MCP を入れる、任意）

プロジェクトを Code で開く
次のように依頼

このプロジェクトに Supabase MCP を導入したいです。
.mcp.json を作成・更新してください。
私の Supabase プロジェクト URL：[URL]
API キー：[キー]

Code が .mcp.json を更新
Code を再起動
「データベースの中身を見せて」と依頼して、MCP 経由でデータが取れるか確認

▼ スクショ伴走のチェックポイント

.mcp.json の内容のスクショ
MCP 経由でデータが取れた画面のスクショ

【つまずきポイント】

MCP が認証情報を要求してくる時、API キーは安全に管理。.gitignore に .mcp.json を追加するか、環境変数経由で渡す
MCP を入れた直後は Code の再起動が必要。再起動しないと認識されない
MCP が動かない時は、.mcp.json の記述ミスが多い。ブラウザに「.mcp.json の書き方をチェックして」と頼むと早い

【確認問題】

Supabase MCP を入れる前と入れた後で、データベース操作の流れはどう変わりますか？
MCP の認証情報を安全に管理する方法は何ですか？

【次のレッスンへの橋渡し】

実例が見えました。第9章最後のレッスンで、MCP がうまく動かない時の対処を扱います。

9-6. MCP のデバッグと再接続のコツ

【学習目標】

MCP が動かない時の典型的な原因を知る
再接続や再設定の流れを把握する

【前提知識】

9-5 まで読んでいること

【概念解説】

MCP は便利ですが、ちゃんと動かない場面もあります。「動いていたのに、急に動かなくなった」「設定したのに反応しない」というやつ。

そんな時の典型的な原因と対処を整理しておきます。

典型的な原因

1. Code の再起動忘れ

.mcp.json を更新したのに、Code を再起動していないと反映されません。MCP 設定変更 → 必ず再起動。

2. 認証情報の期限切れ

API キーには有効期限があるものがあります。期限が切れると MCP が認証できなくなる。エラーを見て「Unauthorized」「Token expired」のような言葉があれば、これが疑わしい。

3. .mcp.json の書式エラー

JSON は厳密な書式が必要。カンマの位置、ダブルクォーテーション、括弧の対応など、1文字ミスでもエラーになります。

4. MCP サーバー側の障害

たとえば Notion MCP を使っている時、Notion のサーバーが落ちていると MCP も動かない。これは自分側の問題ではないので、待つしかない。

5. ネットワークの問題

特に企業ネットワーク内では、ファイアウォールが MCP の通信を遮断することがある。

デバッグの流れ

問題が起きた時の進め方：

1. エラーメッセージのスクショを撮る
2. ブラウザに「このエラーが出ました。MCP の○○です」と相談
3. ブラウザが原因の候補を絞ってくれる
4. 候補ごとに対処
   - 再起動で直る？ → 試す
   - 認証情報の問題？ → 再発行
   - 書式エラー？ → JSON をブラウザに校正してもらう
5. それでも直らなければ、MCP を一旦削除して再導入

これも、スクショ伴走モデルがそのまま使えます。

「MCP 自体を諦める」選択肢

MCP がどうしても動かない、または不安定な時は、MCP を使わない選択肢もあります。

9-3 で説明した「MCP は必要なものだけ」原則を思い出してください。あれば便利だけど、なくても作業は進む。「Supabase MCP が使えないから、ブラウザの Supabase 管理画面で SQL を実行する」というのは、退化ではなく現実的な選択肢です。

僕も一時期 Supabase MCP の調子が悪くて、ブラウザ操作に戻していた期間がありました。「MCP は補助具で、なくても自転車は漕げる」という心構えで使うのがちょうど良い。

MCP の再導入手順

「再導入して直したい」時の流れ：

1. .mcp.json から該当 MCP の設定を削除
2. Code を再起動
3. もう一度 Code に「○○ MCP を導入したい」と依頼
4. .mcp.json を再作成
5. Code を再起動
6. 動作確認

【ハンズオン手順】

▼ ブラウザ側でやること（デバッグの予習）

ブラウザに次のように打つ

MCP が動かない時に確認すべきチェックリストを作ってください。
初心者向けに、優先順位の高い順番で。

チェックリストを得る
メモしておく

▼ Code 側でやること（MCP の状態確認）

Code に次のように聞く

今、このプロジェクトで稼働している MCP の一覧と、
それぞれの状態を教えてください。

Code が答える（接続OK、認証エラー、未起動など）
もし問題があれば、ブラウザのチェックリストに沿って対処

▼ スクショ伴走のチェックポイント

MCP の状態一覧のスクショ
もし問題があった場合、デバッグの履歴

【つまずきポイント】

「MCP の自動再接続を期待しない」。Code が固まっていることもあるので、再起動する方が早い
エラーの原因を1つに絞ろうとしない。複数原因が絡んでいることもある。1つずつ消していく
MCP がダメな時は、ブラウザで直接サービスを操作することも視野に。柔軟に

【確認問題】

MCP が動かない時に最初に試すべきことは何ですか？
MCP がうまく動かない時、どんな代替手段がありますか？

【次のレッスンへの橋渡し】

第9章はこれで完了です。サブエージェント、MCP の世界を駆け足で見てきました。

繰り返しになりますが、これらは「使わなくても進める」もの。僕も訪看アプリの後半になってから本格的に使い始めました。必要になった時に戻ってきてください。

次は第10章。いよいよ本格的な Web アプリを実装・公開する章に入ります。僕自身が3週間で実際に作った訪看アプリの v1.x → v2.5 の流れに沿って進めます。

第9章 サブエージェントと MCP

9-1. サブエージェントの概念：コンテキスト分離の意義

9-2. Task ツールと /branch /fork

9-3. MCP の本質を再確認 — どんなときに必要か、どんなときに不要か

9-4. 自分が使うサービスの MCP だけ入れる原則

9-5. 実例：Supabase MCP / GitHub MCP の導入

9-6. MCP のデバッグと再接続のコツ

第9章サブエージェントと MCP

9-2. Task ツールと `/branch` `/fork`