MCP vs CLI の違いは、エージェントがツールのコストを「いつ」払うかという点に尽きます。MCP サーバーは、ユーザーが何かを入力する前に、すべてのツールの名前・説明・JSON Schema をモデルへ送信します。一方 CLI は、エージェントが実際に実行して --help や出力を読むまでコストはゼロです。実測した環境では、4 つの一般的な MCP サーバーで 11,923 トークンのツール定義が追加されたのに対し、Apidog CLI スキルはわずか 112 トークンでした。
この差こそが、今週の Dev.to の 2 つの投稿の背景にある全体像です。ある開発者はコーディングエージェントに「Run tests」と入力しただけで、ファイルも履歴も添付していないのに最初のリクエストで 28,400 入力トークンを消費しました。原因は 7 つの MCP サーバーでした。別の投稿では、MCP は構築が非常に簡単である一方、難しい部分(認証、承認、重複呼び出し)はデモが動いた直後に始まると論じています。
本記事は 1 つの問いに焦点を絞ります。ツール定義はコンテキストウィンドウにどれだけのコストをかけ、エージェントが必要に応じて呼び出す CLI はどのような場合にコストが少なくて済むのか。問題が巨大なツールレスポンスにある場合は、肥大化した API レスポンスの削減に関する姉妹記事をお読みください。
なぜ MCP サーバーはコンテキストウィンドウのトークンを消費するのか
MCP サーバーは tools/list メソッドを通じてツールを公開します。MCP ツール仕様によれば、各ツールには name、description、inputSchema(引数の JSON Schema)が含まれます。モデルがツールを選択するには、クライアントがこれらの定義をリクエストに含める必要があります。典型的な構成では、エージェントがツールを呼び出すかどうかにかかわらず、会話の毎ターンでこれが行われます。
つまりコストは次の 3 つの要素で増加します。
- ツール数。完全な GitHub 連携では数十個のツールが公開されることがあります。
- スキーマの深さ。ネストされたオブジェクト、列挙型、長い説明はすべてトークンになります。
- ターン数。エージェントループは各ステップで定義を再送信します。
necoz の投稿はこれに数字を示しています。52 ツールのスタックではターン 1 で 24,600 トークンのスキーマがかかるのに対し、4 ツール構成では 640 トークン、10 ステップのループ全体では約 246,000 トークンでした。これらは 1 人の開発者の測定値であり、ベンチマークとして扱うべきではありません。プロンプトキャッシュは定義の繰り返しによるドルコストを削減しますが、トークン自体はウィンドウを占有し、コードとの「注意」の取り合いになります。
品質面のコストもあります。Anthropic のツール検索ドキュメントによれば、GitHub、Slack、Sentry、Grafana、Splunk を組み合わせたマルチサーバー構成では「Claude が何も作業する前に約 55k トークンを定義だけで消費する」可能性があり、利用可能なツールが 30〜50 を超えると Claude のツール選択精度が低下するといいます。
MCP ツール定義トークン:誰でも再現できる計測
2026-11-16 に私は 5 つの MCP サーバーをローカルで stdio 経由で起動し、30 行の Node スクリプトから initialize と tools/list を送信し、各ツールの name、description、inputSchema のトークン数を数えました。
最初に注意点を 1 つ。オフラインで動作するため OpenAI の tiktoken の o200k_base エンコーディングで計測しました。Claude、Gemini などのモデルは独自のトークナイザーを使用するため、カウントは多少異なります。ここで重要なのは構成間の比率です。
| MCP サーバー(バージョン) | ツール数 | 定義トークン | ツールあたり平均 |
|---|---|---|---|
@playwright/mcp 0.0.85 |
25 | 4,634 | 185 |
@modelcontextprotocol/server-filesystem 2.3.0 |
16 | 3,281 | 205 |
@modelcontextprotocol/server-memory 2.1.1 |
9 | 2,013 | 224 |
@modelcontextprotocol/server-everything 2.3.0 |
16 | 1,995 | 125 |
| 上記 4 つの合計 | 66 | 11,923 | 181 |
apidog-mcp-server 0.0.18 |
3 | 291 | 97 |
ありふれた 4 つのサーバーだけで、エージェントがファイルを 1 つ読む前に約 12,000 トークンかかっています。
最終行が有用な反例です。Apidog MCP サーバーは 3 つの限定されたツール(プロジェクトの OpenAPI 仕様の読み取り、$ref ファイルの読み取り、仕様の更新)のみを公開するため、291 トークンで済みます。コストを左右するのはプロトコルではなく、ツール数とスキーマの深さです。
CLI 側については、エージェントが Apidog CLI 2.2.12 を使用する際に実際に読み取る内容を測定しました。
| CLI テキスト | コンテキストに入るタイミング | トークン |
|---|---|---|
| Apidog CLI スキルの説明(frontmatter) | 毎セッション、スキル一覧として | 112 |
| Apidog CLI スキル本文 | タスクが一致する場合のみ | 1,189 |
apidog --help |
エージェントが実行した場合のみ | 668 |
apidog test-case --help |
エージェントが実行した場合のみ | 511 |
apidog run --help |
エージェントが実行した場合のみ | 1,036 |

