MCP ガイド
Model Context Protocol を使う・作る

30秒で理解する MCP

• Host: Claude Code、Claude Desktop、Cursor、Zed などクライアント側アプリ
• Server: データ・API・ツールを MCP 経由で公開する側。誰でも自作可
• Protocol: JSON-RPC 2.0 を基盤。トランスポートは stdio / Streamable HTTP / SSE から選択

ユースケース早見表

Demo.MCP がある生活、ない生活

同じ依頼をしたときに、会話がどう変わるか。実際の Claude Code のやりとりを並べてみます。

Gallery.アイデアギャラリー — こんな MCP があると人生が変わる

既存の公式サーバーと自作アイデアのミックス。「こういうのが欲しい → じゃあ作ろう」の火種を集めました。毎日 3 回以上コピペしているワークフローがあれば、それが最高の MCP 候補です。

Part 1.なぜ MCP が必要か

問題 → 解決: 組み合わせ爆発を標準化で潰す

LLM から外部システム（GitHub、Slack、社内 DB、ファイルシステム…）を使いたいとき、各アプリが各 API の接続コードを個別に書くと アプリ数 × サービス数 の実装が必要になります。MCP は「LLM ホスト ↔ ツール提供者」間の標準インターフェースを規定し、サーバーを 1 つ書けば対応する任意のホストから使えるようにします。

API 直接呼び出しとの違い

全体アーキテクチャ

登場人物

プロトコル層

1. トランスポート

2. メッセージ層

JSON-RPC 2.0 に準拠。3 種類のメッセージ：

• Request: ID 付きで応答を要求（tools/list, tools/call など）
• Response: Request に対する結果またはエラー
• Notification: ID なしの一方通行（ログ、進捗通知など）

3. ライフサイクル

3つのプリミティブ

MCP サーバーは以下のいずれか／複数を提供します。

Tools — 能動的な関数

LLM が「呼び出す」関数。副作用を伴う操作にも使える（ファイル書き込み、API POST など）。

• 例: github_create_issue(title, body), query_database(sql)
• ホスト側で「ユーザー承認を毎回求める／自動承認」が選べる
• JSON Schema でパラメータを記述

Resources — 受動的なデータ

URI でアクセス可能な読み取り専用データ。LLM またはユーザーが参照する。

• 例: file:///path/to/file.py, github://issues/123, postgres://table/users
• LLM が自発的に読むより、ホスト UI から「コンテキストに追加」する使い方が主流
• 動的一覧提供（resources/list）と個別取得（resources/read）

Prompts — テンプレート

ユーザーが明示的に呼び出す会話テンプレート。スラッシュコマンド的な使い方。

• 例: /review-pr, /summarize-issue
• 引数付きテンプレート。実行時にサーバー側で展開される
• Claude Code / Cursor などでは「スラッシュコマンド」として表示される

どれを使うべきか

機能ネゴシエーション

Initialize 時に Client と Server が互いの能力（capabilities）を交換します。サーバー側の例：

{
  "capabilities": {
    "tools": { "listChanged": true },
    "resources": { "subscribe": true, "listChanged": true },
    "prompts": { "listChanged": true },
    "logging": {}
  }
}

• listChanged: ツール/リソース一覧が動的に変わる場合、notifications/tools/list_changed を送れる
• subscribe: クライアントがリソース変更購読可能（ファイル監視など）

これにより、古いクライアントと新しいサーバーの組み合わせでも機能の有無を動的に判定できます。

セキュリティモデル

MCP 自体はプロトコルであり、ホストが権限管理の責任を負う設計です。

• ユーザー承認: 各 tool 呼び出しについて、ホストがユーザーに確認を取るのが標準
• スコープ分離: トークンや API キーはサーバープロセスに閉じる（Client/Host には渡さない）
• プロセス境界: stdio サーバーは独立プロセスなのでメモリ分離される
• 信頼できないサーバー: 第三者サーバーを入れる前にコードを確認する習慣を

関連用語集

Part 2.ホスト別の接続

既存の MCP サーバーを、どこに繋ぐかを整理します。

Claude Code で MCP サーバーを使う

登録方法 3 種

① claude mcp add コマンド（推奨）

対話的に最速で追加：

# stdio（ローカルコマンド起動型）
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/allow

