MCP Server ゼロから開発：2026 手順付き AI ツール呼び出し構築

大規模言語モデルがどれほど賢くても、「手足」がなければデータベースを検索したり、API を呼び出したり、ローカルノートを読むことはできません。Model Context Protocol（MCP）は JSON-RPC により AI クライアントと外部機能を標準化して接続します——2026 年時点でエコシステムは 13,000 超の Server に達し、OpenAI、Google、Microsoft が全面サポートしています。課題：Function Calling は各社独自実装で、モデルを変えるたびに作り直しが必要です。結論：本記事を読めば、MCP Server を独立して開発・デバッグ・本番デプロイできるようになります。構成：プロトコル原理 → 環境構築 → Hello World → Tools/Resources/Prompts → HTTP リモート → デバッグ・テスト → Docker デプロイ → 個人ナレッジベース実践 → エコシステム展望。

1. MCP とは？プロトコルを理解してからコードを書く

1.1 MCP の誕生背景

ツール呼び出し能力は三代の進化を経ました：Function Calling（OpenAI 独自形式）→ Plugins（ChatGPT プラグインエコシステム、式微）→ MCP（オープン標準）。Anthropic は 2024 年 11 月に MCP をオープンソース化しました。核心動機は、AI クライアントを変えるたびにツール統合を書き直す N×M 爆発を解消することです。MCP はAI と外部ツールの通信プロトコルを標準化します——Server を一度書けば、Cursor、Claude Desktop、VS Code ですべて使えます。2026 年にはガバナンスが Linux Foundation 傘下の AAIF に移管されました。

1.2 MCP プロトコルアーキテクチャ概要

┌────────────────────┐         ┌─────────────────────┐
│   MCP Client       │ ◄─────► │   MCP Server        │
│  (Claude / Cursor) │  JSON   │  (開発する部分)      │
│                    │  -RPC   │                     │
└────────────────────┘         └─────────────────────┘
                                        │
                          ┌─────────────┼─────────────┐
                          ▼             ▼             ▼
                       Tools       Resources      Prompts
                    (ツール呼出)   (リソース読取)  (プロンプト)

Client：AI モデル側のホスト（Claude Desktop、Cursor、カスタム Agent）。Server：開発する能力提供者。三大核心機能：Tools は AI が呼び出せる関数（検索、計算、SQL）；Resources は AI が読み取れるデータ（ファイル、設定、URL）；Prompts はパラメータ注入をサポートする事前定義プロンプトテンプレートです。

1.3 MCP 通信メカニズム

基盤は JSON-RPC 2.0 です。転送方式：stdio（ローカル子プロセス、ネットワーク設定不要）と Streamable HTTP（2025-06-18 仕様で旧 HTTP+SSE を置換、リモート/マルチクライアント向け）。ライフサイクル：初期化ハンドシェイク → 能力協議（tools/list）→ リクエスト/レスポンス → クローズ。⚠️ ローカル stdio モードではstdout への非プロトコルログ出力を禁止してください。JSON-RPC 解析が失敗します。

1.4 MCP vs 他ソリューション比較

比較軸	MCP	OpenAI Function Calling	LangChain Tools
標準化度	オープンプロトコル標準	ベンダー独自	フレームワーク依存
転送方式	stdio / Streamable HTTP	HTTP	HTTP
クロスモデル	対応	非対応	一部
リソース/プロンプト	ネイティブ対応	非対応	非対応
エコシステム	13,000+ Server（2026）	成熟	成熟

2. 開発環境の準備

2.1 開発言語の選択

Python（初心者向け）：公式 SDK mcp + FastMCP デコレータで簡潔に始められます。TypeScript（フロント/フルスタック向け）：@modelcontextprotocol/sdk + Zod バリデーション、npm ダウンロード数は 150M 超。本記事は Python を主軸に、TypeScript は対照として説明します。

2.2 環境構築

# Python 環境
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install "mcp[cli]"

# TypeScript 環境（対照）
npm init -y
npm install @modelcontextprotocol/sdk zod

