claude-howto/ja/05-mcp

MCP（Model Context Protocol）

このフォルダには、Claude Code における MCP サーバー設定と使用方法に関する包括的なドキュメントとサンプルが含まれている。

概要

MCP（Model Context Protocol）は、Claude が外部ツール、API、リアルタイムデータソースにアクセスするための標準化された方式である。メモリとは異なり、MCP は変化するデータへのライブアクセスを提供する。

主な特徴：

• 外部サービスへのリアルタイムアクセス
• ライブデータの同期
• 拡張可能なアーキテクチャ
• セキュアな認証
• ツールベースの対話

MCP アーキテクチャ

graph TB
    A["Claude"]
    B["MCP Server"]
    C["External Service"]

    A -->|Request: list_issues| B
    B -->|Query| C
    C -->|Data| B
    B -->|Response| A

    A -->|Request: create_issue| B
    B -->|Action| C
    C -->|Result| B
    B -->|Response| A

    style A fill:#e1f5fe,stroke:#333,color:#333
    style B fill:#f3e5f5,stroke:#333,color:#333
    style C fill:#e8f5e9,stroke:#333,color:#333

MCP エコシステム

graph TB
    A["Claude"] -->|MCP| B["Filesystem<br/>MCP Server"]
    A -->|MCP| C["GitHub<br/>MCP Server"]
    A -->|MCP| D["Database<br/>MCP Server"]
    A -->|MCP| E["Slack<br/>MCP Server"]
    A -->|MCP| F["Google Docs<br/>MCP Server"]

    B -->|File I/O| G["Local Files"]
    C -->|API| H["GitHub Repos"]
    D -->|Query| I["PostgreSQL/MySQL"]
    E -->|Messages| J["Slack Workspace"]
    F -->|Docs| K["Google Drive"]

    style A fill:#e1f5fe,stroke:#333,color:#333
    style B fill:#f3e5f5,stroke:#333,color:#333
    style C fill:#f3e5f5,stroke:#333,color:#333
    style D fill:#f3e5f5,stroke:#333,color:#333
    style E fill:#f3e5f5,stroke:#333,color:#333
    style F fill:#f3e5f5,stroke:#333,color:#333
    style G fill:#e8f5e9,stroke:#333,color:#333
    style H fill:#e8f5e9,stroke:#333,color:#333
    style I fill:#e8f5e9,stroke:#333,color:#333
    style J fill:#e8f5e9,stroke:#333,color:#333
    style K fill:#e8f5e9,stroke:#333,color:#333

MCP のインストール方法

Claude Code は MCP サーバー接続のために複数のトランスポートプロトコルをサポートしている。

HTTP トランスポート（推奨）

# 基本的な HTTP 接続
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 認証ヘッダー付き HTTP
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Stdio トランスポート（ローカル）

ローカルで動作する MCP サーバー向け：

# ローカル Node.js サーバー
claude mcp add --transport stdio myserver -- npx @myorg/mcp-server

# 環境変数付き
claude mcp add --transport stdio myserver --env KEY=value -- npx server

SSE トランスポート（非推奨）

Server-Sent Events トランスポートは http の登場により非推奨となったが、引き続きサポートされている。

claude mcp add --transport sse legacy-server https://example.com/sse

WebSocket トランスポート（ws）

WebSocket サーバーは持続的な双方向接続を保つため、Claude に対して自発的にイベントを push するリモート MCP サーバーに向いている。サーバーがリクエストに応答するだけなら HTTP を使うこと。HTTP は OAuth と claude mcp add --transport フラグの両方をサポートするが、WebSocket はどちらもサポートしない。

--transport は ws を受け付けないため、.mcp.json または claude mcp add-json で設定する。

{
  "type": "ws",
  "url": "wss://mcp.example.com/socket",
  "headers": {
    "Authorization": "Bearer YOUR_TOKEN"
  }
}

type: "ws" のエントリは http と同じ url、headers、headersHelper、timeout、alwaysLoad フィールドを受け付ける。認証はヘッダーのみで、WebSocket サーバー向けの OAuth フローは存在しない。

注意: WebSocket サーバーは claude mcp list の出力に表示されない。確認するには claude mcp get <名前> または /mcp パネルを使うこと。

HTTP や SSE と同様に、WebSocket 接続のアイドル時間は 5 分。stdio と WebSocket にはリクエスト単位のタイマーはない。type のない url エントリはエラーとなり、有効な値として "http"、"sse"、"ws" が示される。

Windows 固有の注意点

ネイティブ Windows（WSL ではない）では、npx コマンドに cmd /c を使う。

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

OAuth 2.0 認証

Claude Code は OAuth 2.0 を必要とする MCP サーバーをサポートする。OAuth 対応サーバーに接続する際、Claude Code が認証フロー全体を処理する。