CLI ルートの常時コストは 112 トークンです。エージェントがスキル全体を読み込み、3 つのヘルプページを読んだとしても約 3,500 トークン程度であり、しかも必要とする会話でのみ発生します。
MCP vs CLI:トークンコストの比較
| MCP サーバー(定義を事前に読み込み) | シェル経由で呼び出す CLI | |
|---|---|---|
| 事前コスト | 毎ターンで全ツールのスキーマ | ゼロ、または短いスキル説明のみ |
| 探索 | 構造化された tools/list |
--help テキストを必要時に読む |
| 出力 | ツールが返すものすべて | コマンドが出力するもの(フィルタ可能) |
| クライアント間の互換性 | 1 つの設定で任意の MCP クライアント | シェルツールを持つ任意のエージェント |
| 型付き引数 | あり(JSON Schema 経由) | フラグ。ペイロードファイルは別途検証 |
| 認証と権限 | サーバーの役割(リモート HTTP サーバーは OAuth) | ローカルのログインとシェル権限 |

CLI が事前コストで優位なのは、エージェントがすでにシェルツールを持っているからです。apidog endpoint list --project 123 の実行には、いずれにせよ読み込まれる Bash ツールを使います。一方 MCP ルートが優位なのは、各クライアント向けに統合コードを書かずに複数クライアントで同じ機能を使いたい場合です。これが Sylwia Lask の指摘する点であり、MCP は REST の代替ではなく、AI クライアントがツールを発見・呼び出すための標準的な方法なのです。
クライアントがすでに MCP ツールの遅延読み込みに対応している場合も
サーバーをすべて削除する前に、自分のエージェントの動作を確認しましょう。前述のコストは定義が事前に読み込まれる前提です。一部のクライアントはデフォルトでそうしなくなっています。
Claude Code の MCP ドキュメントによれば、ツール検索はデフォルトで有効になっており、「セッション開始時に読み込まれるのはツール名とサーバーの指示のみ」で、完全な定義は Claude が検索したときに読み込まれます。ENABLE_TOOL_SEARCH で制御できます。
- 未設定または
true:MCP ツールは遅延され、必要時に読み込まれる auto:定義の合計がコンテキストウィンドウの 10% 未満の間は事前に読み込むauto:N:同様だが、自分で割合を指定false:すべての MCP ツールを事前に読み込む
2 つの例外があります。Opus 4 や Sonnet 4 より前のモデルは設定に関係なく MCP ツールを事前に読み込むこと、そして alwaysLoad: true に設定されたサーバーは遅延の対象外になることです。Claude Code で /context を実行すると、どのツールが遅延対象かを確認できます。Claude API 自体では、同じ考え方がツール検索ツールとして実装されており、事前に読み込むべきでないツールに defer_loading: true を設定します。Anthropic によれば、これにより定義トークンが通常 85% 以上削減されるといいます。
遅延読み込みが解決するのは定義コストであって出力コストではありません。Claude Code は MCP ツールが 10,000 トークンを超える出力を返したときに警告し、デフォルトでは出力を 25,000 トークンに制限します(MAX_MCP_OUTPUT_TOKENS)。プロトコルが初めての方は、MCP とは何か、なぜ API にとって重要なのかから始めてください。
API 作業で MCP と CLI のどちらを使うべきか
API の設計、テスト、ドキュメントについては、次のように使い分けましょう。
- CLI を使うのは、ターミナルで実行するような作業(エンドポイントの一覧表示、OpenAPI ファイルのエクスポート、テストケースの作成と実行、CI でのスイート実行)の場合です。エージェントは必要なときだけヘルプテキストのコストを払い、出力を
jqや--reportersでパイプして短くすることもできます。 - 限定された MCP サーバーを使うのは、エージェントが毎ターン構造化された読み取りアクセスを必要とする場合(クライアントコードを書きながら OpenAPI 仕様を読むなど)です。3 ツールで 291 トークンなら妥当な価格です。
- 避けるべきなのは、5 つ以上のサーバーを全プロジェクトでグローバルに有効化しておくことです。28,400 トークンの「Run tests」を生んだのはまさにこの構成です。
どちらを選ぶ場合でも、Sylwia の警告は通用します。データを書き込むツールにはサーバー側の権限チェック、危険な操作には人間の承認ステップ、再実行で同じレコードが重複作成されないための重複検出が必要です。
コーディングエージェントに Apidog CLI を操作させよう
API 作業における CLI ルートの紹介です。タイピングはコーディングエージェントが行います。CLI をインストールし、一度ログインしてエージェントスキルを追加してください。
npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com # pick your agent when prompted
また、エージェントに「https://apidog.com/apidog-cli-installation-guide.md を読んで Apidog CLI をセットアップして」と指示すれば、エージェントフレンドリーなインストールガイドに従って作業してくれます。
あとは 1 つのプロンプトを与えるだけです。
In Apidog project 123, list the endpoints, export the spec as OpenAPI 3.1 to
./openapi.json, then create a test case for GET /users/{id} that asserts a 200
status and an id field, run it against environment 456 and summarize failures.
Read --help for each command before using it. Print only the lines you need.
エージェントは作業中にヘルプを読み、JSON を検証し、テストケースを実行します。
apidog endpoint list --project 123 --page 1 --page-size 500
apidog export --project 123 --format openapi --oas-version 3.1 --output ./openapi.json
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project 123 --file case.json
apidog run --test-case <caseId> --project 123 -e 456 -r cli,json
各コマンドは agentHints.nextSteps を含むことが多い構造化された JSON を返すため、エージェントはありとあらゆる操作のスキーマを読み込まなくても次に何を実行すべきかを把握できます。同じ apidog run ... -r junit のコマンドはそのまま CI に組み込めます。詳細は Apidog CLI CI/CD パイプラインガイドをご覧ください。Claude Code での手順については Claude Code での Apidog CLI を、実測されたツール呼び出しの削減については ツール呼び出し 30% 減、トークン 25% 減を参照してください。
始める前にすべてのコマンドグループを確認したい方は、Apidog CLI のページをお読みください。
今すぐ MCP のトークンコストを削減する方法
- Claude Code(または使用クライアントの同等機能)で
/contextを実行し、ツール定義の合計を確認する。 - 不要なサーバーをグローバル設定からプロジェクト設定に移動する。
- 遅延読み込みを有効にする(Claude Code では
ENABLE_TOOL_SEARCH)。 - 幅広いサーバーを、ターミナル向きの作業用の CLI と短いスキルに置き換える。
- 自分でサーバーを構築する場合は、ツールを少なく、説明を短く保つ。
FAQ
エージェントが呼び出さない MCP ツールもトークンを消費しますか? 定義を事前に読み込むクライアントでは、はい。すべてのツールの名前、説明、入力スキーマが各リクエストに含まれます。ツール検索を有効にした Claude Code のような遅延読み込み対応クライアントは、ツールが必要になるまでツール名のみを送信します。
MCP サーバーはどれくらいのトークンを使いますか? ツール数とスキーマの深さによります。私の計測では、@playwright/mcp は 25 ツールで 4,634 トークン、Apidog MCP サーバーは 3 ツールで 291 トークンでした(o200k_base トークナイザーで計測)。
AI エージェントにとって CLI は常に MCP より安価ですか? 事前コストではほぼ常にそうです。エージェントがシェルツールを再利用するからです。ただし呼び出しごとには、エージェントが大きなペイロードを出力すると CLI でもコンテキストがあふれる可能性があるため、どちらの方法でも出力をフィルタしましょう。
プロンプトキャッシュで MCP のコンテキスト肥大化は解決しますか? 定義の繰り返しによる価格は下がります。しかしコンテキストウィンドウは解放されず、モデルは毎ターンそれらのトークンに注意を払い続けます。
MCP サーバーの使用をやめるべきですか? いいえ。構造化された毎ターンのアクセスや、複数クライアント間での機能共有には、限定されたサーバーを使いましょう。エクスポートやテスト実行のようなターミナル向きの API 作業は CLI に移行してください。
