MCPサーバー作成ベストプラクティス 技術調査レポート

発行日: 2026-07-04 テーマ: 2026年7月時点における Model Context Protocol（MCP）サーバー開発のベストプラクティス。仕様の現在地（2025-11-25 安定版 / 2026-07-28 RC）、ツール設計・トランスポート・認可/セキュリティ・テスト運用の定石を、TypeScript / Python のサンプルコード付きで整理

TL;DR

追記（2026-07-29）: 2026-07-28 改訂は予定どおり正式リリースされ、Anthropic は Claude 製品への展開開始を発表した。確定内容と本レポートへの影響は文末の「追記: 2026-07-28 改訂の正式リリース」を参照。

• 現行の安定版仕様は 2025-11-25。2026-07-28 にプロトコル開始以来最大の改訂（ステートレスコア・Extensions・Tasks・MCP Apps）が確定公開予定で、RC が既に出ている。今から作るサーバーは「ステートレス前提」で設計しておくと移行コストが最小になる。
• SDK は TypeScript v1.x / Python v1.x が本番推奨。両 SDK とも v2 が 2026-07 末の新仕様と同時に安定化予定（TS v2 はパッケージ名が @modelcontextprotocol/sdk → @modelcontextprotocol/server に変わる）。
• ツール設計の定石は「API のラッパーではなく、エージェントのワークフロー単位で切る」。1サーバー = 1つの境界づけられたコンテキスト、ツール数は 5〜15 個が目安。list_* より search_*、冗長な JSON より response_format（concise/detailed）でトークンを節約する。
• 入力検証エラーはプロトコルエラーではなく isError: true のツール実行エラーで返す（モデルが自己修正できる）。outputSchema + structuredContent で構造化出力を返すのが現行仕様の推奨。
• トランスポートは ローカル = stdio、リモート = Streamable HTTP の二択（HTTP+SSE は非推奨済み）。stdio ではログを必ず stderr へ（stdout に書くとプロトコルが壊れる）。
• 認可は OAuth 2.1 ベース。「トークンパススルーは禁止」「セッションを認証に使わない」が仕様上の MUST。スコープは最小から始めて WWW-Authenticate による段階的昇格（2025-11-25 で追加）を使う。
• 2026-07-28 改訂で Roots / Sampling / Logging が非推奨入り（12ヶ月の削除猶予）。新規開発でこれらに強く依存するのは避ける。

1. MCP の現在地（2026-07 時点）

1.1 仕様バージョンの整理

2025-11-25 の主な変更点（開発者に影響が大きいもの）:

• 入力検証エラーは「ツール実行エラー」で返すことが明確化（SEP-1303）。プロトコルエラーにするとモデルが自己修正できない。
• JSON Schema 2020-12 がデフォルト方言に（SEP-1613）。
• ツール・リソース・プロンプトにアイコンを付与可能に（SEP-973）。
• URL モード Elicitation（SEP-1036）: サーバーがユーザーをブラウザ URL へ誘導できる。
• 段階的スコープ同意（SEP-835）: WWW-Authenticate の scope チャレンジで必要時に権限昇格。
• stdio サーバーはあらゆるログを stderr に出してよいことが明文化。
• Streamable HTTP で不正な Origin ヘッダーには HTTP 403 を返すことが必須化。

1.2 SDK の状況

現時点の結論: 本番は v1.x で作り、v2 の安定化（今月末）を待ってから移行を計画する。 v1.x は v2 リリース後も最低6ヶ月はセキュリティ修正が提供される。

2. アーキテクチャ設計のベストプラクティス

2.1 1サーバー = 1つの境界づけられたコンテキスト

MCP サーバーを「雑多なツールの寄せ集めホスト」にしない。ドメイン単位（例: 注文管理、CI/CD、ドキュメント検索）で分割し、各サーバーに明確な責務を1つ持たせる。

