MCP入門：基本と実践　(2026/06/23 new)

前回の記事『AIエージェント入門』では、各AIの個性と自律的に思考しタスクを組み立てるAIの可能性について触れました。 思考のループを回すAIエージェントは、私たちの強力なパートナーになってくれます。

しかし、AIを実用的なシステムに組み込もうとした瞬間、私たちはある壁にぶつかります。 PC内のファイルシステムやDB（データベース）、外部デバイスなどにアクセスしようとすると、AIメーカー独自のAPIなどを経由する必要があります。 そのため、複数のAIを利用したシステムを組む場合は、実装やメンテナンスも複雑になってしまいます。

この限界を突破し、AIエージェントに「標準化された頑強な手足」を与えるためのオープン規格が登場しました。 それが、Anthropic社が提唱した「MCP（Model Context Protocol）」です。

この記事では、MCPの基本的な構造を整理し、Pythonを使った実践的なサーバー構築のアイデアを提示します。 AIがローカル環境や物理世界と直接会話するための「システム設計」の第一歩を、シンプルに紐解いていきましょう。

MCP（Model Context Protocol）の世界を理解するための第一歩は、その構造を「2つの柱」に分けて俯瞰することです。

AIモデルとユーザーを仲介するインターフェースの役割を担います。

具体例としては、ClaudeやCodex、Antigravity、Cursorなど、あるいは独自に開発するアプリケーションなどがこれに該当します。 CLI、GUI（デスクトップアプリ、WEBアプリ）、IDE（VS Codeプラグイン）など複数のUIを提供している場合も多いです。

言わば、ユーザーからの入力を受け取りどのMCPサーバーを呼び出すべきかを判断する「司令塔」です。
基本的にユーザーが開発することは少ないモジュールになります。

ローカル環境や外部API、各種デバイスと直接つながり、AIに具体的な「能力」を提供するプログラムです。

AIモデル自身はローカルPCのファイルを直接読み書きしたり、サウンドデバイスを叩いたりすることはできません。 その「できないこと」を代わりに実行し、結果をクライアントに返すのがサーバーの役割です。
ユーザーが開発するほとんどが、このMCPサーバーモジュールになります。

この2つが標準化された規格（MCP）で通信することにより、以下のようにシンプルな疎結合が実現します。

• 一度MCPサーバーを書けば、クライアント（ClaudeでもCodexでも・・・）を切り替えてもそのまま同じ機能が動く。
• クライアント側はサーバーの内部実装（PythonなのかC#なのか等）を気にする必要がない。

MCPサーバーを実際に開発する際、AIに対してどのような形で機能やコンテキスト（文脈）を公開するか。 そのアプローチとして、サーバー側には「3つの柱」となる要素が定義されています。

開発時は、これらをJSONベースのメタデータ（スキーマ）としてクライアントへ通知することになりますが、 PythonなどのSDK（FastMCP）を使う場合は通常のプログラムコードとして直感的に定義できます。

AIが自発的に呼び出して「実行」できる関数（機能）や操作です。

• 役割: PCのシステム状態を取得する、ローカルで音声を再生する、ファイルを書き換えるといった「動的なアクション」をAIに許可する。
• 定義フォーマット: サーバー内部では使い慣れたプログラミング言語（PythonやTypeScriptなど）の関数として記述する。クライアントへは、関数名や引数の型、説明文がJSON Schemaの形式に自動変換されてエクスポートされる。
• 特徴: AIはツールの説明文（ドキュメント文字列など）を読み、必要に応じて引数を自分で推論して実行を要求する。

AIに「コンテキスト（文脈）」として読み込ませるためのデータです。

• 役割: ローカルのテキストファイル、データベースのログ、楽譜データなどを、AIがいつでも参照できる「静的な情報源」として公開する。
• 定義フォーマット: 定義フォーマット: テキスト（.txt）、マークダウン（.md）、JSON（.json）などの、AIがパースしやすいテキストベースのファイルフォーマットが基本となる。 これらを、サーバー側で独自に定義したURIスキーム（例：music://... や file://...）と紐付けて管理する。
• 特徴: AIは必要に応じて指定されたURIの中身（テキストデータ）を読み取り、思考の材料にする。

特定のタスクに最適化された「定型文（テンプレート）」をAIに提供する仕組みです。

• 役割: よく使う役割定義や、複雑なタスクの指示書をサーバー側にあらかじめ仕込んでおき、クライアント側から簡単に呼び出せるようにする。
• 定義フォーマット: JSON形式の配列やオブジェクトとしてテンプレートを管理する。プロンプト内にユーザーが動的に値を注入できるよう、変数（引数）を埋め込んだ文字列として定義することが多い。
• 特徴: MCPサーバーの3つの柱は、動的なアクション（Tools）、静的なデータ（Resources）、定型テンプレート（Prompts）で構成されている。 これらは最終的にJSONベースの共通規格としてやり取りされるため、開発言語（Python、C#、TypeScriptなど）を選ばずに実装できる。

概念を理解したところで、実際に動くMCPサーバーを構築して動作させてみましょう。 今回はPythonのライブラリであり、最小限の記述でMCPサーバーを立ち上げられる「FastMCP」を使用します。

