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

AI に MCP Server が必要な理由：ツールのない LLM は「話せる脳」にすぎない

大規模言語モデルの学習データには期限があり、CRM、Git リポジトリ、社内 API にはアクセスできません。2024年以前は、Claude 向けに Function Calling、GPT 向けに Plugins、Cursor 向けに別形式——モデルを変えるたびに作り直しが必要でした。MCP Server では「ツール能力」を独立プロセスとしてカプセル化し、一度書けば Claude Desktop / Cursor / Gemini すべてで使えます。

典型的なシナリオ：Claude Desktop で AI に Postgres の売上データを照会させる、Cursor で Agent にプロジェクトドキュメントを読ませてコードを修正させる、GPT が HTTP MCP 経由で社内チケットシステムを呼び出す——いずれも同じ Server が基盤です。

本稿の価値：概念説明ではなく、say_hello からベクトル検索付き本番級ナレッジベース Server までを実践します。対象読者：Python または TypeScript の基礎があり、IDE や Desktop で AI 能力を拡張したい開発者です。

六つの課題：「API をラップするだけ」では足りない理由

1. 01

   モデルベンダーロックイン：OpenAI Function Calling と Claude Tool Use は形式が異なり、ベンダーを変えるたびにアダプタ層を書き直す必要があります。

2. 02

   ツールが発見できない：REST API は静的ドキュメントに依存し、AI は実行時に tools/list で能力一覧を自律取得できません。

3. 03

   IDE ごとにバラバラ：Cursor、VS Code 拡張、JetBrains プラグインのツール定義は再利用できず、N×M セットの統合を保守し続ける必要があります。

4. 04

   コンテキストとデータの分断：LLM は設定ファイル、ユーザー設定、リアルタイムログを安定して読み取れず、標準化された Resources 読み取りチャネルが必要です。

5. 05

   Prompt テンプレートの散在：Code Review や Incident レポートなどの再利用テンプレートに統一登録機構がなく、チームごとにコピペしています。

6. 06

   ローカル vs リモートデプロイの混乱：stdio 子プロセスは開発向きですが、本番 HTTP ゲートウェイ、認証、監視には統一パラダイムが不足しています（stdio 子プロセス運用編 参照）。

開発環境の構築：Python FastMCP vs TypeScript SDK

二つの主流ルートがあります。Python mcp + FastMCP（データ/スクリプト向き）と TypeScript @modelcontextprotocol/sdk（Web/API 統合、型安全）。SDK ソース：python-sdk、typescript-sdk。

# Python ルート
python -m venv .venv && source .venv/bin/activate
pip install "mcp[cli]" httpx pydantic

# TypeScript ルート
npm init -y && npm install @modelcontextprotocol/sdk zod
npm install -D typescript tsx @types/node

推奨プロジェクト構成

my-mcp-server/
├── pyproject.toml          # または package.json
├── src/
│   ├── server.py           # FastMCP エントリポイント
│   ├── tools/              # 各ツールモジュール
│   ├── resources/          # Resource プロバイダ
│   └── prompts/            # Prompt テンプレート
├── tests/
│   └── test_tools.py       # pytest + ClientSession
├── Dockerfile
└── README.md

六ステップ環境準備チェックリスト

1. 01

   言語スタックを選択：データ/ML チームは Python を優先、Node フルスタックは TypeScript を選択します。

2. 02

   仮想環境を作成し依存を固定：pip freeze または package-lock.json で schema ドリフトを防ぎます。

3. 03

   MCP Inspector をインストール：npx @modelcontextprotocol/inspector で JSON-RPC を可視デバッグします。

4. 04

   Claude Desktop を設定：~/Library/Application Support/Claude/claude_desktop_config.json を編集し、Server の command/args を追加します。

5. 05

   Cursor を設定：Settings → MCP → Add Server で、stdio に python -m src.server または絶対パスを入力します。

6. 06

   Inspector 接続を検証：Server 起動 → Inspector 接続 → tools/list が非空で返ることを確認します。

// Cursor / Claude Desktop MCP 設定例
{
  "mcpServers": {
    "my-tools": {
      "command": "python",
      "args": ["-m", "src.server"],
      "env": { "API_KEY": "your-key" }
    }
  }
}

Tools 実践：Schema から五つの本番級ツールへ

Tool は MCP の中核能力です。AI は tools/call 経由で副作用のある操作を実行します。各 Tool は名称、説明、inputSchema を公開する必要があり、FastMCP は Pydantic モデルでバリデーションを強化します。

from pydantic import BaseModel, Field

class SearchInput(BaseModel):
    query: str = Field(..., description="検索キーワード")
    limit: int = Field(10, ge=1, le=100, description="返却件数")

@mcp.tool()
async def search_docs(params: SearchInput) -> str:
    """ドキュメントライブラリを検索する"""
    results = await index.search(params.query, params.limit)
    return json.dumps(results, ensure_ascii=False)

五つのよく使う Tool パターン