• ツール数の目安: 5〜8 個が理想、8〜12 個は許容、15 個を超えたらサーバー分割を検討。
• ツールが多いほどクライアント側のコンテキストを消費し、モデルのツール選択精度も落ちる。「とりあえず全 API をツール化」は最悪手。

2.2 API ラッパーではなく「ワークフロー」を切り出す

Anthropic の公式ガイダンス（Writing effective tools for agents）の中心的な主張。既存 REST API の 1:1 ラッパーは、エージェントに何度も往復を強いてトークンを浪費する。

• ❌ list_users, list_events, create_event を個別に呼ばせて空き時間を探させる
• ⭕ schedule_event（空き検索+登録まで一括で行う意図レベルのツール）
• ❌ list_contacts（全件返してモデルに探させる）
• ⭕ search_contacts（サーバー側で絞り込んで返す）

2.3 ステートレス設計をデフォルトに

2026-07-28 改訂でプロトコル自体がステートレスコアに移行する。今から作るサーバーは:

• ツールは冪等・ステートレスを基本とする（水平スケール・テスト容易性・ロードバランサ対応）。
• 状態が避けられない場合はインスタンス外部の永続ストア（DB / Redis 等）に置き、セッション ID やインメモリ状態に依存しない。
• 「sticky session が必要な設計」は新仕様で負債になる。

3. ツール設計の定石

3.1 命名と説明

• ツール名は snake_case、ドメインプレフィックスを付ける（asana_search_tasks, github_create_issue）。複数サーバー併用時の衝突・混同を防ぐ。
• description は「新入社員に渡す指示書」のつもりで書く。いつ使うべきか / 使うべきでないか、必須と任意のパラメータ、返り値の形を明示する。
• パラメータ名は曖昧さを排除する: user ではなく user_id（user は名前なのかオブジェクトなのか ID なのか曖昧）。
• 説明文の推敲は評価結果に基づいて反復する。Anthropic は「description の改善だけでエージェントの成功率が大きく向上した」と報告している。

3.2 スキーマ: 入力も出力も厳格に

• inputSchema は厳格に型付けし、enum・範囲・デフォルト値まで定義する（JSON Schema 2020-12）。
• 2025-06-18 以降は outputSchema + structuredContent で構造化出力を返せる。クライアント/モデル双方が結果を機械的に検証でき、後段処理が安定する。
• 互換性のため、structuredContent を返す場合も同内容の JSON テキストを content に併記するのが SDK の標準動作。

3.3 トークン効率

ツールのレスポンスが消費するトークンは、そのままモデルの思考に使えるトークンを削る。

• response_format: "concise" | "detailed" パラメータを設け、既定は concise にする（Anthropic の実測で最大 65% のトークン削減)。
• 大量件数はページネーション + 件数上限（limit のデフォルトと最大値）を必ず設ける。
• UUID や内部 ID の羅列より、モデルが次のアクションに使える意味のある識別子（名前+ID など）を返す。

3.4 エラーはモデルが自己修正できる形で返す

入力不備・業務エラーは JSON-RPC のプロトコルエラーにせず、isError: true のツール結果として「何が悪くて、どう直せばよいか」を自然言語で返す（SEP-1303 で明確化）。

{
  "content": [{ "type": "text", "text": "limit は 1〜50 の範囲で指定してください（受領値: 500）" }],
  "isError": true
}

3.5 アノテーションで挙動のヒントを宣言する

annotations はクライアント（承認 UI 等）へのヒント。セキュリティ境界としては信頼されないが、UX を大きく改善する。

• readOnlyHint: true … 読み取り専用（承認プロンプトの省略候補になる）
• destructiveHint: true … 破壊的変更（明示承認を促す）
• idempotentHint: true … 再実行安全
• openWorldHint: true … 外部世界と相互作用する

4. サンプルコード

4.1 TypeScript（SDK v1.x・本番推奨）: stdio サーバー

npm install @modelcontextprotocol/sdk zod

