🧩 MCP サーバー開発を足場化する公式 Agent Skills - mcp-server-dev

MCP（Model Context Protocol）公式が「Build with Agent Skills」ドキュメントで、MCP サーバー開発を足場化する mcp-server-dev プラグインを提示しました。build-mcp-server / build-mcp-app / build-mcpb の 3 つの Agent Skill が、エージェントにユースケースを問診させ、デプロイモデル・認証・配布形態・ツール設計まで決めてからサーバーを scaffold します。

この記事では、MCP サーバー開発が「API を LLM に開くだけ」の作業から、設計対象として扱う開発へと変わる仕組みを、構造とデータの両面から整理します。

検証日: 2026-06-21 / 対象: anthropics/claude-plugins-official の mcp-server-dev プラグイン（3 スキルとも version 0.1.0）・MCPB manifest schema v0.4・MCP spec 2025-11-25

概要

Agent Skills とは

Agent Skills は、AI コーディングエージェントに専門知識とワークフローを与える軽量なオープンフォーマットです。スキルの実体は SKILL.md を含むフォルダで、SKILL.md は最低限 name と description のメタデータとエージェントへの手順を持ちます。スクリプト・リファレンス・テンプレートなどの補助ファイルをフォルダに同梱できます。

my-skill/
├── SKILL.md          # 必須: メタデータ + 手順
├── scripts/          # 省略可: 実行スクリプト
├── references/       # 省略可: 参照ドキュメント
└── assets/           # 省略可: テンプレート・リソース

エージェントはスキルを段階的に読み込みます。Discovery では name と description だけを読み、タスクと一致したときに SKILL.md 全体を読み込み、実行時に references/ 内のファイルを必要なだけ参照します。この段階的読み込みにより、コンテキストウィンドウの消費を最小化します。

mcp-server-dev プラグインの位置づけ

mcp-server-dev は Anthropic が公開した公式プラグインで、MCP サーバー開発に特化した 3 つのスキルを composing 構造で提供します。

各スキルは SKILL.md と、認証フロー・ツール設計パターン・ウィジェットテンプレート・マニフェストスキーマなどの補助資料を収めた references/ フォルダを持ちます。スキルファイルはオープンフォーマットに従い、標準を実装する任意のエージェントで動作します。

MCP サーバー開発では、transport の選定・認証フローの設計・配布形態の決定・ツールパターンの選択といった設計判断を早い段階で誤ると、後から大規模な書き直しが必要になります。mcp-server-dev はこれらの設計判断をスキルに符号化し、エージェントがユースケースを問診してから最適なサーバーを足場化します。

従来手法との対比

特徴

• 3 スキルの composing 構造: build-mcp-server がエントリポイントとして問診と経路決定を担い、必要に応じて build-mcp-app または build-mcpb へハンドオフします。各スキルは独立して動作しつつ、組み合わせて完全なビルドパスを構成します。
• Discovery-first（コード生成より問診を優先）: 接続先・利用者・操作数・UI 要件・認証の 5 点を確認してから足場を生成します。開発序盤の誤った transport 選定による書き直しを防ぎます。
• 4 つのデプロイ経路へのルーティング: Remote Streamable HTTP（クラウド API ラッパーの既定）・MCP app（リッチ UI が必要な場合）・MCPB（ローカルマシン操作が必要な場合）・Local stdio（プロトタイプ用）を体系化し、問診結果に基づいて 1 つを推奨します。
• オープンフォーマットでエージェント非依存: Agent Skills の仕様は公開されており、Claude Code 以外のエージェントでも同一スキルを利用できます。ベンダーロックインなしにスキルを共有・再利用できます。
• references/ のオンデマンド読み込み: 認証フロー・ツール設計パターン・ウィジェットテンプレート・マニフェストスキーマなどはメインの SKILL.md に含めず references/ に分割します。エージェントは必要なときだけ参照ファイルを読み込み、コンテキストウィンドウを無駄に消費しません。
• ツール設計パターンの符号化: 操作数が少ない場合は 1 操作 1 ツール、操作数が多い大規模 API では search + execute パターンを推奨する知識を組み込んでいます。ツール記述の品質がモデルのコンテキスト使用効率に直結するという観点を初期設計から織り込んでいます。
• Claude 固有制約への対応: MCP 仕様は汎用ですが、Claude には追加の認証タイプ・レビュー基準・制限があります。エントリスキルはビルド開始前に Claude のコネクタドキュメント（https://claude.com/docs/llms-full.txt）をフェッチし、Claude 固有の制約をガイダンスに反映します。

