プロトコル原理 · Tools / Resources / Prompts · デバッグとデプロイ · 個人ナレッジベース実践
Python または TypeScript の基礎があるバックエンド／AI 開発者がよく直面する課題は、Claude や GPT は賢いのに、自社 DB・内部 API・ローカルファイルには直接アクセスできない——モデルに外部ツールへ接続する標準化された経路がないことです。Model Context Protocol（MCP）は Anthropic がオープンソース化したプロトコルで、AI Client（Cursor、Claude Desktop）と自作 Server が JSON-RPC で対話します。本記事を読めば、本番投入可能な MCP Server を独立して開発・デプロイできるようになります。プロトコルアーキテクチャ → 環境構築 → Hello World → Tools / Resources / Prompts 三大能力 → HTTP リモート伝送 → デバッグ・テスト → Docker デプロイ → 個人ナレッジベース実践 → 2026 エコシステム展望までをカバーします。
大規模言語モデルがどれほど優れても、学習データにはカットオフがあり、CRM の顧客情報・昨夜のログ・社内 API のリアルタイム状態をいきなり知ることはできません。業界の進化は明確です：Function Calling → Plugins → MCP。前者はベンダー固有形式が多く、モデルを替えるたびに統合層を書き直す必要があります。MCP は「AI がどのツールを発見し、どう呼び出すか」を開放プロトコルで標準化し、一度書けば複数 Client で再利用できます。
課題：Claude / GPT に DB 照会・API 呼び出し・ファイル操作をさせたいが、形式がバラバラです。
シーン：Cursor で Markdown ノートを読ませる、Claude Desktop で GitHub Issue を照会する。
約束：空ディレクトリからデプロイ可能な Server まで、完全なコードとトラブル表付きで案内します。
Anthropic は 2024 年 11 月に MCP を公開し、AI と外部ツールの通信を標準化して、N モデル × M ツール = N×M カスタムアダプタの断片化を解消することを目指しました。プロトコル史観はサイト内のMCP と HTTP 比喩記事も参照してください。
MCP は Client ↔ Server モデルです。Client は AI 側（Claude Desktop、Cursor）、Server はあなたが開発する能力提供者で、JSON-RPC 経由で三大コア能力を公開します：
Tools（ツール）：AI が呼び出す関数——検索、計算、DB クエリ。
Resources（リソース）：AI が読み取るデータ——ファイル、URL、設定ストリーム。
Prompts（プロンプトテンプレート）：事前定義・パラメータ化可能なプロンプト断片。
JSON-RPC 2.0 をベースに、伝送層は stdio（ローカル子プロセス、Cursor / Claude Desktop デフォルト）と HTTP + SSE / Streamable HTTP（リモートサービス）をサポートします。ライフサイクル：初期化ハンドシェイク → 能力協調（initialize）→ リクエスト／レスポンス → クローズ。
| 観点 | MCP | OpenAI Function Calling | LangChain Tools |
|---|---|---|---|
| 標準化 | 開放プロトコル | ベンダー私有 | フレームワーク依存 |
| 伝送 | stdio / HTTP | HTTP | HTTP |
| クロスモデル | 可 | 不可 | 一部 |
| Resources / Prompts | ネイティブ対応 | 非対応 | 非対応 |
| エコシステム | 2026 年 10,000+ Server | 成熟 | 成熟 |
Python（公式 SDK mcp、FastMCP デコレータが簡潔）は初心者向け。TypeScript（@modelcontextprotocol/sdk）はフロントエンド／フルスタック向きです。本記事は Python を主、TS を対照として進めます。
# Python python -m venv .venv && source .venv/bin/activate pip install mcp httpx pydantic # TypeScript（対照） npm init -y && npm install @modelcontextprotocol/sdk
my-mcp-server/ ├── server.py # メインエントリ ├── tools/ # calculator.py, web_search.py ├── resources/ # file_reader.py ├── prompts/ # templates.py ├── tests/test_tools.py ├── pyproject.toml └── README.md
MCP Inspector：npx @modelcontextprotocol/inspector python server.py
Claude Desktop：claude_desktop_config.json を編集して Server を登録します。
Cursor：Settings → MCP → command + args を追加します。
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("my-first-server")
@mcp.tool()
def say_hello(name: str) -> str:
"""指定した相手に挨拶する"""
return f"Hello, {name}! これが最初の MCP ツールです。"
if __name__ == "__main__":
mcp.run()python server.py 実行後、Inspector または Cursor 設定に {"command":"python","args":["/path/to/server.py"]} を入力し、ツール一覧を更新すると say_hello が表示されるはずです。
server.py と仮想環境 Python への絶対パスを使います。
コード変更後はMCP 接続の再起動または Cursor ウィンドウの再オープンが必要です。
会話でツール呼び出しを明示的に依頼し、AI コンテキストに登録されたことを確認します。
関数シグネチャがそのままドキュメントになります。引数型・戻り型・docstring はモデルのツール選択に公開されます。命名は snake_case、動詞始まり（search_web、read_file）が望ましいです。エラーは裸の例外より構造化 JSON を返すと、モデルが自己修正しやすくなります。
from pydantic import BaseModel, Field
class SearchInput(BaseModel):
query: str = Field(description="検索キーワード")
max_results: int = Field(default=5, description="最大返却件数")
language: str = Field(default="ja", description="結果言語")
@mcp.tool()
def web_search(input: SearchInput) -> list[dict]:
"""ネット検索を実行し、関連結果リストを返す"""
...| ツール | 用途 | 注意点 |
|---|---|---|
| 電卓 | 数式評価 | ast.literal_eval や安全パーサを使い、eval は禁止 |
| ファイル読み書き | ローカルファイル操作 | ホワイトリストディレクトリ、パス正規化でディレクトリトラバーサル防止 |
| HTTP リクエスト | 外部 API 呼び出し | タイムアウト、リトライ、レスポンスサイズ上限 |
| DB クエリ | 読み取り専用 SQL | パラメータ化クエリ、DDL 禁止 |
| 時刻ツール | 現在時刻、タイムゾーン変換 | ISO 8601 で返すとモデルが解析しやすい |
@mcp.tool()
async def fetch_url(url: str) -> str:
"""指定 URL の内容を取得する"""
async with httpx.AsyncClient(timeout=30.0) as client:
response = await client.get(url)
return response.textネットワーク／IO 操作にはタイムアウトを設定します（15–30 秒推奨）。
機密操作には権限チェック（API Key、許可パス）を入れます。
{"error": "...", "hint": "..."} を返し、モデルの再試行を助けます。
Resource と Tool の違い：Resource はデータ提供者（主に読み取り）、Tool はアクション実行者です。URI でアドレス指定：file://、http://、custom://。
@mcp.resource("config://app-settings")
def get_app_settings() -> str:
"""アプリ設定を返す"""
return json.dumps({"version": "1.0", "env": "production"})
@mcp.resource("user://{user_id}/profile")
def get_user_profile(user_id: str) -> str:
"""ユーザー ID に基づきプロファイルを返す"""
return json.dumps(db.query_user(user_id))リソース型にはテキスト（text/plain、application/json）、バイナリ（画像、PDF）、ストリーミング（リアルタイム相場）があります。実践ではファイルシステム Server：ディレクトリ一覧、ファイル読み取り、変更購読も可能です。
MCP Prompt は事前定義されたプロンプト断片で、動的パラメータ注入に対応し、チームのプロンプト一貫性と保守性を高めます。
from mcp.types import PromptMessage, TextContent
@mcp.prompt()
def code_review_prompt(language: str, code: str) -> list[PromptMessage]:
"""コードレビュー用プロンプトテンプレート"""
return [PromptMessage(
role="user",
content=TextContent(type="text", text=f"""以下の {language} コードをレビューしてください：
1. 品質と可読性 2. Bug とセキュリティ 3. パフォーマンス最適化
```{language}
{code}
```""")
)]user + assistant マルチターンのテンプレートも定義でき、面接シミュレーションやデバッグ助手などに使えます。Client は prompts/get で埋め込み済みメッセージチェーンを取得します。
| 特性 | stdio | HTTP + SSE |
|---|---|---|
| デプロイ | ローカルプロセス | リモートサーバー |
| レイテンシ | 極低 | ネットワーク依存 |
| マルチクライアント | 非対応 | 対応 |
| シーン | IDE ローカルツール | SaaS / チーム共有 |
mcp = FastMCP("remote-server", transport="streamable-http")
if __name__ == "__main__":
mcp.run(host="0.0.0.0", port=8000)本番環境では Bearer Token / API Key ミドルウェア、CORS ホワイトリスト、レート制限を追加してください。未認証の HTTP MCP をインターネットに直接公開しないでください。
Inspector 起動で tools/list、tools/call をグラフィカルにテストし、JSON-RPC ログの確認やエラーシナリオのシミュレーションができます。
@pytest.mark.asyncio
async def test_calculator_tool():
server_params = StdioServerParameters(command="python", args=["server.py"])
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
result = await session.call_tool("calculate", {"expression": "2 + 2"})
assert result.content[0].text == "4"| エラー | 原因 | 対処 |
|---|---|---|
| ツールが表示されない | 設定パス誤り | config.json の絶対パスを確認 |
| JSON シリアライズ失敗 | 非対応の戻り型 | str または dict に変換 |
| タイムアウト切断 | ツール実行が遅い | 非同期 + タイムアウト制御 |
| 権限拒否 | ファイルパス制限 | 許可ディレクトリ設定 / VNC で TCC 許可 |
FROM python:3.12-slim WORKDIR /app COPY requirements.txt . RUN pip install -r requirements.txt COPY . . EXPOSE 8000 CMD ["python", "server.py"]
Railway / Render：個人プロジェクトのワンクリックデプロイ。
AWS Lambda / Cloud Run：Serverless。コールドスタートと stdio 制限に注意。
自前 VPS + Nginx：リバースプロキシ + TLS + レート制限。
構造化リクエストログ、Prometheus ツール呼び出しメトリクス、Sentry エラーアラート、/health ヘルスチェック。MCP プロトコルバージョンを宣言し、ツールアップグレードは後方互換を維持します。
要件：AI にローカル Markdown ノートの検索、意味検索、作成／更新をさせる。Cursor で「先週 MCP について何をメモした？」と聞けるようにする。
| コンポーネント | 推奨 |
|---|---|
| ベクトル DB | ChromaDB / Qdrant（ローカル） |
| 埋め込みモデル | text-embedding-3-small |
| ファイル監視 | watchfiles 増分インデックス |
index_notes：ディレクトリをスキャンしてベクトルインデックスを構築します。
semantic_search：意味に基づき関連断片を返します。
write_note：Markdown を作成または追記します。
Resource：notes://{path} で単一ノートを直接読み取ります。
効果：AI が semantic_search で断片を取得してから回答を合成するため、ノート全体をコンテキストに詰め込むより Token を節約し、精度も上がります。
mcp-server-filesystem — ファイルシステム操作
mcp-server-github — GitHub リポジトリ
mcp-server-brave-search — ネット検索
mcp-server-postgres — DB クエリ
mcp-server-slack — Slack メッセージ
2026 年には Cursor、Claude Desktop、OpenAI、Google Gemini、Microsoft が MCP 対応を完了または推進しています。MCP Marketplace とエンタープライズ向けセキュリティ標準（OAuth 2.1、監査）も整備が進んでいます。公式ドキュメント：modelcontextprotocol.io；Python SDK：github.com/modelcontextprotocol/python-sdk。
Host（Cursor / Claude Desktop）を選び、2026 版が MCP をネイティブサポートしていることを確認します。
ローカル stdio で Server を開発し、Inspector で tools/list を検証します。
Cursor MCP 設定に登録し、Hello World ツールでスモークテストします。
ブラウザ・キーチェーン・画面収録を扱う Server は macOS グラフィカルセッションで TCC 許可を完了します（SSH のみではクリック不可）。
HTTP モードを Docker デプロイし、認証と監視を追加して本番投入；サイト内のAgent Skill、ブラウザ MCP記事と相互リンクします。
Python（mcp + FastMCP）は最も手早く始められます。TypeScript（@modelcontextprotocol/sdk）は Node スタックのチーム向きです。プロトコル層は同等です。
IDE ローカル開発は stdio を優先します。マルチユーザー共有・SaaS 提供には HTTP + SSE / Streamable HTTP を選び、必ず認証を追加してください。
Tools はアクションを実行します（DB 書き込み、リクエスト送信）。Resources は読み取り専用データ（設定、ファイル内容）を URI テンプレートで提供します。
ブラウザ DevTools MCP、高権限ファイル操作、キーチェーン・画面収録は macOS TCC ダイアログを起こします。SSH のみでは「常に許可」をクリックできず、VNC グラフィカルセッションで Host と同機検収が必要です。
MCP は AI ツール化の標準プロトコルです。Hello World から本番デプロイまでの全工程を習得することは、2026 年の AI エンジニアにとって重要な競争力の一つになります。MCP でどんなツールを開発する予定ですか？実践後に Server 設計を振り返ってみてください。
隠れコストはコードを書くことより実行環境にあります。Windows 主力機 + クラウド Mac で Cursor MCP を混在運用すると、権限ダイアログ、Python 仮想環境、Inspector ログを同一マシンのデスクトップセッションで突合する必要が出ます。Mac mini を自前購入するとスリープ、OS 更新、減価償却を負い、8GB メモリはベクトルインデックス + 複数 Server 同時実行で逼迫しがちです。
時間課金で MCP ツールチェーンを検証し、Cursor と同機のグラフィカル UI で TCC と Inspector 検収を完了したい場合は、VNCMac のリモート Mac レンタルをご利用ください。下の主ボタンから料金プランへ。プラン比較はホームをご覧ください。