MCPサーバーオーサリング

TypeScriptまたはPythonでMCPサーバーをビルドし、任意のMCP互換クライアントで利用できるようにします。

いつ使うか

• Claude Desktop / Claude Code / Cursorに内部APIまたはツールを公開したい
• 共有可能なMCPサーバーをビルドしている(npm、PyPI、またはSmitheryレジストリ)
• 読み取り専用のデータソースをMCPリソースとしてラップする必要がある
• エージェントがクライアントごとのカスタムグルーコードなしであなたのサービスを呼び出す必要がある

コアモデル

MCPサーバーは3つのプリミティブを公開します:

プリミティブ	目的	副作用
Tool	エージェントが呼び出すアクション	副作用がある可能性(書き込み、ネットワーク呼び出し)
Resource	エージェントが読む取得するデータ	読み取り専用、URIでアドレス指定
Prompt	再利用可能なプロンプトテンプレート	副作用なし、ユーザー呼び出し可能

正しいプリミティブを選択してください — 読み取り操作をツールとして公開するとリソースとするべき時にコンテキストを無駄にします。

クイックスタート — TypeScript (stdio)

npm init -y
npm i @modelcontextprotocol/sdk zod
npm i -D typescript tsx @types/node

// 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: "weather-server",
  version: "1.0.0",
});

server.tool(
  "get_forecast",
  "Get a weather forecast for a location",
  {
    location: z.string().describe("City name or lat,lng"),
    days: z.number().int().min(1).max(14).default(3),
  },
  async ({ location, days }) => {
    const data = await fetchForecast(location, days);
    return {
      content: [{ type: "text", text: JSON.stringify(data) }],
    };
  },
);

server.resource(
  "station",
  "weather://stations/{id}",
  async (uri) => {
    const id = uri.pathname.split("/").pop()!;
    const station = await fetchStation(id);
    return {
      contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(station) }],
    };
  },
);

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

実行してクライアントのmcp.jsonに登録します:

{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": ["-y", "tsx", "src/server.ts"]
    }
  }
}

クイックスタート — Python (stdio)

uv add "mcp[cli]"

# server.py
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("weather-server")

@mcp.tool()
async def get_forecast(location: str, days: int = 3) -> dict:
    """Get a weather forecast for a location."""
    return await fetch_forecast(location, days)

@mcp.resource("weather://stations/{id}")
async def station(id: str) -> dict:
    return await fetch_station(id)

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

ツールコントラクトルール

1. 名前: snake_case、動詞主導(search_issuesでIssueSearcherではなく)
2. 説明: 1文、動詞で始まる、主要な引数に言及
3. スキーマ: Zod / Pydanticを使用し、すべてのフィールドで記述的な.describe()を使用
4. 戻り値の形状: 常に{ content: [{ type: "text", text: ... }] } — JSONをテキストとしてラップ
5. エラー: スロー — SDKがisError: trueに変換します。メッセージに修復方法を含める
6. べき等性: 書き込みツールは可能な限りidempotency_keyを受け付けるべき

プログレッシブディスクロージャーパターン

40個のツールをクライアントにダンプしないでください。小さく安定したサーフェスを公開し、ツールにフォローアップハンドルを返させます:

server.tool("list_projects", "List accessible projects", {}, async () => {
  const projects = await api.listProjects();
  return {
    content: [{
      type: "text",
      text: `Found ${projects.length} projects. Use get_project with id to read one:\n` +
            projects.map(p => `- ${p.id}: ${p.name}`).join("\n"),
    }],
  };
});

テスト

開発中はMCP Inspectorを使用します:

npx @modelcontextprotocol/inspector tsx src/server.ts

すべてのツールを呼び出し、すべてのリソースを検査し、プロンプトをリプレイするUIが提供されます。モックバックエンドに対してCIで実行してスキーマリグレッションを検出します。

公開

• npm: サーバーをbinエントリとして公開すると、ユーザーはnpx your-mcp-serverを実行できます
• Smitheryレジストリ: ワンクリックインストールのために設定スキーマ付きのsmithery.yamlを追加
• プライベート: Dockerイメージとして配布し、commandをdocker runにポイント

ベストプラクティス

1. ツールサーフェスを≤15ツールに保つ — より多いとモデル選択精度が低下
2. バイナリではなくテキストを返す — 大きなペイロードの場合はURIを使用したリソースを使用
3. server.sendNotificationプログレスイベント経由で長時間実行ツールをストリーム
4. 破壊的変更を行う場合はサーバーのnameサフィックスをバージョン管理(github-v2)
5. ツール呼び出し時に環境変数からシークレットを読み込まない — 起動時に読み込んで高速失敗
6. すべてのツール呼び出しをサーバー側でログ — エージェントの動作は予測不可能で、監査証跡が必要になります