mcp-integration

Claude Code プラグイン向け MCP 統合

概要

Model Context Protocol（MCP）を使用すると、構造化されたツールアクセスを提供して、Claude Code プラグインを外部サービスや API と統合できます。MCP 統合を使用すると、外部サービスの機能を Claude Code 内のツールとして公開できます。

主な機能：

• 外部サービス（データベース、API、ファイルシステム）に接続
• 1 つのサービスから関連する 10 個以上のツールを提供
• OAuth や複雑な認証フローに対応
• MCP サーバーをプラグインにバンドルし、自動セットアップを実現

MCP サーバーの設定方法

プラグインには、次の 2 つの方法で MCP サーバーをバンドルできます。

方法 1：専用の .mcp.json（推奨）

プラグインのルートに .mcp.json を作成します。

{
  "database-tools": {
    "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
    "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
    "env": {
      "DB_URL": "${DB_URL}"
    }
  }
}

メリット：

• 関心事を明確に分離できます
• メンテナンスが容易です
• 複数のサーバーに適しています

方法 2：plugin.json にインラインで記述

plugin.json に mcpServers フィールドを追加します。

{
  "name": "my-plugin",
  "version": "1.0.0",
  "mcpServers": {
    "plugin-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}

メリット：

• 設定ファイルを 1 つにまとめられます
• シンプルな単一サーバーのプラグインに適しています

MCP サーバーの種類

stdio（ローカルプロセス）

ローカルの MCP サーバーを子プロセスとして実行します。ローカルツールやカスタムサーバーに最適です。

設定：

{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
    "env": {
      "LOG_LEVEL": "debug"
    }
  }
}

ユースケース：

• ファイルシステムへのアクセス
• ローカルデータベースへの接続
• カスタム MCP サーバー
• NPM パッケージとして配布される MCP サーバー

プロセス管理：

• Claude Code がプロセスを起動して管理します
• stdin/stdout 経由で通信します
• Claude Code の終了時にプロセスを終了します

SSE（Server-Sent Events）

OAuth に対応したホスト型 MCP サーバーに接続します。クラウドサービスに最適です。

設定：

{
  "hosted-service": {
    "type": "sse",
    "url": "https://mcp.example.com/sse"
  }
}

ユースケース：

• 公式のホスト型 MCP サーバー（Asana、GitHub など）
• MCP エンドポイントを備えたクラウドサービス
• OAuth ベースの認証
• ローカルへのインストールが不要

認証：

• OAuth フローは自動的に処理されます
• 初回使用時にユーザーに確認が表示されます
• トークンは Claude Code が管理します

HTTP（REST API）

トークン認証に対応した RESTful MCP サーバーに接続します。

設定：

{
  "api-service": {
    "type": "http",
    "url": "https://api.example.com/mcp",
    "headers": {
      "Authorization": "Bearer ${API_TOKEN}",
      "X-Custom-Header": "value"
    }
  }
}

ユースケース：

• REST API ベースの MCP サーバー
• トークンベースの認証
• カスタム API バックエンド
• ステートレスなやり取り

WebSocket（リアルタイム）

リアルタイムの双方向通信を行う WebSocket MCP サーバーに接続します。

設定：

{
  "realtime-service": {
    "type": "ws",
    "url": "wss://mcp.example.com/ws",
    "headers": {
      "Authorization": "Bearer ${TOKEN}"
    }
  }
}

ユースケース：

• リアルタイムのデータストリーミング
• 持続的な接続
• サーバーからのプッシュ通知
• 低レイテンシが求められる場合

環境変数の展開

すべての MCP 設定で、環境変数の置換がサポートされています。

${CLAUDE_PLUGIN_ROOT} — プラグインのディレクトリ（移植性を確保するため、常に使用してください）：

{
  "command": "${CLAUDE_PLUGIN_ROOT}/servers/my-server"
}

ユーザー環境変数 — ユーザーのシェルから取得します：

{
  "env": {
    "API_KEY": "${MY_API_KEY}",
    "DATABASE_URL": "${DB_URL}"
  }
}

ベストプラクティス： 必要な環境変数をすべてプラグインの README に記載してください。

MCP ツールの命名

MCP サーバーがツールを提供すると、自動的にプレフィックスが付与されます。

形式： mcp__plugin_<plugin-name>_<server-name>__<tool-name>

例：

• プラグイン：asana
• サーバー：asana
• ツール：create_task
• 完全な名前： mcp__plugin_asana_asana__asana_create_task

コマンドでの MCP ツールの使用

コマンドのフロントマターで、特定の MCP ツールを事前に許可します。

---
allowed-tools: [
  "mcp__plugin_asana_asana__asana_create_task",
  "mcp__plugin_asana_asana__asana_search_tasks"
]
---

ワイルドカード（使用は最小限にしてください）：

---
allowed-tools: ["mcp__plugin_asana_asana__*"]
---

ベストプラクティス： セキュリティのため、ワイルドカードではなく特定のツールを事前に許可してください。

ライフサイクル管理

自動起動：

• プラグインが有効になると MCP サーバーが起動します
• 最初のツール使用前に接続が確立されます
• 設定を変更した場合は再起動が必要です

ライフサイクル：

1. プラグインを読み込みます
2. MCP の設定を解析します
3. サーバープロセスを起動する（stdio）か、接続を確立します（SSE/HTTP/WS）
4. ツールを検出して登録します
5. ツールを mcp__plugin_...__... として使用できます

サーバーの表示： /mcp コマンドを使用すると、プラグインが提供するものを含むすべてのサーバーを確認できます。

認証パターン

OAuth（SSE/HTTP）

OAuth は Claude Code によって自動的に処理されます。

{
  "type": "sse",
  "url": "https://mcp.example.com/sse"
}

初回使用時に、ユーザーはブラウザーで認証します。追加の設定は不要です。

トークンベース（ヘッダー）

静的トークンまたは環境変数のトークンを使用します。

{
  "type": "http",
  "url": "https://api.example.com",
  "headers": {
    "Authorization": "Bearer ${API_TOKEN}"
  }
}

必要な環境変数を README に記載してください。

環境変数（stdio）

MCP サーバーに設定を渡します。

{
  "command": "python",
  "args": ["-m", "my_mcp_server"],
  "env": {
    "DATABASE_URL": "${DB_URL}",
    "API_KEY": "${API_KEY}",
    "LOG_LEVEL": "info"
  }
}

統合パターン

パターン 1：シンプルなツールラッパー

コマンドから、ユーザーとのやり取りを伴う MCP ツールを使用します。

# Command: create-item.md
---
allowed-tools: ["mcp__plugin_name_server__create_item"]
---

Steps:
1. Gather item details from user
2. Use mcp__plugin_name_server__create_item
3. Confirm creation

使用する場面： MCP 呼び出しの前に、検証や前処理を追加する場合。

パターン 2：自律型エージェント

エージェントが自律的に MCP ツールを使用します。

# Agent: data-analyzer.md

Analysis Process:
1. Query data via mcp__plugin_db_server__query
2. Process and analyze results
3. Generate insights report

使用する場面： ユーザーとのやり取りを伴わない、複数ステップの MCP ワークフロー。

パターン 3：複数サーバーのプラグイン

複数の MCP サーバーを統合します。

{
  "github": {
    "type": "sse",
    "url": "https://mcp.github.com/sse"
  },
  "jira": {
    "type": "sse",
    "url": "https://mcp.jira.com/sse"
  }
}

使用する場面： 複数のサービスにまたがるワークフロー。

セキュリティのベストプラクティス

HTTPS/WSS を使用する

常にセキュアな接続を使用してください。

✅ "url": "https://mcp.example.com/sse"
❌ "url": "http://mcp.example.com/sse"

トークン管理

実施すること：

• ✅ トークンには環境変数を使用する
• ✅ 必要な環境変数を README に記載する
• ✅ 認証には OAuth フローを使用する

実施しないこと：

• ❌ 設定にトークンをハードコードする
• ❌ トークンを git にコミットする
• ❌ ドキュメントでトークンを共有する

権限の範囲設定

必要な MCP ツールのみを事前に許可します。

✅ allowed-tools: [
  "mcp__plugin_api_server__read_data",
  "mcp__plugin_api_server__create_item"
]

❌ allowed-tools: ["mcp__plugin_api_server__*"]

エラー処理

接続エラー

MCP サーバーが利用できない場合に対処します。

• コマンドにフォールバック動作を用意する
• 接続の問題をユーザーに知らせる
• サーバー URL と設定を確認する

ツール呼び出しエラー

MCP 操作の失敗に対処します。

• MCP ツールを呼び出す前に入力を検証する
• わかりやすいエラーメッセージを表示する
• レート制限とクォータを確認する

設定エラー

MCP の設定を検証します。

• 開発中にサーバーへの接続をテストする
• JSON 構文を検証する
• 必要な環境変数を確認する

パフォーマンスに関する考慮事項

遅延読み込み

MCP サーバーは必要に応じて接続します。

• すべてのサーバーが起動時に接続するわけではありません
• 最初のツール使用時に接続が開始されます
• 接続プールは自動的に管理されます

バッチ処理

可能な場合は、類似したリクエストをまとめて処理します。

# Good: Single query with filters
tasks = search_tasks(project="X", assignee="me", limit=50)

# Avoid: Many individual queries
for id in task_ids:
    task = get_task(id)

MCP 統合のテスト

ローカルテスト

1. .mcp.json で MCP サーバーを設定する
2. プラグインをローカルにインストールする（.claude-plugin/）
3. /mcp を実行して、サーバーが表示されることを確認する
4. コマンド内でツール呼び出しをテストする
5. claude --debug のログで接続の問題を確認する

検証チェックリスト

• MCP 設定が有効な JSON である
• サーバー URL が正しく、アクセス可能である
• 必要な環境変数が記載されている
• /mcp の出力にツールが表示される
• 認証が機能する（OAuth またはトークン）
• コマンドからのツール呼び出しが成功する
• エラーケースに適切に対処できる

デバッグ

デバッグログを有効にする

claude --debug

次の項目を確認してください。

• MCP サーバーへの接続試行
• ツール検出のログ
• 認証フロー
• ツール呼び出しのエラー

よくある問題

サーバーに接続できない場合：

• URL が正しいことを確認する
• サーバーが稼働していることを確認する（stdio）
• ネットワーク接続を確認する
• 認証設定を確認する

ツールを利用できない場合：

• サーバーへの接続が成功したことを確認する
• ツール名が完全に一致していることを確認する
• /mcp を実行して利用可能なツールを確認する
• 設定を変更した後、Claude Code を再起動する

認証に失敗する場合：

• キャッシュされた認証トークンをクリアする
• 再認証する
• トークンのスコープと権限を確認する
• 環境変数が設定されていることを確認する

クイックリファレンス

MCP サーバーの種類

種類	トランスポート	最適な用途	認証
stdio	プロセス	ローカルツール、カスタムサーバー	環境変数
SSE	HTTP	ホステッドサービス、クラウド API	OAuth
HTTP	REST	API バックエンド、トークン認証	トークン
ws	WebSocket	リアルタイム、ストリーミング	トークン

設定チェックリスト

• サーバーの種類を指定している（stdio/SSE/HTTP/ws）
• 種類固有のフィールドがすべて入力されている（command または url）
• 認証が設定されている
• 環境変数が記載されている
• HTTPS/WSS を使用している（HTTP/WS ではない）
• パスに ${CLAUDE_PLUGIN_ROOT} を使用している

ベストプラクティス

推奨事項：

• ✅ 移植性の高いパスには ${CLAUDE_PLUGIN_ROOT} を使用します
• ✅ 必要な環境変数を記載します
• ✅ 安全な接続（HTTPS/WSS）を使用します
• ✅ コマンド内で特定の MCP ツールを事前に許可します
• ✅ 公開前に MCP の統合をテストします
• ✅ 接続エラーやツールエラーを適切に処理します

禁止事項：

• ❌ 絶対パスをハードコードしないでください
• ❌ 認証情報を git にコミットしないでください
• ❌ HTTPS の代わりに HTTP を使用しないでください
• ❌ ワイルドカードを使用してすべてのツールを事前に許可しないでください
• ❌ エラー処理を省略しないでください
• ❌ セットアップの記載を忘れないでください

追加リソース

リファレンスファイル

詳細については、以下を参照してください。

• references/server-types.md - 各サーバータイプの詳細
• references/authentication.md - 認証パターンと OAuth
• references/tool-usage.md - コマンドやエージェントでの MCP ツールの使用方法

設定例

examples/ に動作する設定例があります。

• stdio-server.json - ローカルの stdio MCP サーバー
• sse-server.json - OAuth 対応のホスト型 SSE サーバー
• http-server.json - トークン認証を使用する REST API

外部リソース

• 公式 MCP ドキュメント：https://modelcontextprotocol.io/
• Claude Code MCP ドキュメント：https://docs.claude.com/en/docs/claude-code/mcp
• MCP SDK：@modelcontextprotocol/sdk
• テスト：claude --debug と /mcp コマンドを使用します

実装ワークフロー

プラグインに MCP 統合を追加するには、次の手順に従います。

1. MCP サーバーのタイプを選択します（stdio、SSE、HTTP、ws）
2. プラグインのルートに .mcp.json を作成し、設定を記述します
3. すべてのファイル参照に ${CLAUDE_PLUGIN_ROOT} を使用します
4. README に必要な環境変数を記載します
5. /mcp コマンドを使ってローカルでテストします
6. 関連するコマンドで MCP ツールを事前に許可します
7. 認証（OAuth またはトークン）を処理します
8. エラーケース（接続失敗、認証エラー）をテストします
9. プラグインの README に MCP 統合について記載します

カスタムまたはローカルのサーバーには stdio を、OAuth 対応のホスト型サービスには SSE を使用することをおすすめします。