# HTTP リモート
claude mcp add --transport http my-remote-server https://api.example.com/mcp

# SSE リモート
claude mcp add --transport sse my-legacy-server https://api.example.com/sse

スコープ指定：

claude mcp add --scope user    github ...  # ~/.claude.json に保存。全プロジェクトで有効
claude mcp add --scope project github ...  # .mcp.json に保存。チーム共有可能
claude mcp add --scope local   github ...  # プロジェクトの local settings。自分だけ

② .mcp.json を手書き（プロジェクト共有）

プロジェクトルートに置けば、そのリポジトリをクローンした全員で同じ MCP が使える：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "command": "uvx",
      "args": ["mcp-server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

環境変数展開は ${VAR} 記法。.env ローダーではないので、シェルや OS の環境変数として事前に設定しておく。

③ settings.json の mcpServers キー

~/.claude.json または ~/.claude/settings.json に直接書く。Claude Code が全プロジェクトで読み込む。

接続状態の確認

claude mcp list           # 登録済みサーバー一覧
claude mcp get github     # 特定サーバーの設定詳細
claude mcp remove github  # 削除

セッション中の接続確認は Claude に聞くのが早い：

/mcp

ツール呼び出しの許可

MCP サーバーのツールは既定で「毎回承認を求める」。自動承認したい場合は settings.json の permissions：

{
  "permissions": {
    "allow": [
      "mcp__github__search_issues",
      "mcp__filesystem__read_file"
    ]
  }
}

命名規則: mcp__<server_name>__<tool_name>。信頼度の高いツールだけ許可するのが安全。

起動時の挙動

• stdio サーバー: Claude Code がセッション開始時にサブプロセスとして起動、セッション終了時に停止
• HTTP サーバー: 初回接続時にハンドシェイク、以降は都度リクエスト

# macOS / Linux
export GITHUB_TOKEN=github_pat_xxxxxxxxxxxx

# Windows PowerShell
$env:GITHUB_TOKEN = "github_pat_xxxxxxxxxxxx"

claude mcp add github \
  --env GITHUB_PERSONAL_ACCESS_TOKEN=$GITHUB_TOKEN \
  -- npx -y @modelcontextprotocol/server-github

Claude Desktop の場合

claude_desktop_config.json を編集：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

構造は Claude Code の .mcp.json とほぼ同じ：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/Documents"]
    }
  }
}

編集後は Claude Desktop を再起動。接続状態は画面左下のコンセントアイコン（🔌）から確認できる。

API アプリに組み込む

Python（anthropic-sdk）

from anthropic import Anthropic

client = Anthropic()
response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    mcp_servers=[
        {
            "type": "url",
            "url": "https://mcp.example.com/server",
            "name": "my-server",
            "authorization_token": "Bearer ..."
        }
    ],
    messages=[{"role": "user", "content": "Search issues about login bug"}]
)

サーバー側の tools/resources が自動的に使える状態になる。サーバーからの tool_use はそのまま Claude の tool_use ブロックとして返ってくる。

TypeScript（@anthropic-ai/sdk）

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();
const response = await client.beta.messages.create({
  model: "claude-sonnet-4-5",
  max_tokens: 1024,
  mcp_servers: [{
    type: "url",
    url: "https://mcp.example.com/server",
    name: "my-server",
    authorization_token: `Bearer ${token}`
  }],
  messages: [{ role: "user", content: "..." }]
});

代表的な公式サーバーと導入例

npx -y @modelcontextprotocol/server-* でほぼ全部試せる。

運用：権限・シークレット・監査

シークレットの取り扱い

• .mcp.json に生の API キーを書かない。必ず環境変数経由 (${VAR}) にする
• .mcp.json を git に入れるなら、トークンはホストごとに各自が設定する前提で書く
• 個人用トークンが必要なら --scope user または --scope local を使う

最小権限

• Filesystem server: 公開するルートパスを絞る（/Users/me/Documents ではなく /Users/me/Documents/project-x）
• GitHub PAT: fine-grained token でリポジトリと scope を絞る
• DB: 可能なら読み取り専用ロールを使う

ログとデバッグ

Claude Code をデバッグモード起動：

claude --debug

MCP サーバー側のログを直接見るには、stdio なら stderr が標準。多くのサーバーはログレベル指定可。