// src/server.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "orders-mcp",
  version: "1.0.0",
});

// ベストプラクティス:
//  - search_*（list_* ではなく）でサーバー側絞り込み
//  - inputSchema に上限・デフォルトを定義
//  - outputSchema + structuredContent で構造化出力
//  - readOnlyHint で読み取り専用を宣言
server.registerTool(
  "orders_search",
  {
    title: "注文検索",
    description:
      "顧客名・商品名・ステータスで注文を検索する。注文の一覧取得や状態確認にはまずこのツールを使うこと。" +
      "結果が多い場合は limit で絞る。詳細情報が必要な場合のみ response_format=detailed を指定する。",
    inputSchema: {
      query: z.string().min(1).describe("検索キーワード（顧客名・商品名・注文ID）"),
      status: z.enum(["pending", "shipped", "delivered", "cancelled"]).optional(),
      limit: z.number().int().min(1).max(50).default(10),
      response_format: z.enum(["concise", "detailed"]).default("concise"),
    },
    outputSchema: {
      total: z.number(),
      orders: z.array(
        z.object({
          order_id: z.string(),
          customer_name: z.string(),
          status: z.string(),
          total_jpy: z.number(),
        }),
      ),
    },
    annotations: { readOnlyHint: true, openWorldHint: false },
  },
  async ({ query, status, limit, response_format }) => {
    const orders = await searchOrders({ query, status, limit, detail: response_format === "detailed" });

    // 業務エラー・入力不備は isError: true のツール結果で返す
    // （プロトコルエラーにするとモデルが自己修正できない）
    if (orders === null) {
      return {
        content: [{ type: "text", text: `検索インデックスが利用できません。時間を置いて再試行してください。` }],
        isError: true,
      };
    }

    const structured = { total: orders.length, orders };
    return {
      // 後方互換のためテキストにも同内容を載せる
      content: [{ type: "text", text: JSON.stringify(structured) }],
      structuredContent: structured,
    };
  },
);

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  // 重要: stdio サーバーで console.log は禁止（stdout はプロトコル専用）。
  // ログはすべて stderr へ。
  console.error("orders-mcp started (stdio)");
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

4.2 TypeScript: Streamable HTTP（ステートレス構成）

リモート公開するならこちら。リクエストごとにトランスポートを生成するステートレス構成は、2026-07-28 のステートレスコアともそのまま整合する。

// src/http-server.ts
import express from "express";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { buildServer } from "./server-factory.js"; // McpServer を組み立てるファクトリ

const app = express();
app.use(express.json());

app.post("/mcp", async (req, res) => {
  // sessionIdGenerator: undefined => セッションレス運用。
  // どのインスタンスでもリクエストを処理でき、水平スケールが単純になる。
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined,
    enableJsonResponse: true,
    // ローカル開発時の DNS リビンディング対策（本番はリバースプロキシで Origin 検証）
    enableDnsRebindingProtection: true,
    allowedHosts: ["127.0.0.1", "localhost"],
  });
  res.on("close", () => {
    transport.close();
  });

  const server = buildServer();
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

// 仕様: 不正な Origin には 403 を返す（2025-11-25 で必須化）
app.listen(3000, "127.0.0.1", () => {
  console.error("orders-mcp listening on http://127.0.0.1:3000/mcp");
});

4.3 Python（SDK v1.x / FastMCP）

pip install "mcp[cli]"

# server.py
from enum import Enum
from pydantic import BaseModel, Field
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("orders-mcp")


class OrderStatus(str, Enum):
    pending = "pending"
    shipped = "shipped"
    delivered = "delivered"
    cancelled = "cancelled"


class Order(BaseModel):
    """構造化出力: 返り値の型ヒントから outputSchema が自動生成される"""
    order_id: str
    customer_name: str
    status: OrderStatus
    total_jpy: int