# OAuth 対応 MCP サーバーへ接続（対話フロー）
claude mcp add --transport http my-service https://my-service.example.com/mcp

# 非対話セットアップのために OAuth 認証情報を事前設定
claude mcp add --transport http my-service https://my-service.example.com/mcp \
  --client-id "your-client-id" \
  --client-secret "your-client-secret" \
  --callback-port 8080

機能	説明
対話型 OAuth	/mcp を使ってブラウザベースの OAuth フローをトリガー
事前設定済み OAuth クライアント	Notion、Stripe など一般的なサービス向けの組み込み OAuth クライアント（v2.1.30 以降）
事前設定済み認証情報	自動セットアップ用の --client-id、--client-secret、--callback-port フラグ
トークンの保存	トークンはシステムキーチェーンに安全に保存される
ステップアップ認証	特権操作に対するステップアップ認証をサポート
ディスカバリのキャッシュ	OAuth ディスカバリメタデータがキャッシュされ、再接続が高速化される
メタデータのオーバーライド	.mcp.json の oauth.authServerMetadataUrl でデフォルトの OAuth メタデータディスカバリを上書き

OAuth メタデータディスカバリのオーバーライド

MCP サーバーが標準の OAuth メタデータエンドポイント（/.well-known/oauth-authorization-server）でエラーを返すが、動作する OIDC エンドポイントを公開している場合、Claude Code に特定の URL から OAuth メタデータを取得するよう指示できる。サーバー設定の oauth オブジェクト内で authServerMetadataUrl を設定する。

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"
      }
    }
  }
}

URL は https:// を使用しなければならない。このオプションは Claude Code v2.1.64 以降が必要。

Claude.ai MCP コネクタ

Claude.ai アカウントで設定された MCP サーバーは、Claude Code でも自動的に利用可能になる。つまり、Claude.ai の Web インターフェース経由でセットアップした MCP 接続は、追加設定なしでアクセスできる。

Claude.ai MCP コネクタは --print モード（v2.1.83 以降）でも利用可能で、非対話・スクリプト実行を可能にする。

起動時の注意（v2.1.117 以降）： ローカルと claude.ai の MCP サーバーの両方が設定されている場合、並行接続がデフォルトとなる（以前は逐次接続）。複数サーバー使用時の起動レイテンシが削減される。

Claude Code 内で Claude.ai MCP サーバーを無効化するには、ENABLE_CLAUDEAI_MCP_SERVERS 環境変数を false に設定する。

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

注意： この機能は Claude.ai アカウントでログインしているユーザーのみ利用できる。

MCP セットアップの流れ

sequenceDiagram
    participant User
    participant Claude as Claude Code
    participant Config as Config File
    participant Service as External Service

    User->>Claude: Type /mcp
    Claude->>Claude: List available MCP servers
    Claude->>User: Show options
    User->>Claude: Select GitHub MCP
    Claude->>Config: Update configuration
    Config->>Claude: Activate connection
    Claude->>Service: Test connection
    Service-->>Claude: Authentication successful
    Claude->>User: ✅ MCP connected!

MCP ツール検索

MCP ツールの説明文がコンテキストウィンドウの 10% を超える場合、Claude Code は自動的にツール検索を有効にし、モデルコンテキストを圧迫せずに適切なツールを効率的に選択する。

設定	値	説明
ENABLE_TOOL_SEARCH	auto（デフォルト）	ツールの説明がコンテキストの 10% を超えた時点で自動的に有効化
ENABLE_TOOL_SEARCH	auto:<N>	カスタムしきい値 N 個のツール数で自動的に有効化
ENABLE_TOOL_SEARCH	true	ツール数に関係なく常に有効
ENABLE_TOOL_SEARCH	false	無効。すべてのツールの説明が完全な形で送信される

注意： ツール検索には Sonnet 4 以降、もしくは Opus 4 以降が必要。Haiku モデルはツール検索をサポートしない。

動的ツール更新

Claude Code は MCP の list_changed 通知をサポートする。MCP サーバーが利用可能なツールを動的に追加・削除・変更すると、Claude Code は更新を受け取り、ツール一覧を自動的に調整する。再接続や再起動は不要である。

MCP Apps

MCP Apps は最初の公式 MCP 拡張で、MCP ツール呼び出しがチャットインターフェースに直接レンダリングされるインタラクティブな UI コンポーネントを返せるようにする。プレーンテキストのレスポンスではなく、MCP サーバーがリッチなダッシュボード、フォーム、データの可視化、マルチステップワークフローをチャット内に直接表示できる。会話を離れることなく、すべてがインラインで表示される。

MCP Elicitation