• calculator：安全な eval または ast.literal_eval を使用し、exec は禁止します。
• file_read / file_write：ルートディレクトリのホワイトリストを設け、パストラバーサルを防ぎます。
• fetch_url（async）：httpx で非同期リクエストし、timeout とドメインホワイトリストを設定します。
• db_query：読み取り専用 SQL + パラメータ化クエリのみ許可し、DDL は禁止します。
• get_current_time：ISO8601 タイムゾーン付き時刻を返し、LLM の時間幻覚を解消します。

import httpx
from datetime import datetime, timezone

@mcp.tool()
async def fetch_url(url: str) -> str:
    """HTTP GET で URL コンテンツを取得（ドメインホワイトリスト内）"""
    allowed = ("api.github.com", "nodemini.com")
    if not any(url.startswith(f"https://{d}") for d in allowed):
        raise ValueError(f"Domain not allowed: {url}")
    async with httpx.AsyncClient(timeout=10.0) as client:
        resp = await client.get(url)
        resp.raise_for_status()
        return resp.text[:8000]

@mcp.tool()
def get_current_time() -> str:
    """現在の UTC 時刻を返す"""
    return datetime.now(timezone.utc).isoformat()

エラーハンドリングのベストプラクティス

• 構造化エラーを返す：raise ValueError("human-readable msg") を使うと、Client が message を LLM に返します。
• リトライ可能 vs 致命的を区別：ネットワークタイムアウトは retryable とマークし、権限拒否は即 fail します。
• ログとマスキング：tool 名と所要時間を記録し、API Key や PII の全文は log しません。
• 冪等設計：書き込み操作に idempotency_key を付け、Agent の重複呼び出しによるデータ汚染を防ぎます。

Prompts：再利用可能な多段会話テンプレート

MCP Prompt はServer に登録された会話の骨格です。Client は prompts/get でメッセージリストを取得し、user / assistant ロールとパラメータプレースホルダを含められます——チームで Code Review や Incident フローを共有でき、各自が Prompt ファイルを保守する必要がありません。

from mcp.types import PromptMessage, TextContent

@mcp.prompt()
def code_review_prompt(language: str = "python") -> list[PromptMessage]:
    """標準化 Code Review 多段テンプレート"""
    return [
        PromptMessage(role="user", content=TextContent(
            type="text",
            text=f"あなたはシニア {language} エンジニアです。以下の diff を安全性・性能・可読性の三軸でレビューしてください。"
        )),
        PromptMessage(role="assistant", content=TextContent(
            type="text",
            text="diff を貼り付けるか PR 番号を指定してください。CHECKLIST に沿った構造化 review を出力します。"
        )),
    ]

多段テンプレートには {ticket_id}、{severity} などの変数をネストでき、Server 側でバージョン管理すれば Client が Server をアップグレードするだけで全員が最新 review 基準に同期されます。

デバッグとテスト：Inspector + pytest ユニットテスト

MCP Inspector は公式の可視デバッガです。stdio または URL に接続後、tools/list、tools/call を手動送信し JSON-RPC の往復を確認できます。Cursor ログを推測するより遥かに効率的です。

# tests/test_tools.py
import pytest
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

@pytest.mark.asyncio
async def test_say_hello():
    params = StdioServerParameters(command="python", args=["-m", "src.server"])
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool("say_hello", {"name": "MCP"})
            assert "MCP" in result.content[0].text

よくあるエラー対照表

実践プロジェクト：ChromaDB ナレッジベース MCP Server

社内 Wiki / Markdown ドキュメントをベクトル化し、index_document、search_knowledge、write_note の三つの Tool を公開すれば、Cursor Agent が「社内ナレッジベースを検索してからコードを書く」ことができます。

要件：docs/ の増分インデックス（watchfiles 監視）、セマンティック検索 Top-K、オプションの scratchpad 書き込みをサポートします。

import chromadb
from chromadb.utils.embedding_functions import SentenceTransformerEmbeddingFunction

client = chromadb.PersistentClient(path="./data/chroma")
collection = client.get_or_create_collection(
    "wiki", embedding_function=SentenceTransformerEmbeddingFunction()
)

@mcp.tool()
def search_knowledge(query: str, top_k: int = 5) -> str:
    """社内ナレッジベースをセマンティック検索する"""
    hits = collection.query(query_texts=[query], n_results=top_k)
    return json.dumps(hits["documents"][0], ensure_ascii=False)

@mcp.tool()
def index_document(path: str) -> str:
    """単一 Markdown ファイルをインデックスする"""
    text = open(path).read()
    collection.upsert(ids=[path], documents=[text], metadatas=[{"path": path}])
    return f"Indexed: {path}"

Cursor デモクエリ：「ナレッジベースで MCP HTTP デプロイに関するドキュメントを検索し、三ステップの本番チェックリストを要約して」——Agent は先に search_knowledge を呼び、検索結果に基づいて回答します。大規模向けには Qdrant（リモート gRPC）への置き換えも可能です。