筆者が実機検証用に作成したコード（mj_mcp_server.py）の設計思想をベースに、MCPの「Resource」と「Tool」がどのように実装されるかを見ていきます。

このサーバーは、AIにマイケル・ジャクソンの名曲『Beat It』の楽譜データ（イントロ）をResourceとして提供し、PCのシステム診断（CPU、メモリ使用率）を行います。
さらに診断の前に、ローカルのサウンドデバイスからその１フレーズ（４小節）を演奏する（Tool）という仕様です。

import math
import struct
import winsound
import time
import psutil
import sys
from mcp.server.fastmcp import FastMCP
from pathlib import Path

# MCPサーバーの初期化
mcp = FastMCP("Michael-Jackson-Monitor")

# 楽譜データのファイルパスと独自のURIスキーム定義
BASE_DIR = Path(__file__).resolve().parent
SCORE_FILE = BASE_DIR / "beat_it.txt"
RIFF_URI = "music://michael-jackson/beat-it-riff"

# --- 1. Resources（リソース）の定義 ---
@mcp.resource(RIFF_URI, name="Beat It Intro Riff File")
def get_beat_it_riff() -> str:
    """ローカルファイルからマイケル・ジャクソン『Beat It』の楽譜データを読み込んでAIに提供します。"""
    if not SCORE_FILE.exists():
        return f"Error: {SCORE_FILE} が見つかりません。"
    with SCORE_FILE.open("r", encoding="utf-8") as f:
        return f.read()

# --- 2. Tools（ツール）の定義 ---
@mcp.tool()
def diagnose_and_alert() -> str:
    """PCのシステム状態（CPU・メモリ）を診断し、完了後にローカルスピーカーでアラート（Beat It）を演奏します。"""
    cpu_usage = psutil.cpu_percent(interval=1)
    memory = psutil.virtual_memory()
    
    # 診断完了のアラートとしてローカルで演奏を実行
    play_music_from_resource()
    
    report = (
        f"【診断結果】\n"
        f"・CPU使用率: {cpu_usage}%\n"
        f"・メモリ使用率: {memory.percent}%"
    )
    return report

                                

実装のポイント

1. デコレータによる直感的な定義
@mcp.resource() や @mcp.tool() を関数に付与するだけで、FastMCPが自動的にMCP規格に準拠したスキーマ（JSON）を生成し、クライアントへエクスポートする。開発者が手動で複雑な定義書を書く必要はない。