LOG_LEVEL=debug python my_server.py

MCP Inspector

公式ツール。任意の MCP サーバーに接続して tools/resources を GUI で呼べる：

npx @modelcontextprotocol/inspector npx -y @modelcontextprotocol/server-filesystem /tmp

ブラウザが開き、tools の一覧・JSON Schema・手動実行ができる。自作サーバーのテストにも便利。

トラブルシューティング

サーバーが起動しない

1. コマンド単体で叩いて確認

   npx -y @modelcontextprotocol/server-filesystem /tmp

   JSON-RPC 初期化メッセージが標準出力に出れば OK。
2. パスの絶対化: claude_desktop_config.json は ~ を展開しない。絶対パスを書く。
3. Windows のパス: バックスラッシュはエスケープ "C:\\Users\\me\\..." または forward slash "C:/Users/me/..."。
4. npx のキャッシュ破損: npx --yes を付けるか、npx clear-npx-cache（v6 以前）。

ツールが Claude に認識されない

1. /mcp でサーバー接続確認
2. 接続はしているが tools がゼロ → サーバー側の capabilities.tools または tools/list を要確認
3. claude --debug で initialize 応答を見る

認証エラー

• 環境変数が展開されていない: シェルに設定したか、ホスト再起動したか
• OAuth サーバー: リダイレクト URL 登録や有効期限（多くは 1 時間）を確認

動作が遅い

• stdio の初回起動コスト: npx は毎回パッケージダウンロード確認が走る。npm i -g で固定するか、uvx / pipx で仮想環境キャッシュ利用
• HTTP サーバー: ネットワーク往復。tools/list の結果はホストがキャッシュするので、起動後の遅さはサーバー側の実装問題

command not found 系

Node / Python ランタイムが PATH に無い。GUI アプリ（Claude Desktop）は .bashrc の PATH を読まないので、OS レベルの PATH に登録するか、command をフルパスで書く：

{
  "command": "/usr/local/bin/npx",
  "args": ["..."]
}

Part 3.作るべきか：判断基準

MCP サーバーを自作する前に、以下を確認：

• 公式サーバー（@modelcontextprotocol/servers）に同等のものがないか
• ラップしたい API は LLM から呼ぶ価値があるか（情報量 / 操作性）
• 既存の CLI / スクリプトで十分ではないか（Claude Code は Bash が既に使える）

MCP を使うべき典型は：

1. 複雑な認証が必要な外部 API（OAuth / 署名リクエスト）
2. 構造化された結果が欲しい（テキスト出力より JSON を返したい）
3. 複数ホストで再利用したい（Claude Code / Desktop / Cursor 共通）
4. 社内ツールを標準プロトコルで公開したい

技術選定

SDK 選択

迷ったら Python FastMCP が最速。TS は配布と型の両立が強み。

トランスポート選択

Python で作る：FastMCP

セットアップ

mkdir my-mcp && cd my-mcp
uv init
uv add "mcp[cli]"

pyproject.toml の一例：

[project]
name = "my-mcp"
version = "0.1.0"
dependencies = ["mcp[cli]>=1.0"]

[project.scripts]
my-mcp = "my_mcp:main"

最小サーバー（stdio）

# src/my_mcp/__init__.py
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-mcp")

@mcp.tool()
def add(a: int, b: int) -> int:
    """2 つの整数の和を返す."""
    return a + b

@mcp.tool()
def greet(name: str, formal: bool = False) -> str:
    """挨拶を返す.

    Args:
        name: 相手の名前
        formal: True なら丁寧語
    """
    if formal:
        return f"お世話になっております、{name} 様"
    return f"Hi {name}!"

def main():
    mcp.run()  # 既定は stdio

if __name__ == "__main__":
    main()

起動：

uv run my-mcp
# もしくは
python -m my_mcp

Claude Code から使う場合の .mcp.json：

{
  "mcpServers": {
    "my-mcp": {
      "command": "uv",
      "args": ["--directory", "/abs/path/to/my-mcp", "run", "my-mcp"]
    }
  }
}

Resources を追加

@mcp.resource("config://app")
def get_config() -> str:
    """アプリ設定の JSON."""
    return '{"theme": "dark", "lang": "ja"}'

