CodeCraft Lab

MCPの基礎 ── プロトコルを理解する

MCPのクライアント/サーバーアーキテクチャ、通信モデル、3つの機能カテゴリを理解し、最小構成のMCPサーバーを実際に動かします

応用14分で読了
MCPアーキテクチャstdioHTTP

このレッスンで学ぶこと

  • MCPのクライアント/サーバーアーキテクチャと、Claude Codeがその中でどう振る舞うか
  • stdio（ローカル）とHTTP（リモート）という2つの通信モデルの違いと使い分けの判断軸
  • Tools・Resources・Promptsという3つの機能カテゴリの役割の違い
  • 最小構成のMCPサーバーを実際に1つ接続し、動作を確認する

前提条件

  • 実践コースを修了していること、またはClaude Codeを日常的に使っていること
  • MCP・APIの概念をある程度理解していること（本レッスンでは前提知識として深くは扱いません）
  • ターミナルでコマンドを実行できる環境（Node.js 18以降を推奨）

このレッスンは「MCPを初めて聞いた」人向けの概念解説ではなく、実装・運用に踏み込む前に押さえておくべきプロトコルの構造を扱います。MCPという言葉自体の意味や歴史的な背景は最小限に留め、すぐに手を動かせる状態を目指します。より深いアーキテクチャ解説（セキュリティ設計、自作の設計思想など）はMCP完全ガイドに譲り、本コースでは「実際にどう設定し、何が起きているか」を中心に進めます。

MCPは「ツールを呼び出すための共通規格」

Claude Codeは単体でもファイル編集やコマンド実行ができますが、外部のサービス（GitHub、データベース、社内システムなど）を操作するには、それぞれのAPI仕様を知っている必要があります。MCP（Model Context Protocol）は、この「外部サービスとのやり取り」を統一されたインターフェースにまとめるためのオープンプロトコルです。

ポイントは、MCPに対応してさえいれば、Claude Codeはサービスごとの個別仕様を意識せずに済むという点です。これから扱う「クライアント/サーバーアーキテクチャ」は、この統一インターフェースを実現するための骨格にあたります。

このレッスンの立ち位置

入門・実践コースではMCPサーバーを「導入して使う」ところまでしか扱っていません。応用コースでは、設定の裏側で何が起きているかを理解した上で、構築・開発（Lesson 2, 3）に進みます。

クライアント/サーバーアーキテクチャ

MCPは「クライアント」と「サーバー」という2つの役割で構成されます。

graph LR
    subgraph Client["MCPクライアント"]
        CC["Claude Codeのエージェントループ"]
    end
 
    subgraph Server["MCPサーバー"]
        T["Tools"]
        R["Resources"]
        P["Prompts"]
    end
 
    subgraph Backend["バックエンドの実体"]
        E["外部API / DB / ファイルシステム"]
    end
 
    CC <-->|"JSON-RPCメッセージ"| Server
    Server --> E
 
    style CC fill:#e8f4fd,stroke:#1a73e8
    style Server fill:#fff3e0,stroke:#e65100

Claude Code（クライアント）は、起動時または接続時にMCPサーバーへ「どんなツール・リソース・プロンプトが使えるか」を問い合わせます。サーバー側はその一覧（名前・説明・入出力スキーマ）を返し、Claude Codeは会話の中で必要に応じてそれらを呼び出します。

この設計のメリットは、Claude Code自身が個々のサービスの実装詳細を知らなくてよいことです。GitHub MCPサーバーの裏側がどれだけ複雑なAPI仕様を持っていても、Claude Codeから見えるのは「Issueを作成する」「PRをレビューする」といった、意味のまとまった単位のツール呼び出しだけです。

クライアントはClaude Codeだけではない

MCPはClaude Code専用の仕組みではありません。仕様に対応してさえいれば、別のAIツールも同じMCPサーバーをクライアントとして利用できます。一度作ったMCPサーバーは、Claude Code以外のエコシステムでも再利用できる前提で設計するとよいでしょう。

通信モデル: stdioとHTTPの使い分け

MCPサーバーへの接続方式は、大きく分けてstdio（標準入出力）とHTTPの2系統があります（このほかSSE・WebSocketもありますが、SSEは非推奨でWebSocketは双方向プッシュ向けの特殊用途のため、本レッスンではstdioとHTTPを軸に整理します）。

観点stdioHTTP
実行場所Claude Codeの子プロセスとしてローカルで起動クラウド上にホストされたサーバーにリクエスト
典型的な用途ローカルファイル操作、ブラウザ自動化、ローカルDB接続SaaS連携（GitHub、Slack、Sentry等）
認証環境変数でAPIキー・トークンを渡すことが多いOAuth 2.0またはBearerトークンによるヘッダー認証
チーム共有各自の環境にセットアップが必要URLを共有すれば全員が同じサーバーに接続
再接続プロセスが落ちると自動再接続されない切断時に指数バックオフで自動再接続（最大5回）

判断軸はシンプルです。ローカルマシンのリソース（ファイル・ブラウザ・ローカルDB）に触る必要があるならstdio、クラウド上のサービスに繋ぐならHTTPと考えると、ほとんどのケースで迷いません。

