ゼロから MCP Server を
開発する完全ガイド

Model Context Protocol（MCP）は、AI クライアント（Cursor、Claude Desktop、VS Code など）と外部能力（データベース、API、ファイル）を接続するオープン標準です。2024 年 11 月に Anthropic がオープンソース化し、2026 年時点では OpenAI・Google・Microsoft が採用、Linux Foundation 傘下 AAIF がガバナンスを担います。開発者が Server を実装すれば、一度書いたツール定義をすべての MCP クライアントで再利用できます。

アーキテクチャは三層です。Host（ユーザーが操作するアプリ本体）が内部に MCP Client（各 Server との 1:1 セッション）を持ち、MCP Server（あなたが書くコード）が外部システムに橋渡しします。通信はすべて JSON-RPC 2.0 メッセージで行われ、初期化ハンドシェイク後に能力交換（initialize → initialized）が完了します。

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_articles",
    "arguments": { "query": "MCP デプロイ", "limit": 5 }
  },
  "id": 42
}

主要 RPC メソッドは次のとおりです。tools/list で実行時にツール一覧を動的取得、tools/call で実行、resources/list / resources/read で読み取り専用データ取得、prompts/list / prompts/get でテンプレート取得です。トランスポートは STDIO（ローカル子プロセス、開発向け）と Streamable HTTP（リモート・チーム共有向け）の二系統があります。Server 実装者はビジネスロジックに集中し、プロトコル詳細は SDK が吸収します。

MCP Server は三種類の能力を公開します。Toolsは副作用を伴う実行操作（DB クエリ、API 呼び出し）。Resourcesは読み取り専用データ（ドキュメント、設定ファイル）。Promptsは再利用可能なプロンプトテンプレート（要約、QA 形式）です。Python では FastMCP が最短経路を提供します。

pip install "mcp[cli]"

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("hello-server")

@mcp.tool()
def greet(name: str) -> str:
    """指定した名前で挨拶を返します"""
    return f"こんにちは、{name} さん。MCP Server は正常に動作しています。"

if __name__ == "__main__":
    mcp.run()

型ヒントと docstring から JSON Schema が自動生成され、Client 側の Agent がパラメータ意味を理解できます。次にナレッジベース Server へ 5 ツールを追加します。

@mcp.tool()
def search_articles(query: str, limit: int = 10) -> list[dict]:
    """キーワードで記事を全文検索します"""
    ...

@mcp.tool()
def get_article(article_id: str) -> dict:
    """記事 ID で本文を取得します"""
    ...

@mcp.tool()
def list_categories() -> list[str]:
    """利用可能なカテゴリ一覧を返します"""
    ...

@mcp.tool()
def create_note(title: str, body: str, tags: list[str] | None = None) -> dict:
    """社内メモを新規作成します"""
    ...

@mcp.tool()
def summarize_text(text: str, max_chars: int = 300) -> str:
    """長文を指定文字数以内に要約します"""
    ...

Resourcesは URI スキームで識別されます。ファイルは file:///data/docs/readme.md、カスタムスキームは kb://articles/2026-mcp-guide のように定義し、Client が resources/read で内容を取得します。

@mcp.resource("kb://articles/{article_id}")
def article_resource(article_id: str) -> str:
    return load_markdown(article_id)

@mcp.resource("file://config/{name}")
def config_resource(name: str) -> str:
    return Path(f"./config/{name}.json").read_text(encoding="utf-8")

Promptsは変数付きテンプレートです。Agent が prompts/get で取得し、LLM 入力にそのまま渡せます。

@mcp.prompt()
def qa_from_context(question: str, context_uri: str) -> str:
    """コンテキスト URI の内容を根拠に QA 形式で回答するプロンプト"""
    ctx = resolve_resource(context_uri)
    return f"""以下のコンテキストのみを根拠に質問に答えてください。
コンテキスト:
{ctx}

質問: {question}"""

@mcp.prompt()
def summarize_article(article_id: str, style: str = "bullet") -> str:
    body = load_markdown(article_id)
    return f"記事を{style}形式で要約してください:\n\n{body}"

ローカル開発は STDIO で十分ですが、チーム共有や CI 連携では HTTP トランスポートが必要です。FastMCP は mcp.run(transport="streamable-http") で切り替えられ、2026 年仕様では Streamable HTTP が SSE 後継として推奨されています。

if __name__ == "__main__":
    mcp.run(
        transport="streamable-http",
        host="0.0.0.0",
        port=8080,
        path="/mcp"
    )

MCP Inspectorは公式デバッグ UI です。STDIO と HTTP の両方をテストでき、tools/list の応答、引数バリデーション、エラートレースをブラウザで確認できます。

npx @modelcontextprotocol/inspector python server.py

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Inspector では Transport を stdio に設定し Command に python、Arguments に server.py を指定します。HTTP モードでは URL に http://localhost:8080/mcp を入力します。tools/call タブで各ツールを手動実行し、JSON Schema 違反を本番接続前に潰せます。

本番デプロイは Docker が定番です。非 root ユーザー、ヘルスチェック、環境変数による秘密情報注入を含めます。

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY server.py .
RUN useradd -m mcpuser
USER mcpuser
EXPOSE 8080
HEALTHCHECK CMD curl -f http://localhost:8080/mcp || exit 1
CMD ["python", "server.py"]

docker build -t kb-mcp-server .
docker run -d --name kb-mcp -p 8080:8080 \
  -e DATABASE_URL="postgresql://..." \
  -e API_KEY="sk-..." \
  kb-mcp-server

ここまでの要素を統合した社内ナレッジベース MCP Serverが capstone プロジェクトです。Markdown 記事を kb:// Resources として公開し、search_articles / get_article Tools で Agent が RAG なしでも構造化検索でき、qa_from_context Prompt で回答形式を統一します。PostgreSQL にメタデータ、ベクトル検索は pgvector または外部 Embedding API を Tool 内で呼び出す構成が 2026 年の実務標準です。

自前実装以外に、エコシステムには 10,000 超の公開 MCP Server があります。よく使われる代表例を下表にまとめます。

エコシステム Server を組み合わせ、Filesystem + GitHub + 自社 KB を同一 Cursor セッションに載せる「開発者デスク構成」が 2026 年の主流ワークフローです。自社 Server は差別化資産として残し、汎用部分は npm 公式 Server をそのまま利用するのがコスト最小です。

「既存の Function Calling や LangChain Tools で足りるのでは？」という疑問に答えるため、三方式を Agent 統合の観点で比較します。

以下の七ステップ Runbookをそのままチーム Runbook に貼り付けて評価から本番まで進められます。

2026 年時点の参考データは次の三つです。

ノート PC 上の STDIO Server はスリープ一発でセッションが切れます。Linux VPS は Apple Silicon 最適化推論や Xcode ビルドをネイティブ実行できません。MCP Server と Cursor / Claude Code を 7×24 同居させる本番構成では、MESHLAUNCH の Mac Mini M4 クラウドレンタルが合理的です。専有 Apple Silicon、日/週/月の柔軟契約、料金ページで即見積もり可能。デプロイ障害はヘルプセンターも参照してください。