@mcp.resource("user://{user_id}/profile")
def get_user_profile(user_id: str) -> str:
    """ユーザープロフィール（テンプレート URI）."""
    return fetch_profile_from_db(user_id)

Prompts を追加

@mcp.prompt()
def review_code(language: str, code: str) -> str:
    """コードレビュー用プロンプト."""
    return f"以下の {language} コードをレビューしてください:\n\n```{language}\n{code}\n```"

型と Schema

FastMCP は Python の型ヒントから JSON Schema を自動生成する。複雑な入出力は Pydantic モデルを使う：

from pydantic import BaseModel, Field

class SearchResult(BaseModel):
    title: str
    url: str
    score: float = Field(ge=0, le=1, description="関連度 0-1")

@mcp.tool()
def search(query: str, limit: int = 10) -> list[SearchResult]:
    """検索を実行."""
    ...

コンテキスト（進捗・ログ・サンプリング）

from mcp.server.fastmcp import Context

@mcp.tool()
async def process_files(files: list[str], ctx: Context) -> str:
    """ファイル群を処理する."""
    for i, f in enumerate(files):
        await ctx.info(f"Processing {f}")
        await ctx.report_progress(i + 1, len(files))
        # 重い処理
    return f"Done: {len(files)} files"

• ctx.info / debug / warning / error: クライアントにログ送信
• ctx.report_progress: 進捗通知
• ctx.sample: サーバーからホストの LLM に推論を依頼（高度機能）

HTTP サーバーとして動かす

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

エンドポイント: http://localhost:8080/mcp。Claude Code から接続：

claude mcp add --transport http my-mcp http://localhost:8080/mcp

mkdir notes-mcp && cd notes-mcp
uv init
uv add "mcp[cli]"
mkdir -p src

[project]
name = "notes-mcp"
version = "0.1.0"
dependencies = ["mcp[cli]>=1.0"]

[project.scripts]
notes-mcp = "notes_mcp:main"

[tool.uv]
package = true

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["src/notes_mcp"]

import os
from pathlib import Path
from mcp.server.fastmcp import FastMCP

VAULT = Path(os.environ.get("VAULT_PATH", "~/notes")).expanduser().resolve()
mcp = FastMCP("notes")


@mcp.tool()
def search_notes(query: str, limit: int = 10) -> list[dict]:
    """Vault 内の Markdown ファイルを全文検索する.

    使うべきとき:
        - 過去に書いたメモから特定のトピックを探したい
        - 複数のノートをまたいで関連内容を集めたい

    Args:
        query: 検索語（大文字小文字区別なし、完全一致）
        limit: 最大結果件数（1-50、デフォルト 10）

    Returns:
        マッチしたメモのリスト。各要素は:
            path: Vault root からの相対パス
            snippet: 検索語周辺 200 文字のコンテキスト
            size: ファイル全体のバイト数
    """
    results = []
    q = query.lower()
    for md_path in sorted(VAULT.rglob("*.md")):
        try:
            text = md_path.read_text(encoding="utf-8")
        except (UnicodeDecodeError, OSError):
            continue
        idx = text.lower().find(q)
        if idx == -1:
            continue
        start = max(0, idx - 80)
        end = min(len(text), idx + 120)
        snippet = text[start:end].replace("\n", " ").strip()
        results.append({
            "path": str(md_path.relative_to(VAULT)),
            "snippet": f"…{snippet}…",
            "size": len(text),
        })
        if len(results) >= limit:
            break
    return results


@mcp.tool()
def read_note(path: str) -> str:
    """指定したメモの全文を取得する.

    Args:
        path: Vault root からの相対パス（例: 'work/ideas.md'）

    Returns:
        ファイルの全文テキスト
    """
    full = (VAULT / path).resolve()
    # パス・トラバーサル対策: VAULT 外は拒否
    if not str(full).startswith(str(VAULT)):
        raise ValueError(f"Path outside vault: {path}")
    if not full.is_file():
        raise FileNotFoundError(
            f"Note not found: {path}. "
            f"Tip: まず search_notes で存在確認してください。"
        )
    return full.read_text(encoding="utf-8")


def main():
    mcp.run()


if __name__ == "__main__":
    main()

export VAULT_PATH=$HOME/notes
npx @modelcontextprotocol/inspector uv run notes-mcp