2.3 プロジェクト構造設計

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

2.4 デバッグツールのインストール

1）MCP Inspector：npx @modelcontextprotocol/inspector python server.py、ブラウザ UI は localhost:6274 で Tools/Resources/Prompts をデバッグできます。2）Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json を編集します。3）Cursor：Settings → MCP → mcpServers 設定を追加します。詳細は当サイトの MCP プロトコル深堀解説をご参照ください。

3. 最初の MCP Server：Hello World

3.1 最もシンプルな MCP Server

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()

3.2 実行と検証

python server.py
# または MCP Inspector でデバッグ
npx @modelcontextprotocol/inspector python server.py

3.3 Cursor / Claude Desktop への接続

// claude_desktop_config.json または Cursor MCP 設定
{
  "mcpServers": {
    "my-first-server": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

⚠️ Python インタプリタとスクリプトには絶対パスを使用してください。クライアント再起動後、会話中に say_hello ツールがコンテキストに表示されるはずです。

4. Tools：AI から呼び出せるツールの開発

4.1 ツールの基本構造

関数シグネチャがドキュメントになります。パラメータ型、戻り値型、docstring は SDK により JSON Schema に自動変換され、LLM が理解します。命名規則：小文字+アンダースコア、意味が明確（web_search は ws より優れています）。エラー処理：未捕捉例外を投げるより構造化エラー文字列を返す方が、Server 全体のクラッシュを防げます。

4.2 入力パラメータ型のサポート

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]:
    """ネット検索を実行し、関連結果リストを返す"""
  # 検索ロジックを実装
    return [{"title": "サンプル", "url": "https://example.com"}]

4.3 実践例：5 つの実用ツール

ツール	用途	実装の要点
計算機	数式評価	`eval` はサンドボックスまたは `ast` 安全解析が必要
ファイル読書	ローカルファイルの読み書き	許可ディレクトリを制限、パストラバーサル防止
HTTP リクエスト	外部 API 呼び出し	`httpx` + 30s タイムアウト
DB クエリ	読み取り専用 SQL 実行	パラメータ化クエリ、DDL 禁止
時刻ツール	現在時刻/タイムゾーン変換	`zoneinfo` 標準ライブラリ

4.4 非同期ツール開発

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[:10000]  # トークン爆発防止のため切り詰め

4.5 ツールエラー処理のベストプラクティス

1）構造化エラー：{"error": "...", "code": "TIMEOUT"} 文字列を返します。2）タイムアウト：すべての I/O 操作に 30s 上限を設定します。3）権限検証：Tool 層でディレクトリ/API をホワイトリスト化し、LLM の「自覚」に依存しないでください。

5. Resources：AI に動的コンテンツを読ませる

5.1 Resource と Tool の違い

Resource はデータ提供者（主に読み取り専用）、Tool はアクション実行者です。URI アドレッシング：file://、http://、custom:// カスタム scheme。

5.2 静的リソース vs 動的リソース

import json

@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({"user_id": user_id, "name": "Demo"})

5.3 リソースタイプ

テキストリソース（text/plain、application/json）、バイナリリソース（画像/PDF、base64 返却）、ストリーミングリソース（リアルタイム相場、Streamable HTTP 必須）。

5.4 実践：ファイルシステムリソースサーバー

ディレクトリ一覧、ファイル内容読み取り、ファイル変更の購読（resources/subscribe）が可能です。本番環境ではルートディレクトリを必ず制限し、公式 mcp-server-filesystem の allowlist 設計を参考にしてください。

6. Prompts：再利用可能なプロンプトテンプレートの定義

6.1 MCP Prompt とは？

事前定義プロンプト断片を AI が直接再利用できます。動的パラメータ注入をサポートし、チームの Prompt 一貫性と保守性を向上させます。Cursor Agent Skills と補完関係：MCP Prompt = プロトコル層テンプレート、Skill = 操作マニュアルです。

6.2 プロンプトテンプレートの作成

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}
```"""
            )
        )
    ]

6.3 マルチターン会話プロンプト

user と assistant を含むマルチターンテンプレートを定義できます。シナリオ：面接シミュレーション（assistant が面接官役）、コードデバッグアシスタント（assistant が先に確認質問）。

7. 応用：HTTP 転送モード（リモート MCP Server）

7.1 stdio vs Streamable HTTP

特性	stdio	Streamable HTTP
デプロイ方式	ローカルプロセス	リモートサーバー
レイテンシ	極低（<5ms）	ネットワーク依存（50–200ms）
マルチクライアント	非対応	対応
適用シーン	ローカルツール、IDE プラグイン	SaaS/チーム共有/7×24

⚠️ 旧 HTTP+SSE は 2025-06-18 仕様で廃止されました。新規プロジェクトは Streamable HTTP を使用してください。

7.2 HTTP 転送の実装

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("remote-server")

if __name__ == "__main__":
    mcp.run(transport="streamable-http", host="127.0.0.1", port=8000)

本番デプロイには uvicorn/gunicorn リバースプロキシが使えます。Serverless（Cloud Run/Lambda）では stateless_http=True が必要です。メモリ session はコールドスタート時に失われます。

7.3 認証とセキュリティ

Bearer Token 認証、API Key ミドルウェア、CORS ホワイトリスト、リクエストレート制限（推奨 100 req/min/IP）。ローカル開発は 127.0.0.1 にバインドし、0.0.0.0 への無認証公開は禁止してください。2026 年には 30+ の MCP 関連 CVE が公開され、CVSS 9.6 の mcp-remote RCE も含まれます。

8. デバッグとテスト

8.1 MCP Inspector によるデバッグ

起動後、UI で Tools 一覧 → 手動呼び出し → JSON-RPC 生メッセージ確認 → タイムアウト/エラーシナリオのシミュレーションができます。LLM に直接接続してデバッグするより 10× 効率的です。

8.2 ユニットテストの作成

import pytest
from mcp.client.session import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client

@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 "4" in result.content[0].text

8.3 よくあるエラーのトラブルシューティング

エラー	原因	解決策
ツールが AI に表示されない	設定パス誤り	config.json の絶対パスを確認
JSON シリアライズ失敗	非対応の戻り値型	str または dict に変換
タイムアウト切断	ツール実行が遅い	非同期 + 30s タイムアウト
権限拒否	ファイルパス制限	allowlist ディレクトリを設定

9. 本番デプロイ

9.1 Docker コンテナ化

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["python", "server.py"]

9.2 クラウドサービスへのデプロイ

Railway / Render：ワンクリックデプロイ、個人プロジェクト向け（月額約 $5–20）。AWS Lambda / Google Cloud Run：Serverless、呼び出し課金。自前 VPS：Nginx リバースプロキシ + Let's Encrypt + systemd/launchd 常駐。

9.3 監視と可観測性

構造化ログ（JSON Lines）、Prometheus メトリクス（mcp_tool_calls_total）、Sentry エラーアラート、/health ヘルスチェックエンドポイント。P99 レイテンシアラート閾値は 5s を推奨します。

9.4 バージョン管理と互換性

ハンドシェイク時に MCP プロトコルバージョンを宣言します。ツールアップグレードは後方互換を維持（必須パラメータ変更ではなくオプション追加）。capabilities 協議で Client が存在しない Tool を呼ばないようにします。

10. 実践プロジェクト：個人ナレッジベース MCP Server

10.1 プロジェクト要件

AI がローカル Markdown ノートを検索、セマンティック検索、ノート作成/更新できるようにします。Cursor で「先週 MCP について記録したノートは？」と質問できます。

10.2 技術選定

コンポーネント	選定	理由
ベクトル DB	ChromaDB / Qdrant	ローカル軽量、運用不要
埋め込みモデル	text-embedding-3-small	1536 次元、低コスト
ファイル監視	watchfiles	ノート変更の自動再インデックス

10.3 核心コード実装

4 モジュール：index_notes ツール（ディレクトリスキャンでインデックス構築）、semantic_search ツール（ベクトル検索 Top-K）、write_note ツール（Markdown 作成/追記）、notes://{path} リソース（単一ファイル直接読み取り）。約 1000 ノートのインデックスに 2–5 分（M4 Pro）。

10.4 効果デモ

ユーザーが Cursor に入力：「先週 MCP デプロイについて書いたノートの内容は？」→ Agent が semantic_search(query="MCP デプロイ", days=7) を呼び出し → 3 件の関連断片（類似度 0.82–0.91）を返却 → LLM が総合回答し原文を引用。全ノートを Context Window に詰め込む必要はありません。

11. MCP エコシステムと将来展望

11.1 優良 MCP Server 推薦

mcp-server-filesystem（ファイルシステム）、mcp-server-github（リポジトリ操作）、mcp-server-brave-search（ネット検索）、mcp-server-postgres（データベース）、mcp-server-slack（メッセージ）。公式レジストリは 13,000+ Server を追跡しています。

11.2 MCP エコシステムトレンド（2026）

四大ベンダー全面サポート；MCP Marketplace 台頭；エンタープライズ OAuth 2.1 認証がロードマップに；Google A2A プロトコルと補完（MCP = 垂直ツール層、A2A = Agent 横断オーケストレーション）。

11.3 次の学習パス

① modelcontextprotocol.io 仕様を精読；② 最初の公開 MCP Server をリリース；③ MCP + Agent 組み合わせを探索；④ オープンソースエコシステム（Python/TS SDK）に貢献。

12. 五ステップ導入チェックリスト

Step 1 — FastMCP で Hello World を書き、Inspector で検証。Step 2 — 3 つの業務 Tool + 1 つの Resource を登録。Step 3 — Cursor / Claude Desktop に接続（絶対パス設定）。Step 4 — 必要に応じ Streamable HTTP リモートデプロイ。Step 5 — Docker + 監視 + セキュリティ監査で本番稼働。

13. 引用可能な数値

指標	数値
MCP Server エコシステム（2026）	13,000+
18 ヶ月成長倍率	7.8×（1,200 → 9,400+）
TS SDK 累計 DL	150M+
2026 年 MCP 関連 CVE	30+
推奨 Tool I/O タイムアウト	30s
KB インデックス（1000 件）	2–5 min（M4 Pro）

14. 深堀事例：ローカル stdio から Mac リモート算力ノードへ

ある AI エンジニアが MacBook Air 上で Cursor + 5 つの stdio MCP Server（filesystem、postgres、brave-search、カスタム KB、ブラウザツール）を同時実行。統合メモリ 24GB の常駐使用量 19GB、ノート PC 発熱によるクロックダウン、フタを閉じると切断。移行案：ローカルは Cursor Host のみ；5 Server を Streamable HTTP でリモート Mac mini（64GB 統合メモリ）にデプロイ、launchd 常駐；ローカルは url: http://node.macgpu.local:8000/mcp で接続。Tool 呼び出し P99 レイテンシはローカル 180ms から 95ms へ（リモートノードはクロックダウンなし）——かえって安定しました。

Windows/Linux VPS でも MCP Server は動きますが、Xcode、ComfyUI、Final Cut と並行するグラフィック/マルチメディア + AI ツールチェーンシーンでは macOS が依然としてスムーズです。ローカル stdio は開発・検証向け；7×24 本番常駐にはリモート Apple Silicon ノードが適しています。統合メモリを並行 Tool 呼び出しに割り当て、ノート PC はオーケストレーションのみ。

安定したレンタル環境で MCP Server クラスターと Agent Gateway をホスティングしたい場合は、MACGPU リモート Mac ノードをご検討ください。7×24 常駐、HTTP リバースプロキシ設定済み、統合メモリが複数子プロセスで占有されない——「動く」から「安定稼働」へ、ノード一つで実現できます。