MCPサーバーのトークンコストと削減方法

モデルは、事前に説明されたツールしか呼び出せず、その説明はリクエスト内部に含まれます：名前、数文の説明文、入力用JSONスキーマです。Anthropicのツール使用料金はこれらすべてをプロンプトの他の部分と同様に入力トークンとしてカウントします。したがってMCPサーバーはトークンを消費し、コーディングエージェントでは毎ターン全コンテキストを再送するため、毎回トークンが使われます。

コストはエージェントが定義を遅延させるかどうかで変わります。2026年9月時点で、Claude Code と最新の Codex CLI は、対応モデルではモデルが要求するまでほとんどのMCPツール定義を保持します。アイドル状態のサーバーは安価ですが無料ではなく、いくつかの設定ではフルコストが再びかかります。

MCPサーバーがリクエストに追加するもの

• →ツール定義：各ツールの名前、説明、JSON入力スキーマ。Anthropic のツール検索ドキュメントでは、GitHub、Slack、Sentry、Grafana、Splunk の5つの一般的なサーバーを例に挙げており、作業開始前にモデルの前に約55,000トークン分の定義が置かれます。
• →サーバー指示：サーバーが接続時に返す短いテキストで、モデルに用途を伝えます。Claude Code はセッション開始時にこれをロードし、デフォルトで2,048文字に切り詰めます。
• →呼び出しと結果：モデルが行う各呼び出しとサーバーが返す各結果はトランスクリプトの一部になります。課題リストやデータベーススキーマを含む結果は数千トークンに達し、キャッシュが残っている間はキャッシュレートで再送され、圧縮またはクリアされるまで続きます。
• →ツール使用システムプロンプト：リクエストにツールが含まれると、Claude API は独自の指示を追加します。2026年9月時点のAnthropic公表表では、Opus 5.5で286トークン、Sonnet 5で354トークン、Haiku 4.5で496トークンです。コーディングエージェントは組み込みツールでも同様に支払うため、MCPサーバーがこれを増幅することはありません。

遅延ロードか事前ロードか：自分の設定を把握する

Claude Code はデフォルトでツール検索を有効にします。セッション開始時にはツール名とサーバー指示だけがコンテキストに入り、ツールの完全なスキーマはClaudeが検索したときにロードされます。Anthropicによると、ツール検索は定義オーバーヘッドを85%以上削減し、リクエストに必要な3〜5個のツールだけをロードします。ロードされた定義は会話に残り、履歴と共に再送されます。

以下の場合、MCP定義は全てのリクエストに完全に戻ります：

• →ANTHROPIC_BASE_URL がAnthropic以外のプロキシやゲートウェイを指す場合。ゲートウェイがツール検索が依存するブロックを転送するなら ENABLE_TOOL_SEARCH=true を設定してください。
• →ENABLE_TOOL_SEARCH=false が設定されている、または CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS が設定されている場合、ENABLE_TOOL_SEARCH が有効でもツール検索はオフのままです。
• →ENABLE_TOOL_SEARCH=auto が設定されていると、定義はコンテキストウィンドウの10%未満であれば事前にロードされます。
• →サーバーが alwaysLoad: true とマークされている場合、そのサーバーのツールは常にロードされます。
• →デプロイがツール検索を拒否するケース：Google Cloud の Agent Platform 上の4.5世代以前のClaudeモデル、または Azure 上の Microsoft Foundry デプロイ。

Claude Codeでオーバーヘッドを確認する

$/context all

/context はウィンドウ内の全内容をカテゴリ別に表示します：システムプロンプト、システムツール、MCPツール、メモリファイル、スキル、メッセージ。all を指定すると項目ごとの内訳が展開されます。セッション開始時に実行すれば何も入力する前の設定コストが分かり、数回ツール呼び出し後に再実行すれば結果が追加したトークンを確認できます。

$/mcp

Pro、Max、Team、Enterprise プランでは、/usage が最近の使用量を個々のMCPサーバーに割り当て、該当サーバーの結果を含むリクエストのみをカウントします。これにより、維持コストではなく使用コストが高いサーバーが分かり、実用的です。

Claude Code は単一のMCP結果が10,000トークンを超えると警告し、デフォルトで MAX_MCP_OUTPUT_TOKENS により結果を25,000トークンに上限します。上限を超える結果はファイルに保存され、会話には内容ではなくパスが渡されます。

Claude Codeで削減する方法