MCP サーバーはインタラクティブダイアログを介してユーザーから構造化入力を要求できる（v2.1.49 以降）。これにより MCP サーバーはワークフローの途中で追加情報を要求できる。たとえば確認のプロンプト、選択肢のリストからの選択、必須フィールドの入力などが可能となり、MCP サーバーとの対話に対話性を加える。

ツール説明と指示の上限

v2.1.84 以降、Claude Code は MCP サーバーごとのツール説明と指示に 2 KB の上限 を強制する。これは個々のサーバーが冗長すぎるツール定義でコンテキストを過剰に消費するのを防ぎ、コンテキストの肥大化を抑え、対話を効率的に保つ。

MCP プロンプトをスラッシュコマンドとして利用

MCP サーバーはスラッシュコマンドとして表示されるプロンプトを公開できる。プロンプトは以下の命名規則でアクセスする。

/mcp__<server>__<prompt>

たとえば、github という名前のサーバーが review というプロンプトを公開している場合、/mcp__github__review として呼び出せる。

サーバーの重複排除

同じ MCP サーバーが複数のスコープ（local、project、user）で定義されている場合、ローカル設定が優先される。これにより、競合なしにローカルカスタマイズで project レベルや user レベルの MCP 設定をオーバーライドできる。

@ メンションによる MCP リソース

@ メンション構文を使ってプロンプト内で MCP リソースを直接参照できる。

@server-name:protocol://resource/path

たとえば、特定のデータベースリソースを参照するには：

@database:postgres://mydb/users

これにより Claude が MCP リソースの内容を会話コンテキストの一部としてインラインで取得・包含できる。

MCP のスコープ

MCP の設定は共有レベルの異なる複数のスコープに保存できる。

スコープ	フラグ	場所	説明	共有相手	承認の要否
Local（デフォルト）	--scope local	~/.claude.json（プロジェクトパス配下）	現在のユーザー、現在のプロジェクトに非公開（旧バージョンでは project と呼ばれていた）	自分のみ	不要
Project	--scope project	.mcp.json	git リポジトリにチェックインされる	チームメンバー	必要（初回使用時）
User	--scope user	~/.claude.json	全プロジェクトで利用可能（旧バージョンでは global と呼ばれていた）	自分のみ	不要

サーバー追加時のスコープは --scope（短縮形 -s）で選択する。省略した場合、 Claude Code は local を使う。

# Project スコープ — .mcp.json に書き込まれ、チームで共有される
claude mcp add --scope project --transport http github https://api.github.com/mcp

# User スコープ — すべてのプロジェクトで利用できる
claude mcp add --scope user --transport stdio memory -- npx @modelcontextprotocol/server-memory

Project スコープの使用

プロジェクト固有の MCP 設定を .mcp.json に保存する。

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.github.com/mcp"
    }
  }
}

チームメンバーはプロジェクト MCP の初回使用時に承認プロンプトが表示される。

MCP 設定の管理

MCP サーバーの追加

# HTTP ベースのサーバーを追加
claude mcp add --transport http github https://api.github.com/mcp

# ローカル stdio サーバーを追加
claude mcp add --transport stdio database -- npx @company/db-server

# すべての MCP サーバーを一覧表示
claude mcp list

# 特定サーバーの詳細を取得
claude mcp get github

# MCP サーバーを削除
claude mcp remove github

# プロジェクト固有の承認選択をリセット
claude mcp reset-project-choices

# Claude Desktop からインポート
claude mcp add-from-claude-desktop

利用可能な MCP サーバー一覧

MCP サーバー	用途	一般的なツール	認証	リアルタイム
Filesystem	ファイル操作	read、write、delete	OS の権限	✅ Yes
GitHub	リポジトリ管理	list_prs、create_issue、push	OAuth	✅ Yes
Slack	チームコミュニケーション	send_message、list_channels	トークン	✅ Yes
Database	SQL クエリ	query、insert、update	認証情報	✅ Yes
Google Docs	ドキュメントアクセス	read、write、share	OAuth	✅ Yes
Asana	プロジェクト管理	create_task、update_status	API キー	✅ Yes
Stripe	決済データ	list_charges、create_invoice	API キー	✅ Yes
Memory	永続メモリ	store、retrieve、delete	ローカル	❌ No

実用例

例 1：GitHub MCP の設定

ファイル： .mcp.json（プロジェクトルート）

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

利用可能な GitHub MCP ツール：

プルリクエスト管理

• list_prs - リポジトリ内の全 PR を一覧
• get_pr - diff を含む PR の詳細を取得
• create_pr - 新しい PR を作成
• update_pr - PR の説明・タイトルを更新
• merge_pr - PR を main ブランチにマージ
• review_pr - レビューコメントを追加

リクエスト例：

/mcp__github__get_pr 456

