ゼロから MCP Server を開発する：AI ツール呼び出し能力の完全ガイド

既存の AI モデルが「外部世界に届かない」主因は、リアルタイムデータや外部ツールへのアクセス手段が標準化されていないことです。Claude にデータベースを照会させ、GPT に API を呼ばせ、Cursor にファイルシステムを操作させる——これが MCP が解決する課題です。ツール呼び出し能力は Function Calling → Plugins → MCP と進化してきました。Function Calling は単一ベンダーに縛られ、Plugins はエコシステムが閉じています。MCP はモデル横断・クライアント横断のオープン標準を提供します。

Anthropic は 2024年11月に MCP を設計し、AI と外部ツール間の通信を標準化して、N 個のモデル × M 個のツール = N×M 件の個別統合という問題を解消することを目指しました。本記事を読み終える頃には、本番投入可能な MCP Server を自力で開発・デプロイできる状態を目指します。

• 車輪の再発明：Cursor、Claude Desktop、VS Code それぞれにファイルシステム連携ロジックを書き直す必要があります。
• モデル変更で全面書き直し：Claude から GPT へ移行すると、統合レイヤー全体を捨て去ることになります。
• リソースとプロンプトに標準がない：Function Calling は「関数呼び出し」に留まり、読み取り専用リソースや再利用可能な Prompt テンプレートをネイティブに公開できません。
• デバッグのブラックボックス：ツール呼び出しが失敗した際、統一された Inspector や JSON-RPC ログがありません。

Client は AI モデル側（Claude Desktop、Cursor、カスタムクライアント）です。Server はあなたが開発する能力提供者です。両者は JSON-RPC 2.0 で通信し、伝送方式は stdio（ローカルプロセス）と HTTP + SSE（リモートサービス）をサポートします。ライフサイクルは初期化ハンドシェイク → 能力ネゴシエーション → リクエスト/レスポンス → クローズです。

Server が公開する三大核心能力は次のとおりです。

• Tools：AI が呼び出せる関数（検索、計算、データベースクエリ）
• Resources：AI が読み取れるリソース（ファイル、URL、データストリーム）
• Prompts：事前定義されたプロンプトテンプレート

Python（初心者向け）：公式 SDK mcp で、シンプルかつ学習コストが低いです。TypeScript（フロントエンド/フルスタック向け）：公式 SDK @modelcontextprotocol/sdk を利用します。本記事は Python を主軸に、TypeScript は対照として示します。

# Python
python -m venv .venv
source .venv/bin/activate
pip install mcp

# 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（公式デバッグ UI）、Claude Desktop によるローカル連携、Cursor の .cursor/mcp.json 設定。公式ドキュメントは modelcontextprotocol.io を参照してください。

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
npx @modelcontextprotocol/inspector python server.py

Cursor の .cursor/mcp.json または Claude Desktop の claude_desktop_config.json に command + args で python server.py を設定し、再起動後にツールが AI コンテキストに表示されることを確認します。

ツールの基本構造は「関数シグネチャがそのままドキュメント」です。パラメータ型、戻り値型、docstring が MCP により JSON Schema に変換され、モデルが理解します。命名は snake_case を使い、エラーは生の例外ではなく構造化された情報を返してください。

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 はサンドボックス制限が必要）
• ファイル読み書き：許可ディレクトリ内のローカルファイルの読み取り/書き込み
• HTTP リクエスト：外部 REST API の呼び出し
• データベースクエリ：読み取り専用 SQL の実行
• 時刻ツール：現在時刻の取得、タイムゾーン変換

import httpx

@mcp.tool()
async def fetch_url(url: str) -> str:
    """指定 URL のコンテンツを取得する"""
    async with httpx.AsyncClient() as client:
        response = await client.get(url)
        return response.text

エラー処理のベストプラクティス：構造化エラー情報を返す、タイムアウトを設定する（30秒推奨）、Server 層で権限チェックを行い、認証情報をクライアント設定に漏らさないこと。

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）、ストリーミングリソース（リアルタイムデータ）をカバーします。ファイルシステムリソース Server では、ディレクトリ一覧、ファイル読み取り、ファイル変更の監視（リソースサブスクリプション）を実装できます。

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} コードをレビューしてください..."
            )
        )
    ]

mcp = FastMCP("remote-server", transport="streamable-http")

if __name__ == "__main__":
    mcp.run(host="0.0.0.0", port=8000)