• →プロジェクトで使用しないものはオフにします。/mcp でサーバーをオフにするか、/mcp disable <server> と入力してください。Claude Code はプロジェクト単位で選択を記録し、設定を保持します。
• →サーバーのスコープを必要なプロジェクトに限定します。claude mcp add はデフォルトでローカルスコープ（このプロジェクトのみ）です。--scope user を付けるとマシン上の全プロジェクトでサーバーがロードされ、リポジトリにチェックインされた .mcp.json は承認した全員に適用されます。
• →claude.ai コネクタを確認してください。claude.ai のサブスクリプションでサインインしていると、Claude Code は claude.ai に追加したコネクタを自動的にロードします。プロジェクトの .claude/settings.json に "disableClaudeAiConnectors": true を設定するか、ENABLE_CLAUDEAI_MCP_SERVERS=false で Claude Code を起動すれば除外できます。
• →CLI が存在する場合はそれを使用します。Anthropic のコストガイダンスでは、gh、aws、gcloud、sentry-cli はツールごとのリストを全く追加せず、Claude はそれらを直接実行できます。
• →遅延ロードをオンに保ちます。alwaysLoad は毎ターン必要な少数のツールに限定してください。
• →不要な単一ツールは削除します。mcp__<server>__<tool> 形式の権限拒否ルールで指定すれば、Claude のコンテキストから除外できます。

長いツールリストはトークンだけでなく精度も低下させる

大規模なカタログには別のコストがあります。Anthropic のドキュメントでは、Claude のツール選択が劣化し始めるのは利用可能ツールが30〜50個程度とされています。遅延ロードは検索された少数のツールだけをClaudeが見るため助けになりますが、カタログ自体を小さくする方が効果的です。

サーバーを自作または選択する場合、Anthropic のツール設計ガイドラインは同様に示しています：関連操作を action パラメータでまとめた単一ツールに統合し、サービス名でプレフィックス（github_、slack_）を付けて検索でグループ全体を取得し、次のステップが必要とするフィールドだけを返す。ツール数を減らし範囲を広げることで定義が小さくなり、簡潔なレスポンスはトランスクリプトに残る部分も縮小します。

ツール変更がキャッシュを壊すとき

プロンプトキャッシュはプレフィックスマッチです。Claude API ではプレフィックスは固定順序で構築され、tools、system、messages の順です。ツールの名前、説明、パラメータを変更するとキャッシュ全体が無効化されます。次のリクエストはキャッシュから読むのではなく、全会話を新たな入力として処理し、2026年9月時点の多くのモデルでは入力価格の約1/10のコストで済んでいたはずです。

Claude Code ではロードモードに依存します。遅延ツールの場合、サーバーの接続・切断・ツールリスト変更は会話に追記されるだけで、キャッシュプレフィックスは維持されます。事前ロードの場合、いずれの変更もキャッシュを無効化し、ローカルサーバーのプロセス終了やリモートセッションの期限切れ、一時的な障害後の再接続など、ユーザーが何もしなくても起こり得ます。MCP 設定の編集は次回起動時に反映されるため、事前ロード時にサーバーを追加・削除する最適なタイミングはセッション間です。

Codex CLI

Codex CLI は MCP サーバーを ~/.codex/config.toml、または信頼できるプロジェクト内の .codex/config.toml に保存し、サーバーごとに [mcp_servers.<name>] テーブルを1つ作ります。CLI、IDE 拡張、ChatGPT デスクトップアプリは同じ設定を共有するため、どれかで追加したサーバーはすべてで利用可能です。

課金構造は同様です：Codex が公開するすべてのツールがモデルに説明され、すべての結果がトランスクリプトに加わります。現在のリリース（2026年9月時点で0.156）では、対応モデルで検索ツールの背後にMCP定義を遅延させ、サーバーは事前にリスト化します。この挙動はドキュメントではなくオープンソースコードに実装されているため、現状のものとして扱い、永続的とはみなさないでください。

$/mcp verbose

/status はセッションのトークン使用量と残りコンテキストを表示します。スイッチは同じ設定ファイルにあります：

• →enabled = false はエントリを削除せずにサーバーをオフにします。
• →enabled_tools はリストしたツールだけを公開し、disabled_tools は許可リスト適用後にいくつかを除外します。
• →tools.<tool>.output_token_limit はサーバーのテーブル内で特定ツールの出力トークン上限を設定し、モデルのデフォルト切り捨てを上書きします。
• →リポジトリが必要とするサーバーはグローバルファイルではなく、そのリポジトリの .codex/config.toml に配置します。

課金の残りの部分

定義を遅延させ、アイドルサーバーをオフにすると、残るのはコンテキストそのものです：エージェントが読むファイル、コマンド出力、そしてそれらを含む履歴です。これが capsul が対象とする部分で、既にサインインしている Claude Code または Codex CLI がタスクに必要なものだけを送信し、設定した予算で停止し、除外された内容を通知します。

$capsul ask 'why does the webhook handler retry twice' --budget 3000