# Returns:
Title: Add dark mode support
Author: @alice
Description: Implements dark theme using CSS variables
Status: OPEN
Reviewers: @bob, @charlie

Issue 管理

• list_issues - 全 Issue を一覧
• get_issue - Issue の詳細を取得
• create_issue - 新しい Issue を作成
• close_issue - Issue をクローズ
• add_comment - Issue にコメントを追加

リポジトリ情報

• get_repo_info - リポジトリの詳細
• list_files - ファイルツリー構造
• get_file_content - ファイル内容を読み込み
• search_code - コードベースを横断検索

コミット操作

• list_commits - コミット履歴
• get_commit - 特定コミットの詳細
• create_commit - 新しいコミットを作成

セットアップ：

export GITHUB_TOKEN="your_github_token"
# または CLI で直接追加:
claude mcp add --transport stdio github -- npx @modelcontextprotocol/server-github

設定での環境変数展開

MCP 設定は環境変数の展開とフォールバックデフォルトをサポートする。${VAR} および ${VAR:-default} 構文は次のフィールドで動作する：command、args、env、url、headers。

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}",
        "X-Custom-Header": "${CUSTOM_HEADER:-default-value}"
      }
    },
    "local-server": {
      "command": "${MCP_BIN_PATH:-npx}",
      "args": ["${MCP_PACKAGE:-@company/mcp-server}"],
      "env": {
        "DB_URL": "${DATABASE_URL:-postgresql://localhost/dev}"
      }
    }
  }
}

変数は実行時に展開される。

• ${VAR} - 環境変数を使用、未設定ならエラー
• ${VAR:-default} - 環境変数を使用、未設定なら default にフォールバック

例 2：Database MCP のセットアップ

設定：

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-database"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

使用例：

User: Fetch all users with more than 10 orders

Claude: I'll query your database to find that information.

# Using MCP database tool:
SELECT u.*, COUNT(o.id) as order_count
FROM users u
LEFT JOIN orders o ON u.id = o.user_id
GROUP BY u.id
HAVING COUNT(o.id) > 10
ORDER BY order_count DESC;

# Results:
- Alice: 15 orders
- Bob: 12 orders
- Charlie: 11 orders

セットアップ：

export DATABASE_URL="postgresql://user:pass@localhost/mydb"
# または CLI で直接追加:
claude mcp add --transport stdio database -- npx @modelcontextprotocol/server-database

例 3：マルチ MCP ワークフロー

シナリオ：日次レポート生成

# Daily Report Workflow using Multiple MCPs

## Setup
1. GitHub MCP - fetch PR metrics
2. Database MCP - query sales data
3. Slack MCP - post report
4. Filesystem MCP - save report

## Workflow

### Step 1: Fetch GitHub Data
/mcp__github__list_prs completed:true last:7days

Output:
- Total PRs: 42
- Average merge time: 2.3 hours
- Review turnaround: 1.1 hours

### Step 2: Query Database
SELECT COUNT(*) as sales, SUM(amount) as revenue
FROM orders
WHERE created_at > NOW() - INTERVAL '1 day'

Output:
- Sales: 247
- Revenue: $12,450

### Step 3: Generate Report
Combine data into HTML report

### Step 4: Save to Filesystem
Write report.html to /reports/

### Step 5: Post to Slack
Send summary to #daily-reports channel

Final Output:
✅ Report generated and posted
📊 47 PRs merged this week
💰 $12,450 in daily sales

セットアップ：

export GITHUB_TOKEN="your_github_token"
export DATABASE_URL="postgresql://user:pass@localhost/mydb"
export SLACK_TOKEN="your_slack_token"
# 各 MCP サーバーを CLI で追加するか、.mcp.json で設定する

例 4：Filesystem MCP の操作

設定：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    }
  }
}

利用可能な操作：

操作	コマンド	用途
ファイル一覧	ls ~/projects	ディレクトリの内容を表示
ファイル読み込み	cat src/main.ts	ファイル内容を読み込み
ファイル書き込み	create docs/api.md	新規ファイルを作成
ファイル編集	edit src/app.ts	ファイルを変更
検索	grep "async function"	ファイル内を検索
削除	rm old-file.js	ファイルを削除

セットアップ：

# CLI で直接追加:
claude mcp add --transport stdio filesystem -- npx @modelcontextprotocol/server-filesystem /home/user/projects

MCP とメモリの比較：判断マトリクス

graph TD
    A["Need external data?"]
    A -->|No| B["Use Memory"]
    A -->|Yes| C["Does it change frequently?"]
    C -->|No/Rarely| B
    C -->|Yes/Often| D["Use MCP"]

    B -->|Stores| E["Preferences<br/>Context<br/>History"]
    D -->|Accesses| F["Live APIs<br/>Databases<br/>Services"]

    style A fill:#fff3e0,stroke:#333,color:#333
    style B fill:#e1f5fe,stroke:#333,color:#333
    style C fill:#fff3e0,stroke:#333,color:#333
    style D fill:#f3e5f5,stroke:#333,color:#333
    style E fill:#e8f5e9,stroke:#333,color:#333
    style F fill:#e8f5e9,stroke:#333,color:#333