2. AIへの説明の埋め込み（Docstringの重要性）
関数の内部に記述された三連引用符（"""）による説明文（Docstring）は、そのままAIに対する「この機能（データ）は何か」という説明書（指示書）として送信される。 AIはこの説明文を読み、いつ、どのようにツールやリソースを使うべきかを自律的に判断する。

3. リソースURI（URL）の定義形式と意味
MCPサーバーが提供するリソースは、WebサイトのURLと同じように一意の識別子（URI）で管理される。
今回のコードで定義している music://michael-jackson/beat-it-riff という形式には、AIに文脈を構造的に理解させるための重要な意味が含まれている。

• music（スキーム名）: このデータが「音楽（楽譜）関連のリソース」であることを示す。Webでいう http や https に相当し、AIに対してデータのジャンルや大枠の文脈を明示する役割を持つ。
• michael-jackson（ホスト名/ネームスペース）: データの所有者や、大分類のカテゴリを示す。これにより、他のアーティストのデータと衝突（衝突）することを防ぎ、AIは「マイケル・ジャクソンに関するデータ領域である」と識別できる。
• beat-it-riff（パス名/リソース識別子）: 具体的な特定のデータを示す。今回の場合は『Beat It』のイントロのリフ（楽譜データ）そのものを指し、AIはこの最下層のパスを指定してピンポイントに中身を読み出す。

4. 低レイヤーへのアクセス（Wave演奏エンジン）
今回の実装では、単なる標準の電子音（単調なBeep音）を鳴らすのではなく、struct.pack を用いてRIFF/WAVEヘッダをバイナリレベルで組み立て、末尾にエンベロープ（フェードアウト）処理を施したWAVEバイナリを winsound.PlaySound でメモリから直接再生している。
AIからの高レベルな要求（Tool実行）が、ローカルPCの最も低レイヤーな物理デバイス（スピーカー）を直接駆動させるという設計である。
面白いことに、単調なBeep音がより音楽的に聴こえてくるようになる。

MCPは統一されたオープン規格ですが、それを読み込む側のMCPクライアント（デスクトップアプリ）は、それぞれ独自の設計思想とユーザーインターフェースを持っています。
今回は、筆者が実際に自作のMCPサーバー（mj_mcp_server.py）を接続し、動作を検証した3つの主要なデスクトップアプリ（Codex、Claude、Antigravity）における「登録方法」「登録時の注意点」「使用方法」の差異と対策などを説明します。

1. 共通の登録方法と注意事項
全てのMCPクライアントで共通する注意点です。
MCPクライアント毎の詳細については、各デスクトップアプリの項目を参照して下さい。

📌 注意事項

• パスの完全修飾（絶対パス指定）：
  コマンドラインから直接動く python や uv コマンドであっても、実行環境（仮想環境など）の絶対パス（例: C:\Users\user\venv\Scripts\python.exe）で記述しなければ認識されないケースが多い。 相対パスや省略形での記述はエラーの原因となる。
  これは、ソースファイル、設定ファイルとも共通した注意点である。（特にClaudeとAntigravityは要注意）
• stderrへ出力：
  MCPは、プロセス間通信時に標準入出力（stdin, stdout）を経由してメッセージの送受信を行う場合がある。 そのためメッセージの破壊を防止するためにも、printメソッド等を使用して標準入出力を使用する場合はstderrに出力する。 （特にClaudeとAntigravityは要注意）
• MCPサーバーの再起動：
  再起動する場合、アプリ右上の「×」で終了しない。
  タスクバーのアイコンを右クリックし、「タスクを終了する」で終了する。 これは、設定ファイルの変更が反映されないケースがみられたためである。
  推測となるが、終了時に呼ばれるイベント処理が異なるため、キャッシュをクリアするタイミングが異なっている可能が考えられる。 （特にClaudeとAntigravityは要注意）

📌 MCPサーバーの登録方法

• アプリの設定ファイルをテキストエディタで開く。
• mcpServers セクションなどに、サーバー名、起動コマンド、および引数をJSON形式または専用形式で追記する。
• MCPクライアント（デスクトップアプリ）を再起動する。
• 再起動後、MCPサーバーが正常に登録されていることを確認する。

📌 使用方法

• ユーザーがプロンプトで「MCPでPCの健康状態をチェックして」のように指示を出す。
• 実行の承認を求められた場合は、承認する。

2. Claude (Anthropic Claude Desktop App)

📌 設定ファイル
MCPサーバー登録情報は、claude_desktop_config.jsonに追記する。
Claude desktopインストール時に次の場所に自動生成される。

C:\Users\user\AppData\Roaming\Claude\claude_desktop_config.json


上記以外のパスに設定ファイルが生成されている場合は、アプリの再インストールを推奨する。

"coworkUserFilesPath": "C:\\Users\\user\\Claude", → この後に追化する。

"coworkUserFilesPath": "C:\\Users\\user\\Claude",
  "mcpServers": {
    "michael-jackson-monitor": {
      "command": "python",
      "args": ["D:\\AiBeep\\mcp_server\\mj_mcp_server.py"]
   }

📌 MCPサーバーの登録状態確認
設定 > 開発者 > ロカールMCPサーバー

3. Codex (OpenAI Codex Desktop App)

📌 設定ファイル
MCPサーバー登録情報は、config.tomlに追記する。
Codex desktopインストール時に次の場所に自動生成される。

C:\Users\user\.codex\config.toml

[mcp_servers.mj]
command = "C:\\Users\\user\\AppData\\Local\\Python\\bin\\python.exe"
args = ["D:\\AiBeep\\mcp_server\\mj_mcp_server.py"]
cwd = "D:\\AiBeep\\mcp_server"
enabled = true
startup_timeout_sec = 20
tool_timeout_sec = 60

📌 MCPサーバーの登録状態確認
設定 > MCPサーバー > サーバー

4. Antigravity 2.0 (Google Antigravity Desktop App)

📌 設定ファイル
MCPサーバー登録情報は、mcp_config.jsonに追記する。
Antigravity desktopインストール時に次の場所に自動生成される。

C:\Users\user\.gemini\config\mcp_config.json

{
  "mcpServers": {
    "filesystem": {
      "command": "python",
      "args": [
        "D:\\AiBeep\\mcp_server\\mj_mcp_server.py"
      ]
    }
  }
}

📌 MCPサーバーの登録状態確認
Settings > Customizations > Installed MCP Servers

💻 サンプルプログラムは、GitHubからZIPファイルでダウンロードできます。
サンプルプログラム

Model Context Protocol（MCP）の登場によって、AIのカスタマイズやエージェント開発のパラダイムは完全に変わりました。 かつてのような「プロンプトの微調整」や「面倒な工夫」でAIをコントロールする次元は、もう終わりを迎えています。

これからのAI開発は、AIという予測不可能な頭脳に対して、どのような「Tools（手足）」や「Resources（コンテキスト）」を繋ぎ、 それらを独自のアプリケーションの中でいかに堅牢に「状態管理」していくかという、純粋なシステム設計（アーキテクチャ）の時代へとシフトしました。 今回構築したPythonによるFastMCPサーバー（『Beat It』演奏サーバー）は、その広大な世界の入り口に過ぎません。

このWebサイトでは今後さらにこの思想を深掘りしながら次回以降の記事にて、 「MCPクライアントにAvalonia(C#) 、MCPサーバーに Raspberry Pi を用いたリアルタイム音声ストリーミングおよび物理センサー連携」 という実機開発の実験現場をお届けしていく予定です。

AIに現実世界の干渉力を与える魅力的な設計の世界へ、あなたも一歩踏み出してみませんか。