本番環境では Bearer Token 認証、API Key 検証ミドルウェア、CORS、リクエストレート制限を設定してください。認証情報は各クライアントに分散させず、Server 層で集中管理します。

引用データポイント 1：2026年時点で、MCP エコシステムには 10,000 を超える Server が存在します。

引用データポイント 2：企業が MCP を採用した場合、ツール統合の開発コストは約 38–55% 削減されると報告されています（業界調査レンジ）。

引用データポイント 3：MCP Python SDK の PyPI 月間ダウンロード数は 500万 を突破しました（2026 Q2）。

MCP Inspector でデバッグ UI を起動し、Tools 呼び出しのテスト、JSON-RPC リクエスト/レスポンスログの確認、エラーシナリオのシミュレーションを行います。ユニットテストでは子プロセスとして Server を起動し、ClientSession 経由で呼び出します。

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

async with stdio_client(StdioServerParameters(
    command="python", args=["server.py"]
)) 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"

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 エラーアラート、ヘルスチェックエンドポイント。バージョン管理では MCP プロトコルバージョンを宣言し、後方互換性を保ったツールアップグレード戦略を採用してください。

要件：AI がローカルの Markdown ノートを検索できること、セマンティック検索（ベクトル検索）をサポートすること、ノートの作成・更新ができること。

技術選定：ローカルベクトル DB ChromaDB / Qdrant、埋め込みモデル text-embedding-3-small、ファイル監視 watchfiles。

• ノートインデックスツール：ディレクトリをスキャンし、チャンク分割してベクトル DB に書き込む
• セマンティック検索ツール：クエリに対して Top-K 関連断片を返す
• ノート書き込みツール：Markdown ファイルの作成または追記
• ファイルリソースサービス：Resource URI 経由でノート全文を公開

デモ効果：Cursor で「先週 MCP について何をメモした？」と質問すると、AI が MCP 検索ツールを呼び出し、関連ノート断片を返します。

優れたコミュニティ Server：mcp-server-filesystem（ファイルシステム）、mcp-server-github（GitHub リポジトリ）、mcp-server-brave-search（Web 検索）、mcp-server-postgres（データベース）、mcp-server-slack（Slack メッセージ）。

2026年のトレンド：OpenAI、Google、Microsoft が相次いで MCP 対応を発表。ガバナンスは Linux Foundation AAIF へ移管。MCP Marketplace が急速に成長。エンタープライズ向けセキュリティ標準（OAuth 2.1）がロードマップに入りました。

次の学習パス：MCP プロトコル仕様を深く学ぶ、公開 MCP Server を開発・リリースする、MCP + Agent の組み合わせを探索する、オープンソースエコシステムに貢献する（Python SDK、TypeScript SDK、Inspector）。

1. 01
   伝送モードを決定する：ローカル開発は stdio、チーム共有やリモート Claude Code 呼び出しは HTTP+SSE。API Key は Server 層で集中管理します。
2. 02
   コンソールでクラウド Mac を起動する：NUKCLOUD コンソールにログインし、16 GB 以上のメモリ（複数 Server 並行時は 32 GB 推奨）を選択。料金ページで時間課金の試運転が可能です。
3. 03
   Python 3.12 + mcp をインストールする：SSH ログイン後 pip install mcp httpx pydantic を実行。MCP Inspector でローカルスモークテストを行います。
4. 04
   HTTP Server をデプロイしてポートを公開する：mcp.run(host="0.0.0.0", port=8000)。Bearer Token ミドルウェアと CORS を設定します。
5. 05
   クライアント接続を検証する：Cursor の .cursor/mcp.json をクラウド URL に向ける。tools/list と tools/call のスモークテストを通過させます。
6. 06
   launchd 常駐と月額固定：LaunchAgents plist で 7×24 運用を維持。試運転後は 注文ページでスペックを確定。NUKCLOUD 本番運用 Runbookも参照してください。

ローカルノート PC や共有 VPS で HTTP MCP Server を動かすと、フタを閉じるとセッションが中断される、帯域の揺らぎで SSE が切断される、複数開発者が同一プロセスを奪い合うといった問題が起きがちです。Cursor Background Agents や個人ナレッジベース Server を 7×24 で安定稼働させるには、NUKCLOUD の多リージョン裸金属 Mac / クラウド Mac ノードが、専用テナント境界とスペックの柔軟性の面で MCP ワークフローと相性が良いです。