リクエスト/レスポンスパターン

sequenceDiagram
    participant App as Claude
    participant MCP as MCP Server
    participant DB as Database

    App->>MCP: Request: "SELECT * FROM users WHERE id=1"
    MCP->>DB: Execute query
    DB-->>MCP: Result set
    MCP-->>App: Return parsed data
    App->>App: Process result
    App->>App: Continue task

    Note over MCP,DB: Real-time access<br/>No caching

環境変数

機密性の高い認証情報は環境変数に保存する。

# ~/.bashrc or ~/.zshrc
export GITHUB_TOKEN="ghp_xxxxxxxxxxxxx"
export DATABASE_URL="postgresql://user:pass@localhost/mydb"
export SLACK_TOKEN="xoxb-xxxxxxxxxxxxx"

そして MCP 設定で参照する。

{
  "env": {
    "GITHUB_TOKEN": "${GITHUB_TOKEN}"
  }
}

Claude を MCP サーバーにする（claude mcp serve）

Claude Code 自体が他のアプリケーション向けの MCP サーバーとして動作できる。これにより、外部ツール、エディタ、自動化システムが標準 MCP プロトコルを介して Claude の機能を活用できる。

# Claude Code を stdio 上の MCP サーバーとして起動
claude mcp serve

他のアプリケーションは、stdio ベースの MCP サーバーと同じようにこのサーバーに接続できる。たとえば、別の Claude Code インスタンスに Claude Code を MCP サーバーとして追加するには：

claude mcp add --transport stdio claude-agent -- claude mcp serve

これは、ある Claude インスタンスが別のインスタンスをオーケストレーションするマルチエージェントワークフローの構築に有用である。

管理対象 MCP 設定（エンタープライズ）

エンタープライズ展開では、IT 管理者が managed-mcp.json 設定ファイルを通じて MCP サーバーポリシーを強制できる。このファイルは、組織全体で許可または禁止する MCP サーバーを排他的に制御する。

配置場所：

• macOS: /Library/Application Support/ClaudeCode/managed-mcp.json
• Linux: ~/.config/ClaudeCode/managed-mcp.json
• Windows: %APPDATA%\ClaudeCode\managed-mcp.json

機能：

• allowedMcpServers -- 許可するサーバーのホワイトリスト
• deniedMcpServers -- 禁止するサーバーのブロックリスト
• サーバー名、コマンド、URL パターンによるマッチをサポート
• ユーザー設定より前に組織全体の MCP ポリシーを強制
• 認可されていないサーバー接続を防止

設定例：

{
  "allowedMcpServers": [
    {
      "serverName": "github",
      "serverUrl": "https://api.github.com/mcp"
    },
    {
      "serverName": "company-internal",
      "serverCommand": "company-mcp-server"
    }
  ],
  "deniedMcpServers": [
    {
      "serverName": "untrusted-*"
    },
    {
      "serverUrl": "http://*"
    }
  ]
}

注意： allowedMcpServers と deniedMcpServers の両方が同じサーバーにマッチする場合、deny ルールが優先される。

プラグイン提供の MCP サーバー

プラグインは独自の MCP サーバーをバンドルでき、プラグインのインストール時に自動的に利用可能になる。プラグイン提供の MCP サーバーは 2 つの方法で定義できる。

1. スタンドアロンの .mcp.json -- プラグインのルートディレクトリに .mcp.json ファイルを配置
2. plugin.json 内にインライン定義 -- プラグインマニフェスト内で MCP サーバーを直接定義

${CLAUDE_PLUGIN_ROOT} 変数を使ってプラグインのインストールディレクトリからの相対パスを参照する。

{
  "mcpServers": {
    "plugin-tools": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/dist/mcp-server.js"],
      "env": {
        "CONFIG_PATH": "${CLAUDE_PLUGIN_ROOT}/config.json"
      }
    }
  }
}

サブエージェントスコープの MCP

MCP サーバーはエージェントのフロントマター内で mcpServers: キーを使ってインライン定義でき、プロジェクト全体ではなく特定のサブエージェントにスコープできる。これは、ワークフロー内の他のエージェントには不要な特定の MCP サーバーへのアクセスを、あるエージェントが必要とする場合に有用である。

---
mcpServers:
  my-tool:
    type: http
    url: https://my-tool.example.com/mcp
---

You are an agent with access to my-tool for specialized operations.