@mcp.tool()
def orders_search(
    query: str = Field(description="検索キーワード（顧客名・商品名・注文ID）"),
    status: OrderStatus | None = None,
    limit: int = Field(default=10, ge=1, le=50),
) -> list[Order]:
    """顧客名・商品名・ステータスで注文を検索する。

    注文の一覧取得や状態確認にはまずこのツールを使うこと。
    結果が多い場合は limit で絞る。
    """
    return search_orders(query=query, status=status, limit=limit)


@mcp.tool()
def orders_cancel(order_id: str, reason: str) -> str:
    """注文をキャンセルする（破壊的操作・要確認）。

    delivered 状態の注文はキャンセルできない。
    """
    order = get_order(order_id)
    if order is None:
        # ValueError は isError: true のツール実行エラーとして返る
        raise ValueError(f"注文 {order_id} が見つかりません。orders_search で ID を確認してください。")
    if order.status == OrderStatus.delivered:
        raise ValueError("配達済みの注文はキャンセルできません。返品フローを案内してください。")
    cancel_order(order_id, reason)
    return f"注文 {order_id} をキャンセルしました"


if __name__ == "__main__":
    # ローカル: mcp.run()  (stdio)
    # リモート: streamable-http
    mcp.run(transport="streamable-http")

4.4 参考: TypeScript SDK v2（beta）の書き味

v2 ではパッケージが分割され、inputSchema に zod v4 のスキーマオブジェクトをそのまま渡す形になる。

import { McpServer } from "@modelcontextprotocol/server";
import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
import * as z from "zod/v4";

const server = new McpServer({ name: "greeting-server", version: "1.0.0" });

server.registerTool(
  "greet",
  {
    description: "Greet someone by name",
    inputSchema: z.object({ name: z.string() }),
  },
  async ({ name }) => ({
    content: [{ type: "text", text: `Hello, ${name}!` }],
  }),
);

const transport = new StdioServerTransport();
await server.connect(transport);

5. トランスポート選択

• Streamable HTTP は「plain JSON レスポンス」と「SSE ストリーム」を状況で使い分けられる。進捗通知や elicitation が不要な単純ツールなら enableJsonResponse: true（plain JSON）がスケールしやすい。
• 2025-11-25 で SSE のポーリング型運用（サーバーが任意に切断→クライアントが GET で再開）が公式化された。長時間接続の保持を前提にしない。
• 2026-07-28 以降はセッションヘッダー（Mcp-Session-Id）自体が廃止される。セッション ID に業務ロジックを載せないこと。

6. 認可とセキュリティ

6.1 認可（リモートサーバー）

• ベースは OAuth 2.1。MCP サーバーは OAuth のリソースサーバーであり、RFC 9728（Protected Resource Metadata）でオーソリゼーションサーバーを広告する。
• クライアントは RFC 8707 Resource Indicators で「このMCPサーバー向け」のトークンを取得する（2025-06-18 で必須化）。
• 2025-11-25 で OIDC Discovery 対応と Client ID Metadata Documents（動的クライアント登録の代替）が追加され、エンタープライズ IdP との統合が現実的になった。
• スコープは最小で始める。全スコープを最初に要求せず、特権操作が試みられた時に WWW-Authenticate の scope チャレンジで段階的に昇格させる。

6.2 仕様上の MUST（違反すると脆弱性になる）

1. トークンパススルー禁止: クライアントから受け取ったトークンを検証せず下流 API に横流ししない。自サーバー宛て（audience）に発行されたトークンのみ受け入れる。
2. セッションを認証に使わない: セッション ID はあくまで転送層の識別子。認可は毎リクエスト検証する。セッション ID は CSPRNG で生成し、可能なら <user_id>:<session_id> 形式でユーザーにバインドする（セッションハイジャック対策）。
3. Confused Deputy 対策: サードパーティ API への OAuth プロキシとして動く場合、静的 client_id での consent クッキー再利用を悪用されないよう、クライアントごとの同意画面を必ず挟む。redirect_uri は完全一致で検証する。
4. Origin 検証: Streamable HTTP で不正な Origin には 403 を返す（DNS リビンディング対策）。