構造

C4 model の 3 段階で、プラグインとエージェントと生成される MCP サーバーの関係を図解します。

システムコンテキスト図

コンテナ図

Plugin サブグラフ内の要素

スキル間のハンドオフ関係

コンポーネント図

Phase 別の要素

データ

概念モデル

Plugin と Skills

MCP Server と Primitives

デプロイ・設計・認証の種別

情報モデル

構築方法

前提条件

インストール: Claude Code プラグイン経由

/plugin marketplace add anthropics/claude-plugins-official
/plugin install mcp-server-dev

インストール後、build-mcp-server・build-mcp-app・build-mcpb の 3 スキルが使えるようになります。

インストール: 他エージェント向け（clone）

Claude Code 以外のエージェントを使う場合は、スキルディレクトリを直接 clone して配置します。

git clone https://github.com/anthropics/claude-plugins-official.git

plugins/mcp-server-dev/skills/ 配下の各スキルディレクトリ（SKILL.md + references/）を、対象エージェントのスキル配置場所にコピーします。スキルファイルは特定のエージェントに依存しないオープンフォーマットです。

利用方法

必須パラメータ一覧（Discovery フェーズで確定する設計判断）

エージェントへの依頼

スキルインストール後、自然文で依頼します。エントリスキル build-mcp-server が自動的に起動します。

「MCP サーバーを作って。GitHub Issues API をラップしたい」

Discovery フェーズ: 5 つの設問

エージェントは以下の 5 問を 1 メッセージにまとめて問いかけます。すでに情報が揃っている場合はスキップして推奨に進みます。

1. 接続先 — クラウド API か、ローカルプロセス・ファイルシステム・ハードウェアか
2. 利用者 — 自分・チームのみか、配布するか
3. アクション数 — 15 未満なら one-per-action、数十〜数百なら search + execute
4. UI 要否 — Elicitation の平坦なフォームで足りるか、リッチな Widget が要るか
5. 認証 — なし、API キー、OAuth 2.0 の別

4 経路への振り分けと Scaffold

経路 1: Remote Streamable-HTTP（デフォルト推奨）

クラウド API をラップする場合の標準経路です。ホストしたサーバーの URL を登録するだけでユーザーが使えます。

TypeScript SDK（@modelcontextprotocol/sdk）の最小サーバー

npm install @modelcontextprotocol/sdk zod express

// src/server.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import express from "express";
import { z } from "zod";

const server = new McpServer(
  { name: "my-service", version: "0.1.0" },
  { instructions: "Prefer search_items before calling get_item directly — IDs aren't guessable." },
);

server.registerTool(
  "search_items",
  {
    description: "Search items by keyword. Returns up to `limit` matches ranked by relevance.",
    inputSchema: {
      query: z.string().describe("Search keywords"),
      limit: z.number().int().min(1).max(50).default(10),
    },
    annotations: { readOnlyHint: true },
  },
  async ({ query, limit }) => {
    const results = await upstreamApi.search(query, limit);
    return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
  },
);

const app = express();
app.use(express.json());
app.post("/mcp", async (req, res) => {
  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
  res.on("close", () => transport.close());
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});
app.listen(process.env.PORT ?? 3000);

Python FastMCP 3.x（fastmcp on PyPI）の最小サーバー

FastMCP 3.x は jlowin が開発するパッケージです。公式 mcp SDK に同梱の FastMCP 1.0 とは別物です。

# server.py
from fastmcp import FastMCP

mcp = FastMCP(
    name="my-service",
    instructions="Prefer search_items before calling get_item directly — IDs aren't guessable.",
)