サブエージェントスコープの MCP サーバーは、そのエージェントの実行コンテキスト内でのみ利用でき、親エージェントや兄弟エージェントとは共有されない。

MCP の出力上限

Claude Code はコンテキストオーバーフローを防ぐため、MCP ツールの出力に上限を強制する。

上限	しきい値	動作
警告	10,000 トークン	出力が大きいことを示す警告を表示
デフォルト最大値	25,000 トークン	この上限を超えた出力は切り詰められる
ディスク永続化	50,000 文字	50K 文字を超えるツール結果はディスクに永続化される

最大出力上限は MAX_MCP_OUTPUT_TOKENS 環境変数で設定可能。

# 最大出力を 50,000 トークンに引き上げる
export MAX_MCP_OUTPUT_TOKENS=50000

コード実行によるコンテキスト肥大化の解決

MCP の採用が拡大するにつれ、数十のサーバーと数百〜数千のツールに接続することは大きな課題を生む：コンテキストの肥大化 である。これは MCP がスケールしたときの最大の問題と言ってよく、Anthropic のエンジニアリングチームが提案するエレガントな解決策が、ツールを直接呼び出す代わりにコード実行を使う方法である。

出典： Code Execution with MCP: Building More Efficient Agents — Anthropic Engineering Blog

問題：トークン浪費の 2 つの源

1. ツール定義がコンテキストウィンドウを過負荷にする

ほとんどの MCP クライアントは全ツール定義を事前に読み込む。数千のツールに接続している場合、モデルはユーザーのリクエストを読む前に数十万トークンを処理しなければならない。

2. 中間結果がさらにトークンを消費する

すべての中間ツール結果はモデルのコンテキストを通過する。Google Drive から Salesforce へ会議の文字起こしを転送する場合を考えると、文字起こし全体がコンテキストを 2 回 流れる。読み込むときと、宛先に書き込むときである。2 時間の会議の文字起こしは 50,000 トークン以上の追加になり得る。

graph LR
    A["Model"] -->|"Tool Call: getDocument"| B["MCP Server"]
    B -->|"Full transcript (50K tokens)"| A
    A -->|"Tool Call: updateRecord<br/>(re-sends full transcript)"| B
    B -->|"Confirmation"| A

    style A fill:#ffcdd2,stroke:#333,color:#333
    style B fill:#f3e5f5,stroke:#333,color:#333

解決策：コード API としての MCP ツール

ツール定義と結果をコンテキストウィンドウに通す代わりに、エージェントが MCP ツールを API として呼び出す コードを書く。コードはサンドボックス化された実行環境で動作し、最終結果のみがモデルに返される。

graph LR
    A["Model"] -->|"Writes code"| B["Code Execution<br/>Environment"]
    B -->|"Calls tools directly"| C["MCP Servers"]
    C -->|"Data stays in<br/>execution env"| B
    B -->|"Only final result<br/>(minimal tokens)"| A

    style A fill:#c8e6c9,stroke:#333,color:#333
    style B fill:#e1f5fe,stroke:#333,color:#333
    style C fill:#f3e5f5,stroke:#333,color:#333

仕組み

MCP ツールは型付き関数のファイルツリーとして提示される。

servers/
├── google-drive/
│   ├── getDocument.ts
│   └── index.ts
├── salesforce/
│   ├── updateRecord.ts
│   └── index.ts
└── ...

各ツールファイルには型付きラッパーが含まれる。

// ./servers/google-drive/getDocument.ts
import { callMCPTool } from "../../../client.js";

interface GetDocumentInput {
  documentId: string;
}

interface GetDocumentResponse {
  content: string;
}

export async function getDocument(
  input: GetDocumentInput
): Promise<GetDocumentResponse> {
  return callMCPTool<GetDocumentResponse>(
    'google_drive__get_document', input
  );
}

エージェントはツールをオーケストレーションするコードを書く。

import * as gdrive from './servers/google-drive';
import * as salesforce from './servers/salesforce';

// データはツール間で直接流れる — モデルを経由しない
const transcript = (
  await gdrive.getDocument({ documentId: 'abc123' })
).content;

await salesforce.updateRecord({
  objectType: 'SalesMeeting',
  recordId: '00Q5f000001abcXYZ',
  data: { Notes: transcript }
});

結果：トークン使用量は約 150,000 から約 2,000 に減少 — 98.7% の削減。

主な利点

利点	説明
段階的開示	エージェントはファイルシステムを参照して必要なツール定義のみを読み込み、全ツールを事前読込みしない
コンテキスト効率の良い結果	データは実行環境内でフィルタ/変換されてからモデルに返される
強力な制御フロー	ループ、条件分岐、エラー処理がモデルへのラウンドトリップなしにコード内で動作
プライバシー保護	中間データ（PII、機密レコード）は実行環境内に留まり、モデルコンテキストに入らない
状態の永続化	エージェントは中間結果をファイルに保存し、再利用可能なスキル関数を構築できる