# stdio: ローカルプロセスとして起動
claude mcp add playwright -- npx -y @playwright/mcp@latest
 
# HTTP: リモートサーバーのURLに接続
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_TOKEN"
迷ったらHTTPを優先する

公式ドキュメントでも、リモートMCPサーバーに接続する場合はHTTPが推奨トランスポートとされています。SSEは非推奨化が進んでおり、新規にサーバーを選定する際はHTTP対応の有無を確認しましょう。

Tools・Resources・Promptsという3つの機能カテゴリ

MCPサーバーがクライアントに提供できる機能は、仕様上3種類に分類されています。

カテゴリ役割呼び出され方具体例
ToolsClaude Codeが呼び出して実行できる関数会話の中で自動的に呼び出されるIssueの作成、SQLクエリの実行
Resources@メンションで参照できるデータユーザーが明示的に参照する@github:issue://123
Promptsスラッシュコマンドとして呼び出せる定型処理/mcp__server__prompt名 で実行/mcp__github__pr_review 456

実務で最も多用されるのはToolsですが、3つの違いを理解しておくと、新しいMCPサーバーに出会ったときに「何ができるサーバーか」を素早く把握できます。

# Resourcesの参照例（@メンション）
@github:issue://123 の内容を分析して、修正方針を提案してください
 
# Promptsの実行例（スラッシュコマンド形式）
/mcp__jira__create_issue "ログインフローのバグ" high
Resourcesは複数同時に参照できる

1つのプロンプトの中で複数のResourcesを組み合わせることもできます。たとえば @postgres:schema://users と @docs:file://database/user-model を比較してください のように、構造化されたデータ同士を突き合わせる指示が可能です。

実践: 最小構成のMCPサーバーを接続する

ここまでの概念を踏まえて、実際に1つMCPサーバーを接続してみましょう。今回は認証不要で試せる、Claude Code公式ドキュメントの検索サーバー（HTTP接続）を例にします。

サーバーを追加する

ターミナル（claude セッションの外）で以下を実行します。

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

--transport http がHTTP接続であることを示し、claude-code-docs は自分で付けた任意のサーバー名です。これがツール呼び出しのラベルや、後述のclaude mcp removeで使う識別子になります。

接続ステータスを確認する

サーバーが正しく登録されたかを確認します。

claude mcp list

✓ Connected と表示されれば成功です。✗ Failed to connect の場合は、ネットワーク接続やURLのタイプミスを疑いましょう。

セッション内でツールを使ってみる

Claude Codeを起動し、追加したサーバーを使うよう明示的に指示します。

claude
claude-code-docsサーバーを使って、MCP_TIMEOUTが何をする環境変数か調べてください

初回呼び出し時はツール使用の許可を求められるので、内容を確認して承認します。出力にサーバー名がラベルとして表示されていれば、MCPサーバー経由で取得した情報だとわかります。

不要になったら削除する

実験用に追加したサーバーは、使い終わったら削除しておきましょう。接続中のサーバーはツール名やサーバー説明が常にコンテキストウィンドウの一部を占有するため、使わないサーバーを残すのは無駄なコスト要因になります。

claude mcp remove claude-code-docs
プロジェクトスコープのサーバーは承認が必要

リポジトリに含まれる.mcp.jsonからプロジェクトスコープのMCPサーバーを読み込む場合、Claude Codeは初回利用時に明示的な承認を求めます。これは、リポジトリをクローンしただけで意図しないプロセスが自動起動することを防ぐための安全策です。スコープの種類と設定方法はLesson 2で詳しく扱います。

よくある質問

Q. stdioサーバーとHTTPサーバーを同時に使うことはできますか?

できます。.mcp.jsonに両方のタイプを混在させて定義でき、Claude Codeのセッションからは透過的に両方のツールを呼び出せます。具体的な構成パターンはLesson 2で扱います。

Q. Toolsの数が増えるとコンテキストウィンドウを圧迫しませんか?

Claude Codeにはツール検索の仕組みが備わっており、セッション開始時にはツール名とサーバーの説明文だけが読み込まれ、実際に使うツールのスキーマはオンデマンドで読み込まれます。そのため、接続するサーバーの数そのものよりも、各ツールの説明文がどれだけ的確に書かれているかの方が実用上は重要です。

まとめ

  • MCPは「クライアント/サーバー」という単純なモデルの上に成り立つ、外部ツール連携の標準プロトコル
  • 通信モデルはstdio（ローカルプロセス）とHTTP（リモート）の2系統が中心。ローカルリソースに触るかクラウドサービスに繋ぐかで使い分ける
  • サーバーが提供する機能はTools（実行）・Resources（参照データ）・Prompts（定型コマンド）の3カテゴリに分類される
  • claude mcp add → claude mcp list → 実際に呼び出す、という最小フローを押さえておけば、新しいMCPサーバーにもすぐ対応できる

次のステップ

次のLesson 2では、ローカル・リモート双方のMCPサーバーを本格的に構築する手順、認証設定、環境変数・シークレット管理のベストプラクティス、そして複数サーバーを.mcp.jsonで管理するパターンを扱います。今回接続した最小構成を土台に、実務で使えるレベルの構成へと発展させていきましょう。