@mcp.tool(annotations={"readOnlyHint": True})
def search_items(query: str, limit: int = 10) -> list[dict]:
    """Search items by keyword. Returns up to `limit` matches ranked by relevance."""
    return upstream_api.search(query, limit)

if __name__ == "__main__":
    mcp.run(transport="http", host="0.0.0.0", port=3000)

FastMCP は型ヒントから JSON スキーマを自動生成します。docstring がそのまま Claude のコンテキストに入るため、端的な動詞句で書きます。

Cloudflare Workers への 2 コマンドデプロイ

SKILL.md では Cloudflare Workers が「最速デプロイ経路」と位置づけられています。Workers ネイティブの scaffold を使い、2 コマンドで無料枠の https:// URL が得られます。これは Express scaffold とは別のランタイムです。

# Workers ネイティブ scaffold を生成
npm create cloudflare@latest -- my-mcp-server \
  --template=cloudflare/ai/demos/remote-mcp-authless

# テンプレートのツールを差し替えてデプロイ
cd my-mcp-server && npx wrangler deploy

上流 API キーは npx wrangler secret put UPSTREAM_API_KEY で登録し、env.UPSTREAM_API_KEY から読みます。OAuth が必要な場合は @cloudflare/workers-oauth-provider（CIMD/DCR エンドポイント・トークン発行・同意 UI を扱う drop-in）を使います。

経路 2: Elicitation（ツール実行中の構造化入力）

ユーザーへの確認・選択・短いフォーム入力が必要な場合に使います。HTML/iframe を一切書かずに済む、スペックネイティブな手法です。サーバーが平坦な JSON スキーマを送り、ホストがネイティブフォームをレンダリングします。

capability check + fallback の canonical パターン

server.registerTool("delete_all", {
  description: "Delete all items after confirmation",
  inputSchema: {},
}, async ({}, extra) => {
  const caps = server.getClientCapabilities();
  if (caps?.elicitation) {
    const r = await server.elicitInput({
      mode: "form",
      message: "Delete all items? This cannot be undone.",
      requestedSchema: {
        type: "object",
        properties: { confirm: { type: "boolean", title: "Confirm deletion" } },
        required: ["confirm"],
      },
    });
    if (r.action === "accept" && r.content?.confirm) {
      await deleteAll();
      return { content: [{ type: "text", text: "Deleted." }] };
    }
    return { content: [{ type: "text", text: "Cancelled." }] };
  }
  // Fallback: Claude 経由でユーザーに確認を中継させる
  return { content: [{ type: "text", text: "Confirmation required. Please ask the user to confirm, then call this tool again with their answer." }] };
});

Elicitation はホストサポートが新しい機能です。必ず clientCapabilities.elicitation を確認してから呼び出し、非対応ホスト向けの fallback を用意します。SDK はクライアントが capability を広告していない場合に例外を throw します。パスワード・API キー・トークンの取得には使えません（spec 要件）。

経路 3: MCP App（リッチ UI Widget）

Elicitation の平坦なフォームでは表現できない場合（大量の選択肢スクロール、チャート、ライブ更新など）に使います。エージェントは build-mcp-app スキルへ委譲します。Widget は Remote HTTP サーバーと MCPB の両方に対応します。

経路 4: MCPB（バンドル型ローカルサーバー）

サーバーがユーザーのマシン上で動作しなければならない場合（ローカルファイル読み書き、デスクトップアプリ操作、localhost サービスへのアクセス）に使います。エージェントは build-mcpb スキルへ委譲します。ユーザーが Node/Python をインストールせずに使えるよう、ランタイムごとバンドルした .mcpb アーカイブを生成します。

# Node の場合のビルドとパック
npx esbuild src/index.ts --bundle --platform=node --outfile=server/index.js
npx @anthropic-ai/mcpb pack

mcpb pack はディレクトリを zip 化し、manifest.json をスキーマに対して検証します。

フレームワーク選択（TS SDK と FastMCP 3.x）

どちらも同一の wire プロトコルを生成します。既存のスタックに合わせて選びます。