例：大規模データセットのフィルタリング

// コード実行なし — 10,000 行すべてがコンテキストを流れる
// TOOL CALL: gdrive.getSheet(sheetId: 'abc123')
//   -> returns 10,000 rows in context

// コード実行あり — 実行環境内でフィルタリング
const allRows = await gdrive.getSheet({ sheetId: 'abc123' });
const pendingOrders = allRows.filter(
  row => row["Status"] === 'pending'
);
console.log(`Found ${pendingOrders.length} pending orders`);
console.log(pendingOrders.slice(0, 5)); // 5 行のみがモデルに到達

例：ラウンドトリップなしのループ

// デプロイ通知をポーリング — すべてコード内で実行
let found = false;
while (!found) {
  const messages = await slack.getChannelHistory({
    channel: 'C123456'
  });
  found = messages.some(
    m => m.text.includes('deployment complete')
  );
  if (!found) await new Promise(r => setTimeout(r, 5000));
}
console.log('Deployment notification received');

考慮すべきトレードオフ

コード実行は独自の複雑さを持ち込む。エージェント生成のコードを実行するには次が必要となる。

• 適切なリソース上限を持つ セキュアなサンドボックス実行環境
• 実行されたコードの 監視とログ記録
• ツールの直接呼び出しと比較した追加の インフラオーバーヘッド

利点（トークンコスト削減、レイテンシ低下、ツール構成の改善）は、こうした実装コストと天秤にかける必要がある。MCP サーバーが少数だけのエージェントなら、ツールの直接呼び出しのほうがシンプルかもしれない。スケールするエージェント（数十のサーバー、数百のツール）にとって、コード実行は大きな改善である。

MCPorter：MCP ツール構成のためのランタイム

MCPorter は、MCP サーバーへの呼び出しをボイラープレートなしで実用的にする TypeScript ランタイム＆ CLI ツールキットである。選択的なツール公開と型付きラッパーを通じてコンテキストの肥大化を抑える助けにもなる。

解決すること： すべての MCP サーバーから全ツール定義を事前読み込みする代わりに、MCPorter は特定のツールを必要に応じて発見、検査、呼び出しできるようにする。これによりコンテキストを軽量に保てる。

主な機能：

機能	説明
ゼロ設定での発見	Cursor、Claude、Codex、ローカル設定から MCP サーバーを自動発見
型付きツールクライアント	mcporter emit-ts が .d.ts インターフェースとすぐ動作するラッパーを生成
構成可能な API	createServerProxy() がツールを camelCase メソッドとして公開し、.text()、.json()、.markdown() ヘルパーを提供
CLI 生成	mcporter generate-cli が任意の MCP サーバーをスタンドアロン CLI に変換し、--include-tools / --exclude-tools でフィルタリング
パラメータの非表示	オプションパラメータはデフォルトで非表示となり、スキーマの冗長性を低減

インストール：

npx mcporter list          # インストール不要 — サーバーをすぐに発見
pnpm add mcporter          # プロジェクトに追加
brew install steipete/tap/mcporter  # macOS の Homebrew 経由

例 — TypeScript でツールを構成：

import { createRuntime, createServerProxy } from "mcporter";

const runtime = await createRuntime();
const gdrive = createServerProxy(runtime, "google-drive");
const salesforce = createServerProxy(runtime, "salesforce");

// データはモデルコンテキストを通過せずにツール間を流れる
const doc = await gdrive.getDocument({ documentId: "abc123" });
await salesforce.updateRecord({
  objectType: "SalesMeeting",
  recordId: "00Q5f000001abcXYZ",
  data: { Notes: doc.text() }
});

例 — CLI ツール呼び出し：

# 特定のツールを直接呼び出し
npx mcporter call linear.create_comment issueId:ENG-123 body:'Looks good!'

# 利用可能なサーバーとツールを一覧
npx mcporter list

MCPorter は上述のコード実行アプローチを補完するもので、MCP ツールを型付き API として呼び出すためのランタイム基盤を提供する。中間データをモデルコンテキストの外に保つことを容易にする。

ベストプラクティス

セキュリティに関する考慮事項

推奨 ✅

• すべての認証情報に環境変数を使用する
• トークンと API キーを定期的にローテーションする（毎月推奨）
• 可能な限り読み取り専用トークンを使用する
• MCP サーバーのアクセス範囲を必要最小限に制限する
• MCP サーバーの使用状況とアクセスログを監視する
• 利用可能であれば外部サービスに OAuth を使用する
• MCP リクエストにレート制限を実装する
• 本番運用前に MCP 接続をテストする
• 稼働中の MCP 接続をすべてドキュメント化する
• MCP サーバーパッケージを最新に保つ

