MCPとCLIはなぜ使い分けるのか：Apidog CLIの設計思想から学ぶAIエージェント統合

126個のMCPツールを構築したチームが、それでも新たにCLIを作り直した。Apidogのエンジニアリングチームが公開したこの事実は、AIエージェントをAPI開発ワークフローに組み込む際の設計上の問題を端的に示しています。

MCPとCLIの「複雑性の置き場所」という違い

MCP（Model Context Protocol）は、AIモデルと外部ツールを接続するためのプロトコルです。Claude や GPT-4 系モデルが外部システムを操作する際の「共通の会話フォーマット」として機能します。シンプルな操作では非常に有効な仕組みで、エンドポイントの取得や単一リソースの参照といった用途には今も十分に機能します。

ただし、多段階ワークフローになると状況が変わります。MCPではモデル自身が以下の情報をコンテキストとして保持し続ける必要があります。どのツールを使うか、どの順番で呼び出すか、戻り値の構造が何を意味するか——これらをモデルが推論しながら処理します。ツール呼び出しが増えるほどコンテキストへの負荷が増し、判断の揺れが起きやすくなります。

Apidogチームが採用した CLI + SKILL という構成は、この複雑性をモデル側ではなくエンジニアリングシステム側に移動させる発想です。役割分担は次のように整理されます。

SKILL：どのワークフローを実行するかを決める「方法論レイヤー」
CLI：APIの読み取り・書き込み・実行といった「製品操作レイヤー」
cli-schema：書き込み前に構造を検証する「バリデーションレイヤー」
agentHints：次のステップを提案する「ナビゲーションレイヤー」

この構成により、エージェントが「次に何をすべきか」を毎回推論するコストを下げられます。ツール呼び出し回数が30%減、トークン消費が25%減という数値は、この構成変更による定量的な結果としてApidogが公開しているものです。

業務システムの文脈で読み解く「読み取り→検証→書き込み」の原則

APIライフサイクル管理という特定の文脈に限らず、この設計思想は既存の業務システムにAIエージェントを組み込む際にも参照できます。

Apidogが推奨する実行パターンは「読み取り → 生成 → 検証 → 書き込み → 実行確認」という順序です。コマンドレベルで示すと次のようになります。

# ステップ1：既存状態を読み取る
apidog endpoint get <endpointId> --project <projectId>

# ステップ2：書き込み前に構造を検証する
apidog cli-schema validate test-case-create --file ./test-case-create.json

# ステップ3：テストを実行して結果を確認する
apidog run --project <projectId> --out-dir ./apidog-reports

エージェントにいきなり「生成して書き込め」と指示するのではなく、まず現在の状態を読ませる。この順序は、既存のデータベーススキーマや業務ルールを扱う場面でも同じ原則が当てはまります。書き込み前のバリデーションステップをエンジニアリングシステムが担うことで、エージェントの推測だけによる変更を防ぐ設計です。

CI/CD統合と「SKILLをコードとして配布する」という考え方

SKILL という概念は、シリーズ第5回のタイトル「運用経験をコードとして出荷する」に端的に表れています。熟練エンジニアが持つ「こういう手順で進めると安定する」という暗黙知を、実行可能なワークフロー定義として記述し、エージェントに参照させるという発想です。

これはドキュメントをコード化するInfrastructure as Code（IaC）の考え方に近いものがあります。IaCがインフラの構成を宣言的に記述してバージョン管理するように、SKILLはAPIテストや変更手順のベストプラクティスをコードとして管理します。チームで共有でき、CI/CDパイプラインにもそのまま組み込めます。

JenkinsやGitHub Actionsといった既存のCI/CD基盤との相性がよいのも、CLIアプローチの実用的な利点です。MCPは専用のMCP互換クライアントが必要になりますが、CLIは標準的なシェル環境があれば動作します。既存のパイプライン定義に数行追加するだけで品質ゲートを挿入できるため、段階的な導入がしやすい構造になっています。

MCPとCLI + SKILLはどちらが優れているかという話ではありません。「シンプルな単一ツール操作かつMCPエコシステムとの統合が必要な場面」ではMCPが適し、「検証ゲートと多段階実行を伴う複雑なワークフロー」ではCLI + SKILLが安定する——この使い分けの軸を持つことが、AIエージェント統合を設計する上での出発点になります。