ツール設計の書き方（one-per-action パターン）

ツール説明はそのまま Claude のコンテキストに入ります。プロンプトエンジニアリングとして書きます。

server.registerTool(
  "search_issues",
  {
    description:
      "Search issues by keyword across title and body. Returns up to `limit` results ranked by recency. " +
      "Does NOT search comments or PRs — use search_comments / search_prs for those.",
    inputSchema: {
      query: z.string().describe("Keywords to search for. Supports quoted phrases."),
      status: z.enum(["open", "closed", "all"]).default("open")
        .describe("Filter by status. Use 'all' to include closed items."),
      limit: z.number().int().min(1).max(50).default(10)
        .describe("Max results. Hard cap at 50."),
    },
    annotations: { readOnlyHint: true },
  },
  async ({ query, status, limit }) => {
    const results = await api.searchIssues({ query, status, limit });
    return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
  },
);

ツール定義の要点は次のとおりです。

• description は「何をするか」「何を返すか」「何をしないか」の 3 点を含めます
• 類似ツールが並ぶ場合、各 description に「こちらではなく X を使う状況」を明記します
• パラメータは .describe() で説明文を必ず付けます

ツールアノテーションはホストの権限 UI の挙動を制御します。

運用

テスト — MCP Inspector

MCP Inspector は npx で即時起動できるインタラクティブなデバッグツールです。

# ローカル開発中サーバーを検査 (TypeScript)
npx @modelcontextprotocol/inspector node path/to/server/index.js

# ローカル開発中サーバーを検査 (Python)
npx @modelcontextprotocol/inspector uv --directory path/to/server run <package-name>

テスト — Claude へのカスタムコネクタ登録

MCP Inspector でプロトコル準拠を確認した後、実際の Claude でエンドツーエンドテストを行います。

• 登録場所: Settings → Connectors → Add custom connector
• ローカルサーバーは Cloudflare Tunnel または ngrok で公開 URL を作成してから登録する
• カスタムコネクタはディレクトリ公開コネクタと同一インフラで動作する

# Cloudflare Tunnel でローカルサーバーを公開 (例: ポート 3000)
cloudflared tunnel --url http://localhost:3000

Claude がサーバーを識別する際に送る clientInfo.name は、サーフェスによって "claude-ai" などに変わります。認可処理にこの値を使ってはなりません。分析や機能検出の補助情報として使います。

公開 — Anthropic Directory への Submit

事前準備としてドキュメント URL・プライバシーポリシー URL（ローカルコネクタは必須）・サーバーアイコン・テスト用アカウント資格情報を揃えます。MCP App 提出時はカルーセルスクリーンショット（3〜5 枚、幅 1000px 以上）が必要です。

提出経路はサーバー種別で分かれます。

• リモート MCP サーバー / MCP App: 提出ポータル（Team / Enterprise 組織が必要）
• 個人プラン: MCP directory submission form
• Desktop extension（MCPB）: desktop extension submission form

提出ポータルでは接続情報・ツール同期・リスティング・ユースケース・認証・データ取り扱い・コンプライアンス確認を経て、最終レビューで品質警告が表示されます。問い合わせ先は mcp-review@anthropic.com です。

公開後の更新

Plugin + Skills の同梱（推奨）

MCP サーバーと Plugin は補完関係にあり、多くのパートナーが両方を ship しています。MCP サーバーは全サーフェスで動作するツールサーフェスを提供し、Plugin は Skills とコネクタ参照をバンドルした配布パッケージです。Claude Code の marketplace 配布では Plugin が実質的な配布単位になります。一方、他エージェント向けには SKILL.md + references/ のスキルディレクトリを直接配置する経路もあります。

ベストプラクティス

デプロイモデル選択指針

クラウド API をラップする、または複数ユーザーに配布する
  → Remote HTTP (デフォルト推奨)

ユーザーのローカルファイル・デスクトップアプリ・OS API が必要
  → MCPB

個人用プロトタイプ・チーム内ツール
  → Local stdio (MCPB へのアップグレードパスを保持)