6.3 プロンプトインジェクション / ツールポイズニング

• ツールが返すデータ（Web ページ、Issue 本文、検索結果）は信頼できない入力。レスポンス内の指示をモデルが実行してしまう「間接プロンプトインジェクション」を前提に設計する。
• 対策の基本は最小権限（読み取り専用トークン、スコープ分離）と破壊的操作の human-in-the-loop（destructiveHint + クライアント側承認）。
• サーバー配布側は、ツール description に悪意ある指示を仕込む「ツールポイズニング」への警戒として、依存する MCP サーバーの description を監査対象にする（バージョン固定・レビュー）。

7. テスト・評価・運用

7.1 開発ループ

1. MCP Inspector（npx @modelcontextprotocol/inspector）でツールの疎通・スキーマ・レスポンスを対話確認する。
2. 評価駆動で description を磨く: 実タスクに近いプロンプト集を用意し、エージェントに解かせて成功率を測る。Anthropic の推奨プロセスは「プロトタイプ → 評価 → （エージェントと）協働改善」の反復。ツールの transcript を読み、モデルがどこで迷ったかを description に反映する。
3. ユニットテストはツールのハンドラ関数を直接呼ぶ形で書き、スキーマ検証は SDK に任せる。

7.2 ロギングと可観測性

• stdio: stderr に構造化ログ。stdout 汚染は最も典型的な事故。
• HTTP: OpenTelemetry ベースのトレーシングを推奨。2026-07-28 改訂で W3C Trace Context の _meta 伝播が公式ドキュメント化される。
• プロトコルの logging ケーパビリティは 2026-07-28 で非推奨になるため、新規で依存しない。

7.3 バージョニングと配布

• ツールスキーマの変更は加算的変更を優先し、フィールド削除・意味変更はメジャーバージョンで。クライアント側のプロンプトはツール定義に依存しているため、破壊的変更の影響は API より大きい。
• 配布は MCP Registry（server.json）への登録が標準ルートになりつつある。Implementation の description フィールド（2025-11-25 追加）を registry と揃える。

8. 2026-07-28 改訂への備え（アクションアイテム)

今月末に確定する新仕様に向けて、今から作るサーバーで意識すべきこと:

1. ステートレスに作る: initialize ハンドシェイクと Mcp-Session-Id は廃止される。セッションに依存した設計は移行コストが跳ね上がる。
2. Roots / Sampling / Logging に新規依存しない: 12ヶ月の猶予付きで非推奨入り。Sampling の代替は LLM プロバイダ API の直接利用、Logging の代替は stderr / OpenTelemetry。
3. 長時間処理は Tasks 拡張へ: 2025-11-25 の実験的 Tasks API を使っている場合、拡張ベースのライフサイクル（tasks/get / tasks/update / tasks/cancel）への移行が必要。
4. リソース未検出エラーコードの変更: -32002 → 標準の -32602 に変わる。エラーコードのマッチングをしている場合は要修正。
5. リスト系レスポンスにキャッシュヒント: ttlMs / cacheScope が追加される。list 系ツールを持つサーバーは対応するとクライアント体験が向上する。
6. UI が必要なら MCP Apps: サンドボックス化された iframe でサーバー提供の HTML UI をレンダリングできる公式拡張（SEP-1865）が入る。独自のアウトオブバンド UI を作る前に検討する。

9. ベストプラクティス チェックリスト