非推奨 ❌

• 認証情報を設定ファイルにハードコードしない
• トークンや秘密情報を git にコミットしない
• チームのチャットやメールでトークンを共有しない
• 個人用トークンをチームプロジェクトに使用しない
• 不要な権限を付与しない
• 認証エラーを無視しない
• MCP エンドポイントを公開しない
• MCP サーバーを root/admin 権限で実行しない
• 機密データをログにキャッシュしない
• 認証メカニズムを無効化しない

設定のベストプラクティス

1. バージョン管理： .mcp.json を git に保存するが、シークレットには環境変数を使う
2. 最小権限： 各 MCP サーバーに必要最小限の権限のみ付与する
3. 分離： 可能なら異なる MCP サーバーを別プロセスで実行する
4. 監視： 監査証跡のため、すべての MCP リクエストとエラーを記録する
5. テスト： 本番デプロイ前にすべての MCP 設定をテストする

パフォーマンスのヒント

• 頻繁にアクセスするデータはアプリケーションレベルでキャッシュする
• データ転送量を減らすため、特定の MCP クエリを使う
• MCP 操作のレスポンスタイムを監視する
• 外部 API にはレート制限を検討する
• 複数操作を実行するときはバッチ処理を使う

インストール手順

前提条件

• Node.js と npm がインストール済み
• Claude Code CLI がインストール済み
• 外部サービス用の API トークン/認証情報

ステップバイステップのセットアップ

1. 最初の MCP サーバーを追加（例：GitHub）：

claude mcp add --transport stdio github -- npx @modelcontextprotocol/server-github

または、プロジェクトルートに .mcp.json ファイルを作成：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

2. 環境変数を設定：

export GITHUB_TOKEN="your_github_personal_access_token"

3. 接続をテスト：

claude /mcp

4. MCP ツールを使う：

/mcp__github__list_prs
/mcp__github__create_issue "Title" "Description"

特定サービスのインストール

GitHub MCP：

npm install -g @modelcontextprotocol/server-github

Database MCP：

npm install -g @modelcontextprotocol/server-database

Filesystem MCP：

npm install -g @modelcontextprotocol/server-filesystem

Slack MCP：

npm install -g @modelcontextprotocol/server-slack

トラブルシューティング

MCP サーバーが見つからない

# MCP サーバーがインストールされているか確認
npm list -g @modelcontextprotocol/server-github

# 未インストールならインストール
npm install -g @modelcontextprotocol/server-github

認証失敗

# 環境変数が設定されているか確認
echo $GITHUB_TOKEN

# 必要なら再設定
export GITHUB_TOKEN="your_token"

# トークンが正しい権限を持つか確認
# GitHub のトークンスコープは https://github.com/settings/tokens で確認

接続タイムアウト

• ネットワーク疎通を確認：ping api.github.com
• API エンドポイントが到達可能か確認
• API のレート制限を確認
• 設定でタイムアウトを延ばしてみる
• ファイアウォールやプロキシの問題を確認

MCP サーバーがクラッシュする

• MCP サーバーのログを確認：~/.claude/logs/
• すべての環境変数が設定されているか確認
• 適切なファイル権限を確認
• MCP サーバーパッケージの再インストールを試す
• 同じポートで競合するプロセスがないか確認

関連概念

メモリと MCP

• メモリ： 永続的で変化しないデータを保存（設定、コンテキスト、履歴）
• MCP： 変化するライブデータにアクセス（API、データベース、リアルタイムサービス）

どちらを使うか

• メモリを使う場合： ユーザー設定、会話履歴、学習したコンテキスト
• MCP を使う場合： 現在の GitHub Issue、ライブデータベースクエリ、リアルタイムデータ

他の Claude 機能との統合

• メモリと MCP を組み合わせて豊かなコンテキストを構築
• プロンプト内で MCP ツールを使い、より良い推論を実現
• 複雑なワークフローには複数の MCP を活用

追加リソース

• Official MCP Documentation
• MCP Protocol Specification
• MCP GitHub Repository
• Available MCP Servers
• MCPorter — ボイラープレートなしで MCP サーバーを呼び出すための TypeScript ランタイム＆ CLI
• Code Execution with MCP — コンテキスト肥大化の解決に関する Anthropic のエンジニアリングブログ
• Claude Code CLI Reference
• Claude API Documentation

---

最終更新： 2026 年 8 月 25 日 Claude Code バージョン： 2.1.245 情報源：

• https://code.claude.com/docs/en/mcp
• https://code.claude.com/docs/en/changelog
• https://github.com/anthropics/claude-code/releases/tag/v2.1.117 対応モデル： Claude Sonnet 4.6、Claude Opus 4.7、Claude Haiku 4.5