Remote HTTP は、ゼロインストールフリクション・1 回デプロイで全ユーザーへ反映・OAuth フローが正常に機能・全サーフェスで動作、という理由でデフォルト推奨です。

ツール設計

tool-design.md はツール数で 3 段階に切り分けます。

読み取りと書き込みはツールを分割し、読み取りには readOnlyHint: true、破壊的操作には destructiveHint: true を設定します。Claude が繰り返しツールを誤用する場合は、サーバーの instructions に修正指示を書くのが最も効果的です。

認証セキュリティ

• トークンオーディエンス検証（spec MUST / RFC 8707）: 署名が有効でも、当該サーバー向けに発行されたトークンでなければ拒否します。api.other-service.com 向けのトークンは受け入れてはなりません。
• トークンパススルーは明示的に禁止: 受け取ったトークンをそのままアップストリームに転送してはなりません。トークン交換かサーバー自身のクレデンシャルを使います。
• コールバック URL（全サーフェス共通）: https://claude.ai/api/mcp/auth_callback

DCR は接続ごとにクライアント登録が走るため、高トラフィックなディレクトリ掲載には CIMD を優先します。

MCPB ローカルセキュリティ

MCPB はサンドボックスを持ちません。マニフェストに permissions ブロックは存在せず、サーバープロセスはユーザー権限でフルアクセスできます。ツールハンドラーが唯一の防壁です。

パストラバーサル対策（必須）:

import { resolve, relative, isAbsolute } from "node:path";

function safeJoin(root: string, userPath: string): string {
  const full = resolve(root, userPath);
  const rel = relative(root, full);
  if (rel.startsWith("..") || isAbsolute(rel)) {
    throw new Error(`Path escapes root: ${userPath}`);
  }
  return full;
}

String.includes("..") では不十分です。エンコードやシンボリックリンクを使った迂回に対応するため、必ず resolve + relative で確認します。

コマンドインジェクション対策: シェルを経由した引数渡しを避け、execFile("git", ["log", branch]) のように argv を配列で構築します。exec() / shell=True は使いません。

リソース上限: ファイル読み取り・ディレクトリ列挙・検索結果など、すべての unbounded 処理に上限を設けます。

MCP App の Abuse Protection

• エンドポイントにレートリミットと IP ティアリングを実装する
• iframe の CSP を維持する（CDN からのスクリプトインポートはブロックされる）
• 外部リンクは app.openLink 経由で開く（window.open はサンドボックスでブロックされる）
• 画像は iframe CSP がリモート img-src をブロックするため、サーバー側でフェッチして data: URL として埋め込む

バージョン固定の管理

バージョン固定値は時間経過で陳腐化します。versions.md の台帳を定期レビューし、コマンドで現在値を確認してから更新します。

npm view @modelcontextprotocol/ext-apps version
gh api repos/cloudflare/ai/contents/demos/remote-mcp-authless/src/index.ts --jq '.sha'
curl -sI https://raw.githubusercontent.com/anthropics/mcpb/main/schemas/mcpb-manifest-v0.4.schema.json | head -1

固定値は履歴台帳の値です。scaffold で利用する際は上記コマンドで現在の npm / GitHub 値を確認してから採用します。

トラブルシューティング

まとめ

MCP 公式の mcp-server-dev プラグインは、デプロイモデル・ツール設計・認証・配布形態という設計判断を 3 つの Agent Skill に符号化し、エージェントがユースケースを問診してから MCP サーバーを足場化します。MCP サーバー開発は「API を LLM に開く」作業から、4 経路の選択と認証・配布の設計を含む対象へと位置づけが変わりました。

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNSでのシェアをいただけると励みになります！

参考リンク

一次情報（MCP / Agent Skills 公式）

• Build with Agent Skills（MCP 公式）
• mcp-server-dev プラグイン（GitHub）
• mcp-server-dev skills ディレクトリ
• Agent Skills
• MCPB（GitHub）

ツール・テスト

• MCP Inspector ドキュメント
• MCP Inspector（GitHub）

Claude コネクタ構築

• Authentication
• Testing
• Review criteria
• Submission
• What to build