プロトコル原理 · FastMCP 実戦 · Tools/Resources/Prompts · HTTP リモートデプロイ · ナレッジベースプロジェクト
AI モデルが「賢くない」と感じるのはなぜでしょうか。外部ツールやリアルタイムデータにアクセスできないからです。Claude や GPT にデータベース検索、API 呼び出し、ファイル読み書きをさせたいなら、MCP（Model Context Protocol） が標準化された答えです。本記事は Python または TypeScript の基礎があるバックエンド / AI 開発者向けです。プロトコル原理から環境構築まで、Tools、Resources、Prompts の登録、MCP Inspector によるデバッグ、HTTP+SSE リモートデプロイ、個人ナレッジベース実戦プロジェクトまでを網羅します。読み終える頃には、本番利用可能な MCP Server を独立して開発・デプロイできるようになります。
大規模言語モデルのツール呼び出し能力は、Function Calling → Plugins → MCP と進化してきました。Anthropic が MCP を設計した核心動機は、AI と外部ツール間の通信をオープンプロトコルで標準化し、「Server を 1 回書けば複数 Client で再利用できる」世界を実現することです。
MCP Client（Claude Desktop、Cursor、カスタムクライアント）と MCP Server（あなたが開発する部分）は JSON-RPC 2.0 で通信します。Server は下位に 3 つの核心能力を接続します。Tools（検索、計算、データベースクエリなど呼び出し可能な関数）、Resources（ファイル、URL、データストリームなど読み取り可能なリソース）、Prompts（事前定義されたプロンプトテンプレート）です。
転送方式は 2 種類あります。stdio（ローカル子プロセス、レイテンシ極小）と HTTP + SSE（リモートサービス、複数クライアント対応）です。ライフサイクルは初期化ハンドシェイク → 能力交渉 → リクエスト / レスポンス → クローズです。
モデルはリアルタイムデータを欠く：学習データのカットオフにより「今日の株価」や「最新チケット状態」に答えられず、外部 API 接続が必須です。
各ベンダーのツール形式が統一されていない：ChatGPT Plugins、OpenAI Function Calling、Claude Tool Use はそれぞれ独立しており、モデル変更のたびに統合層を書き直す必要があります。
IDE 間でツール資産を再利用できない：Cursor、VS Code、Claude Desktop それぞれ異なる接続方式を持ち、チームが蓄積したツールを製品横断で移行できません。
Agent フレームワークへのバインド：LangChain Tools を CrewAI に直接使えず、オーケストレーション資産がフレームワークに固定されます。
N×M の保守コスト：N モデル × M 外部システム = 指数関数的なカスタム統合。MCP はこれを「Server を 1 回書き、どこでも使える」形に集約します。
| 比較軸 | MCP | OpenAI Function Calling | LangChain Tools |
|---|---|---|---|
| 標準化度 | オープンプロトコル標準 | ベンダー独自 | フレームワーク依存 |
| 転送方式 | stdio / HTTP | HTTP | HTTP |
| クロスモデル対応 | あり | なし | 一部 |
| Resources / Prompts | ネイティブ対応 | 非対応 | 非対応 |
| エコシステム | 急成長（10000+ Server） | 成熟 | 成熟 |
この節を読み終えてからコードを書きましょう。MCP はまた 1 つの SDK ではなく、AI ツール化の標準プロトコルです。2026 年の AI エンジニアにとって、これを習得することは核心的な競争力になります。
Python（公式 SDK mcp + FastMCP）は初心者向けです。TypeScript（@modelcontextprotocol/sdk）はフロントエンド / フルスタック向きです。本記事は Python を主軸に、TypeScript を対照説明します。
python -m venv .venv source .venv/bin/activate pip install mcp 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（公式 UI、npx @modelcontextprotocol/inspector）、Claude Desktop ローカル連携（claude_desktop_config.json）、Cursor MCP 設定（Settings → MCP Servers）です。公式ドキュメントは modelcontextprotocol.io をご参照ください。
以下の 6 ステップ Runbook で、30 分以内に AI から呼び出せる最初のツールを動かせます。
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()
仮想環境を作成し mcp をインストール：pip install mcp を実行し、Python ≥ 3.10 であることを確認します。
server.py を作成：@mcp.tool() デコレータで say_hello を登録します。docstring がツール説明になります。
Inspector でデバッグ：npx @modelcontextprotocol/inspector python server.py を実行し、UI で tools/list と tools/call をテストします。
Cursor 設定：MCP 設定に {"command":"python","args":["/path/to/server.py"]} を追加し、再起動後に Agent コンテキストにツールが表示されることを確認します。
Claude Desktop 設定：~/Library/Application Support/Claude/claude_desktop_config.json を編集します。形式は Cursor と同じです。
呼び出しを検証：Cursor で「say_hello で VpsMesh に挨拶して」と入力し、Agent が自動でツールを選択して結果を返すことを確認します。
ヒント：関数シグネチャがそのままドキュメントになります。パラメータ型、戻り値型、docstring は LLM に直接公開され、Agent がツールを正しく選べるかを左右します。
ツールは MCP Server の核心です。命名規則は動詞始まり（search_web、query_database）を推奨します。複雑なパラメータは Pydantic でモデル化します。
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]:
"""Web 検索を実行し、関連結果リストを返す"""
...
eval の直接使用は禁止します。import httpx
@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
エラー処理のベストプラクティス：予期可能な失敗は構造化エラー（error_code と message 付き）を返します。ネットワーク IO には必ずタイムアウトを設定します。書き込み操作の前には権限チェックと監査ログを行います。
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:
user = db.query_user(user_id)
return json.dumps(user)
リソースタイプはテキスト（text/plain、application/json）、バイナリ（画像、PDF）、ストリーミングリアルタイムデータをカバーします。ファイルシステムリソースサーバーでは、ディレクトリ一覧、ファイル読み取り、変更監視（リソース購読）を実装できます。
MCP Prompt は事前定義された断片で、動的パラメータ注入に対応し、一貫性と保守性を高めます。user と assistant を含むマルチターン テンプレートを定義でき、コードレビュー、面接シミュレーション、デバッグアシスタントなどに適用できます。
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} コードをレビューしてください。品質、Bug、パフォーマンスに重点を置いてください。\n```{language}\n{code}\n```"
)
)
]
| 特性 | stdio | HTTP + SSE |
|---|---|---|
| デプロイ方式 | ローカルプロセス | リモートサーバー |
| レイテンシ | 極小 | ネットワーク依存 |
| 複数クライアント | 非対応 | 対応 |
| 適用シーン | ローカルツール | 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 設定、リクエスト頻度制限です。本番環境では tool schema に秘密鍵を書き込まないでください。
Inspector では Tools 呼び出しのテスト、JSON-RPC ログの確認、エラーシナリオのシミュレーションができます。ユニットテストは公式 Client SDK で stdio 子プロセスを起動します。
@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"
| エラー | 原因 | 解決策 |
|---|---|---|
| ツールが AI に表示されない | 設定パス誤り | config.json の command/args 絶対パスを確認 |
| JSON シリアライズ失敗 | 戻り値型が非対応 | str または dict に変換 |
| タイムアウト切断 | ツール実行が遅い | async 化 + timeout 設定 |
| 権限拒否 | ファイルパス制限 | allowlist ディレクトリを設定 |
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 / Google Cloud Run（Serverless）、自前 VPS（Nginx リバースプロキシ）です。監視は構造化ログ、Prometheus メトリクス、Sentry アラート、ヘルスチェック API を使います。バージョン管理では MCP プロトコルバージョンを宣言し、ツール更新時に後方互換を維持します。
要件：AI にローカル Markdown ノートの検索、セマンティック検索、ノート作成・更新をさせること。技術選定：ChromaDB / Qdrant ベクトル DB、text-embedding-3-small 埋め込み、watchfiles によるファイル変更監視。核心実装：ノートインデックスツール、セマンティック検索ツール、ノート書き込みツール、ファイルリソースサービス。効果：Cursor で「先週 MCP について何をメモした？」と聞くと、Agent が検索ツールを呼び出して関連断片を返します。
2026 年の主流 AI クライアント（Cursor、Claude Desktop、VS Code、OpenAI、Gemini）は MCP に対応済みです。MCP Marketplace とエンタープライズセキュリティ標準も急速に発展しています。次のステップ：プロトコル仕様の深掘り、公開 Server のリリース、MCP + Agent 組み合わせの探索、オープンソースエコシステムへの貢献です。参考リソース：Python SDK、TypeScript SDK、MCP Inspector。
tools/list で実行時取得です。ノート PC は MCP POC に適していますが、フタを閉じるとスリープし、macOS ネイティブツールチェーンと長期プロセスデーモンが不足し、7×24 体験が損なわれます。純粋 Linux VPS は HTTP+SSE を実行できますが、Keychain、Xcode など macOS 依存の MCP ツールは載せにくい状態です。複数 MCP Server を「常駐インフラ」として運用し、Agent に週単位でツール呼び出しの複利を蓄積させたい技術チームにとって、VpsMesh Mac Mini M4 クラウドレンタルは uptime、リモート KVM、予測可能な月額を本番級 OpEx としてパッケージ化します。料金は Mac Mini M4 レンタル料金、デプロイは ヘルプセンター、注文は 注文ページ をご参照ください。
Python 公式 SDK mcp と FastMCP の組み合わせが最も早く始められ、バックエンドや AI エンジニアに適しています。TypeScript SDK @modelcontextprotocol/sdk はフロントエンドやフルスタック向きです。プロトコル層は完全互換で、ロジックは対照しながら移植できます。チーム主力が Node フルスタックなら TS、データ / ML 中心なら Python を選ぶのが一般的です。
Tools はアクション実行者です。AI が呼び出すと外部状態を変更したり計算をトリガーします（検索、ファイル書き込み、リクエスト送信）。Resources はデータ提供者です。URI による読み取り専用取得で、config://app-settings や user://{id}/profile などが該当します。覚え方：データを読むなら Resource、アクションを実行するなら Tool です。
HTTP+SSE モードは Railway、Cloud Run、Linux VPS にデプロイできます。MCP ツールチェーンが macOS ネイティブ能力や Keychain に依存する場合、または Cursor Agent と複数 Server をフタを閉じても 7×24 中断なく稼働させたい場合は、Mac Mini M4 月額レンタルがより安心です。1 か月レンタルで tools/call 呼び出し曲線を検証することをお勧めします。料金は Mac Mini M4 レンタル料金、注文は 注文ページ をご参照ください。