claude mcp add notes \
  --env VAULT_PATH=$HOME/notes \
  -- uv --directory $(pwd) run notes-mcp

TypeScript で作る

セットアップ

mkdir my-mcp && cd my-mcp
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node tsx
npx tsc --init

package.json:

{
  "name": "my-mcp",
  "version": "0.1.0",
  "type": "module",
  "bin": {
    "my-mcp": "./dist/index.js"
  },
  "scripts": {
    "build": "tsc",
    "dev": "tsx src/index.ts",
    "start": "node dist/index.js"
  }
}

最小サーバー（stdio）

// src/index.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: "my-mcp",
  version: "0.1.0",
});

server.registerTool(
  "add",
  {
    title: "Add",
    description: "2つの整数の和を返す",
    inputSchema: {
      a: z.number().int(),
      b: z.number().int(),
    },
  },
  async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }],
  })
);

server.registerTool(
  "greet",
  {
    title: "Greet",
    description: "挨拶を返す",
    inputSchema: {
      name: z.string(),
      formal: z.boolean().optional().default(false),
    },
  },
  async ({ name, formal }) => ({
    content: [{
      type: "text",
      text: formal ? `お世話になっております、${name} 様` : `Hi ${name}!`,
    }],
  })
);

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

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

Streamable HTTP トランスポート（TS）

import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import express from "express";

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

app.post("/mcp", async (req, res) => {
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: () => crypto.randomUUID(),
  });
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

app.listen(8080);

Tool の設計原則

ツールの良し悪しは LLM が正しく使えるかどうかで決まる。

1. 名前は動詞 + 目的語

• Good create_issue, search_users, list_repositories
• Bad issues, data, handler

2. description は「LLM へのドキュメント」

長さより情報密度。以下を含める：

• 何をするか
• いつ使うべきか（最重要。LLM は description を見てツール選択する）
• いつ使うべきでないか（類似ツールとの使い分け）
• 主要パラメータの意味
• 返り値の構造

@mcp.tool()
def search_issues(
    query: str,
    state: Literal["open", "closed", "all"] = "open",
    limit: int = 20,
) -> list[dict]:
    """GitHub issue を全文検索で探す.

    使うべきとき:
        - 過去の issue から特定のバグを探すとき
        - ラベル指定ではなく自由文で検索したいとき

    使うべきでないとき:
        - 特定 issue の詳細を取得する場合は `get_issue(number)` を使う
        - ラベルで絞りたい場合は `list_issues_by_label` を使う

    Args:
        query: GitHub search syntax に従うクエリ文字列
               (例: 'login bug label:P0 author:alice')
        state: 'open' / 'closed' / 'all' のいずれか
        limit: 最大結果件数（1-100）

    Returns:
        issue の dict のリスト。各要素は {number, title, state, labels, author, url}
    """

3. パラメータは最小限に

• 不要なオプションは削る。デフォルト値で済むなら省略可能に
• 列挙型は Literal / enum で固定（LLM の誤入力防止）
• ID と名前どちらでも受ける「寛容な API」より、片方に絞る方が LLM は迷わない

4. 返り値は構造化

• LLM が次の行動を決められるよう、必要な情報を構造化して返す
• エラーは例外で投げるか、エラーフィールドを持つ構造体で返す
• バイト列や巨大データは「参照 URI」で返し、必要時に resource 経由で取得

5. 冪等性と副作用

• 副作用のある tool には名前で示唆（create_, delete_, send_）
• 可能なら冪等にする（同じ引数で複数回呼んでも安全）
• 破壊操作は確認フラグ必須（confirm: bool）または dry_run モードを用意

6. エラーメッセージは改善の情報源

ユーザー向けではなく LLM 向けに書く。「次に何をすればよいか」を示唆：

raise ValueError(
    f"Issue #{number} not found. "
    f"Did you mean to search first with `search_issues`?"
)

認証

stdio の場合

環境変数で渡す。.mcp.json で：

{
  "env": {
    "API_KEY": "${MY_API_KEY}"
  }
}

サーバー側：

import os
API_KEY = os.environ["API_KEY"]

リモート MCP（Streamable HTTP）

A. API Key / Bearer Token

クライアントが Authorization: Bearer <token> をつけて送る。Claude Code の .mcp.json：