• 1サーバー = 1ドメイン、ツール数 5〜15
• ツール名は domain_action 形式の snake_case、description に「いつ使う/使わない」を明記
• list_* ではなく search_*、response_format でトークン節約、limit 上限あり
• inputSchema / outputSchema を厳格に定義、structuredContent を返す
• 入力・業務エラーは isError: true + 修正ヒント付きテキストで返す
• readOnlyHint / destructiveHint 等のアノテーションを宣言
• stdio では stdout にログを書かない（stderr のみ）
• リモートは Streamable HTTP、Origin 検証、127.0.0.1 バインド（ローカル時）
• トークンパススルーをしない、セッションを認証に使わない
• スコープ最小 + 段階的昇格、破壊的操作は human-in-the-loop
• MCP Inspector + 評価駆動で description を反復改善
• ステートレス設計で 2026-07-28 仕様に備える

追記（2026-07-29）: 2026-07-28 改訂の正式リリース

本文執筆時点（2026-07-04）で RC だった 2026-07-28 改訂が予定どおり正式公開され、Anthropic も同日「Bringing MCP 2026-07-28 to Claude」で Claude 製品への順次展開を発表した（製品別の展開日程は未公表）。確定した changelog（公式）のうち、本文の予想からの差分・開発者影響が大きい点:

確定した主要変更（本文の予想との対応）

本文で触れていなかった確定事項（要注意）

• server/discover RPC が必須化: サーバーは対応バージョン・capabilities・identity を広告する server/discover を MUST 実装
• サーバー発リクエストの廃止 → MRTR パターンへ: roots/list / sampling/createMessage / elicitation/create のようなサーバー→クライアント要求は、resultType: "input_required" を返してクライアントが元リクエストを再試行する Multi Round-Trip Requests に置き換え（SEP-2322）。全結果に resultType フィールドが必須になった
• 通知系の再編: HTTP GET エンドポイントと resources/subscribe は subscriptions/listen（単一の長寿命 POST ストリーム）に統合。ping・logging/setLevel は削除、ログレベルは _meta の io.modelcontextprotocol/logLevel でリクエスト単位指定
• SSE 再開機構の削除: Last-Event-ID によるストリーム再開・再配送は廃止。切断されたら新しいリクエスト ID で再発行が MUST
• キャッシュの一級市民化: tools/list 等の一覧系は ttlMs / cacheScope が必須（CacheableResult）。tools/list は決定的順序で返すことが SHOULD に（LLM のプロンプトキャッシュ効率に直結）
• 認可まわり: RFC 9207 の iss 検証がクライアント MUST に、Dynamic Client Registration（RFC 7591）は非推奨入りし Client ID Metadata Documents へ移行。資格情報は発行元 AS 単位で分離保存が MUST
• エラーコード再配置: -32020〜-32099 が MCP 仕様予約に。resource not found は -32002 → -32602 に変更

本レポートへの影響

本文の推奨（ステートレス前提設計・セッションに業務ロジックを載せない・stdio ログは stderr・Roots/Sampling/Logging 回避）はそのまま有効で、いずれも正式版と整合する。今後の新規開発は 2026-07-28 前提とし、既存サーバーは (1) server/discover 実装、(2) resultType 対応、(3) 一覧系への ttlMs/cacheScope 付与、(4) サーバー発リクエスト依存の MRTR 移行、の順で対応するのが現実的。SDK（TS v2 / Python v2）の安定化状況は別途確認が必要（本追記時点では未確認）。

参考リンク

• MCP Specification 2025-11-25（現行安定版）
• 2025-11-25 Changelog
• MCP Specification 2026-07-28（正式版）
• 2026-07-28 Changelog
• Bringing MCP 2026-07-28 to Claude — Anthropic
• The 2026-07-28 MCP Specification Release Candidate（公式ブログ）
• The 2026 MCP Roadmap（公式ブログ）
• Security Best Practices（公式仕様）
• TypeScript SDK（GitHub）
• Python SDK（GitHub）
• Writing effective tools for AI agents — Anthropic Engineering
• Code execution with MCP — Anthropic Engineering
• MCP Server Best Practices — MCPcat
• 8 Tips and Best Practices for MCP Server Development — Nordic APIs