{
  "transport": "http",
  "url": "https://mcp.example.com/mcp",
  "headers": {
    "Authorization": "Bearer ${MY_TOKEN}"
  }
}

サーバー側は通常の Web アプリと同様にトークン検証。

B. OAuth 2.1（PKCE）

MCP 仕様は OAuth 2.1 + Dynamic Client Registration を推奨。ホスト（Claude など）がユーザーを OAuth 同意画面にリダイレクトし、得たトークンを各リクエストに付与する。SDK レベルでの対応状況はまだ進化中。公式サンプルを参照。

C. mTLS / 社内トークン

社内専用なら mTLS や独自ヘッダーでも可。ただし標準化されていないので、クライアント側の対応可否を要確認。

テスト

MCP Inspector

対話的 GUI。自作サーバーのデバッグに必須：

# stdio サーバー
npx @modelcontextprotocol/inspector uv run my-mcp

# HTTP サーバー
npx @modelcontextprotocol/inspector --transport http http://localhost:8080/mcp

tools/resources/prompts の一覧、スキーマ確認、手動実行、ログ確認が可能。

ユニットテスト（Python）

import pytest
from mcp.client.stdio import stdio_client, StdioServerParameters
from mcp import ClientSession

@pytest.mark.asyncio
async def test_add():
    params = StdioServerParameters(command="python", args=["-m", "my_mcp"])
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool("add", {"a": 2, "b": 3})
            assert result.content[0].text == "5"

ユニットテスト（TypeScript）

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

test("add", async () => {
  const transport = new StdioClientTransport({
    command: "node",
    args: ["dist/index.js"],
  });
  const client = new Client({ name: "test", version: "0.0.0" });
  await client.connect(transport);
  const result = await client.callTool({ name: "add", arguments: { a: 2, b: 3 } });
  expect(result.content[0].text).toBe("5");
  await client.close();
});

配布

Python: PyPI + uvx

pyproject.toml に [project.scripts] を書いて build → twine でアップロード。利用側は：

uvx my-mcp                 # ワンショット実行
# または
pip install my-mcp && my-mcp

.mcp.json：

{
  "command": "uvx",
  "args": ["my-mcp"]
}

TypeScript: npm + npx

package.json の bin を設定 → npm publish。利用側は：

npx -y my-mcp

.mcp.json：

{
  "command": "npx",
  "args": ["-y", "my-mcp"]
}

Docker

リモート MCP サーバーや複雑な依存があるサーバーは Docker 配布が楽：

FROM python:3.12-slim
WORKDIR /app
COPY . .
RUN pip install -e .
EXPOSE 8080
CMD ["python", "-m", "my_mcp", "--transport", "streamable-http", "--host", "0.0.0.0"]

セキュリティ・チェックリスト

パフォーマンス最適化

• Lazy import: 起動を軽くするため、重い依存は tool 呼び出し時にロード
• 接続プール: DB や HTTP 接続は使い回す
• キャッシュ: tools/list は頻繁に呼ばれる。変化しないなら静的データでよい
• 非同期化: I/O バウンドな tool は async def にする
• タイムアウト: 外部 API 呼び出しに必ずタイムアウトを設ける

よくある設計ミスと対策

参考プロジェクト構造（Python）

my-mcp/
├── pyproject.toml
├── README.md
├── LICENSE
├── src/
│   └── my_mcp/
│       ├── __init__.py      # FastMCP インスタンスと main()
│       ├── tools.py         # @mcp.tool() 群
│       ├── resources.py     # @mcp.resource() 群
│       ├── prompts.py       # @mcp.prompt() 群
│       ├── clients/         # 外部 API クライアント
│       │   └── github.py
│       └── config.py        # 環境変数ロード
├── tests/
│   ├── test_tools.py
│   └── conftest.py
└── .mcp.json.example

参考プロジェクト構造（TypeScript）

my-mcp/
├── package.json
├── tsconfig.json
├── README.md
├── LICENSE
├── src/
│   ├── index.ts             # エントリーポイント
│   ├── server.ts            # McpServer 初期化
│   ├── tools/
│   │   ├── index.ts         # registerAll 関数
│   │   └── search.ts
│   ├── resources/
│   ├── prompts/
│   └── clients/
├── tests/
│   └── tools.test.ts
└── .mcp.json.example