DEV Community

Cover image for AIエージェント内でAPI管理を完結する方法
Akira
Akira

Posted on • Originally published at apidog.com

AIエージェント内でAPI管理を完結する方法

Cursor、Claude Code、VS CodeでAPI実装を書いている途中に、仕様確認のためブラウザへ切り替えるとコンテキストが途切れます。Apidog MCPサーバーを使うと、API仕様をAIエージェントに直接渡せます。エージェントはエディター内で契約を読み取り、参照し、仕様に沿ったコードを生成できます。

今すぐApidogを試す

なぜAIエージェントにAPI仕様を渡すべきか

AIエージェントはAPIクライアント、DTO、ハンドラー、テストコードを高速に生成できます。ただし、仕様がコンテキストにない場合は推測でコードを書きます。

たとえば、Cursorに次のように依頼したとします。

POST /orders を呼び出す TypeScript 関数を作成して
Enter fullscreen mode Exit fullscreen mode

仕様がなければ、エージェントは以下のようなミスを起こしがちです。

  • 存在しないフィールド名を使う
  • enum値を誤る
  • statusの型を間違える
  • 必須フィールドを落とす
  • レスポンスコードごとの分岐を実装しない

この問題を減らすには、エージェントに真のソースを渡します。つまり、APIデザインそのものを読ませます。MCPサーバーをAPI仕様に接続すると、エージェントは推測ではなく契約に基づいてコードを生成できます。

ここでいう「APIを管理する」とは、設計時の作業を指します。

  • API契約を読む
  • エンドポイントやスキーマを参照する
  • DTOやクライアントコードを生成する
  • 仕様に基づいてコメントやテストを作る

ランタイムのトラフィック管理ではありません。ApidogはAPIゲートウェイではなく、本番リクエストのルーティング、スロットリング、認証プロキシのような役割は担いません。KongやApigeeの代替ではなく、APIの設計、モック、テスト、ドキュメントのライフサイクルを支援するツールです。

Apidog MCPサーバーでできること

Apidog MCPサーバーは、AIコーディングツールにAPI仕様への読み取りアクセスを提供します。接続後、エージェントは仕様をオンデマンドで参照できます。

主な用途は次のとおりです。

  • API仕様に基づいてコードを生成する
  • エンドポイント、リクエスト、レスポンス、スキーマを検索する
  • 仕様に追加されたフィールドに合わせてDTOを更新する
  • コードに仕様ベースのドキュメントコメントを追加する
  • 特定エンドポイント向けのMVCコードを生成する

MCPサーバーはローカルで動作し、MCP対応のAIツールと連携します。

  • Cursor
  • VS CodeのMCP対応AI拡張
  • Claude Code
  • その他のMCP対応コーディングエージェント

基本的な流れは次のとおりです。

  1. API仕様ソースを用意する
  2. Apidog MCPサーバーを起動する
  3. CursorやClaude CodeにMCPサーバーを登録する
  4. エージェントに「仕様を参照して実装して」と依頼する

仕様ソースを接続する3つの方法

Apidog MCPサーバーは、複数の仕様ソースに対応します。

ソース 必要なトークン 使いどころ
Apidogプロジェクト パーソナルアクセストークン チーム内のプライベートAPIをApidogで設計している場合
公開されたApidogドキュメント なし 公開済みAPIドキュメントをエージェントに参照させたい場合
Swagger / OpenAPIファイル（ローカルまたはURL） なし リポジトリ内や外部URL上のOpenAPI仕様を使う場合

重要なのは、Apidogプロジェクトを使っていなくてもOpenAPIファイルを読み込める点です。

たとえば、リポジトリに次のようなファイルがある場合です。

api/
  openapi.yaml
src/
  handlers/
  clients/
Enter fullscreen mode Exit fullscreen mode

このopenapi.yamlをMCPサーバー経由でエージェントに読ませれば、エージェントは仕様に沿ってDTO、APIクライアント、ハンドラー、テストを生成できます。

実装時のプロンプト例

MCPサーバーを接続したら、エージェントには仕様を明示的に参照させます。

Apidog MCPサーバーで POST /subscriptions の仕様を確認し、
リクエストDTO、レスポンスDTO、Expressのハンドラーを生成してください。
必須フィールド、enum、レスポンスコードは仕様に合わせてください。
Enter fullscreen mode Exit fullscreen mode

DTOを更新したい場合は次のように依頼できます。

Apidog MCPサーバーから GET /users/{id} の最新仕様を読み取り、
既存の UserResponse 型に不足しているフィールドを追加してください。
既存のフィールド名は変更しないでください。
Enter fullscreen mode Exit fullscreen mode

ドキュメントコメントを追加したい場合は次のようにします。

仕様を参照して、OrderClient の各メソッドにJSDocコメントを追加してください。
summary、リクエストパラメータ、主なレスポンスコードを含めてください。
Enter fullscreen mode Exit fullscreen mode

ポイントは、単に「作って」ではなく「MCPサーバーから仕様を確認して」と指示することです。

制限事項

Apidog MCPサーバーを使う前に、できないことも理解しておく必要があります。

読み取り専用

Apidog MCPサーバーは仕様データをエージェントに提供する読み取り専用の仕組みです。エージェントがMCPサーバー経由でAPI設計を書き換えることはできません。

契約を変更する場合は、ApidogプロジェクトまたはOpenAPIファイルを更新します。その後、エージェントに最新仕様を読み直すよう依頼します。

ローカルキャッシュを使う

サーバーは速度のために仕様データをローカルにキャッシュします。Apidog側で仕様を変更した直後は、エージェントが古い仕様を参照する可能性があります。

設計を変更した後は、次のように明示します。

Apidog MCPサーバーの仕様を更新してから、POST /subscriptions を再確認してください。
Enter fullscreen mode Exit fullscreen mode

APIゲートウェイではない

MCPサーバーは仕様を読み取り、設計時のコード生成を支援するものです。本番トラフィックのルーティング、レート制限、プロキシ処理は行いません。

Apidogツールチェーンとの組み合わせ

MCPサーバーは、APIライフサイクル全体の一部です。Apidogでは、同じ契約をもとに次の作業をつなげられます。

  • 仕様設計
  • モック
  • テスト
  • ドキュメント
  • AIエージェントへの仕様提供

バックエンド実装前にモックする

フロントエンドやAIエージェントの実装は、バックエンド完成を待つ必要はありません。Apidogでは仕様からモックサーバーを生成できます。

これにより、次のような流れを作れます。

  1. Apidogでエンドポイントを設計する
  2. モックURLを発行する
  3. フロントエンドをモックに対して実装する
  4. エージェントにモックURLを使ったテストを生成させる
  5. 実装完了後、本番APIに切り替える

モックの基本はモックAPIの解説とAPIモックガイドが参考になります。ツール比較をしたい場合は、最高のAPIモックツール比較も確認できます。

CIでAPIテストを実行する

設計だけでは不十分です。実装が契約に合っているかをCIで検証する必要があります。

Apidog CLIでは、apidog runでテストシナリオをヘッドレス実行できます。

たとえば、CIでは次のような使い方になります。

apidog run
Enter fullscreen mode Exit fullscreen mode

Apidog CLIは、テスト結果を複数形式で出力できます。

  • CLI出力
  • HTML
  • JSON
  • JUnit

JUnit形式を出力すれば、CI上でテストレポートとして扱えます。コマンドラインでREST APIテストを回す流れは、コマンドラインREST APIテストチュートリアルで確認できます。

API テスト レポート

AIエージェントと組み合わせる場合は、エージェントにCLI実行とレポート解析を任せられます。

apidog run を実行し、失敗したテストだけを要約してください。
失敗原因がレスポンススキーマ不一致なら、該当する実装ファイルも確認してください。
Enter fullscreen mode Exit fullscreen mode
ステージ Apidog要素 エージェント内での扱い
契約を読む MCPサーバー（読み取り専用） MCP経由で直接参照
エンドポイントをモックする モックサーバー モックURLに対してコードやテストを生成
実装をテストする Apidog CLI（apidog run） エージェントがシェルから実行し、結果を読む
ライフサイクルを管理する Apidogプロジェクト 設計時の契約をMCP経由で提供

Cursor内での実用的なワークフロー

たとえば、既存サービスにPOST /subscriptionsを追加するとします。

  1. ApidogプロジェクトでPOST /subscriptionsを設計する
  2. リクエストスキーマ、レスポンススキーマ、ステータスコードを定義する
  3. CursorにMCPサーバーを接続する
  4. エージェントにハンドラーとDTOの生成を依頼する
  5. モックURLに対するテストを生成する
  6. apidog runを実行する
  7. 失敗したテストをエージェントに解析させる
  8. 仕様を変更した場合は、エージェントに再読み込みを依頼する

プロンプト例は次のとおりです。

Apidog MCPサーバーで POST /subscriptions の仕様を読み、
Node.js + Express 用のルート、ハンドラー、DTO、基本的なバリデーションを作成してください。
レスポンスコードは仕様に定義されたものだけを使ってください。
Enter fullscreen mode Exit fullscreen mode

テスト生成は次のように依頼できます。

POST /subscriptions の仕様を参照して、正常系とバリデーションエラーのテストを作成してください。
モックサーバーのURLを使って実行できる形にしてください。
Enter fullscreen mode Exit fullscreen mode

仕様変更後は次のようにします。

Apidog MCPサーバーの仕様を更新し、POST /subscriptions のDTOとテストを最新仕様に合わせて修正してください。
Enter fullscreen mode Exit fullscreen mode

このループでは、ブラウザで仕様を探し回る必要がありません。契約はApidogまたはOpenAPIファイルに残り、エージェントはその契約を参照して実装します。

視覚的なデバッグの流れは、Apidog MCPクライアントでの視覚的なデバッグで確認できます。MCPサーバー自体のテストについては、MCPサーバーテストプレイブックが参考になります。

他のCLI・仕様ツールとの違い

APIまわりには多くのCLIやモックツールがあります。それぞれ役割が異なります。

  • Newman

    Postmanコレクションをコマンドラインで実行するランナーです。コレクション実行には強いですが、MCP経由でAIエージェントに設計時の契約を渡す仕組みではありません。

  • inso（Insomnia CLI）

    ターミナルからコレクションを実行し、仕様をlintできます。ただし、仕様をエディター内のAIエージェントへ渡すMCPブリッジではありません。

  • Prism

    OpenAPIファイルに対するモックと検証に強いツールです。仕様駆動のモックには向いていますが、設計、モック、テスト、ドキュメント、MCP連携をまとめて扱うプラットフォームではありません。

  • WireMock / Mockoon CLI

    モックサーバーとして有用です。ただし、契約ライフサイクル全体の管理やMCP経由での仕様公開は主目的ではありません。

Apidogの位置づけは、単なるランナーではありません。1つのAPI契約をもとに、設計、モック、テスト、ドキュメント、AIエージェントへの仕様提供をつなげる点が中心です。

CLI比較をしたい場合は、Apidog CLI vs Postman CLIの比較が参考になります。CI/CD全体の考え方は、CI/CDテスト実践ガイドで整理されています。

よくある質問

AIエージェントはMCPサーバー経由でAPI仕様を編集できますか？

いいえ。Apidog MCPサーバーは読み取り専用です。エージェントは仕様を読み、検索し、仕様に基づいてコードを生成できますが、MCPサーバー経由で設計を書き換えることはありません。

仕様を変更する場合は、ApidogまたはOpenAPIファイルを更新し、その後エージェントに最新仕様の再読み込みを依頼します。

MCPサーバーを使うためにApidogアカウントは必要ですか？

すべてのケースで必要なわけではありません。

プライベートなApidogプロジェクトに接続する場合は、パーソナルアクセストークンが必要です。一方で、公開されたApidogドキュメントやSwagger/OpenAPIファイルは、トークンなしで読み取れます。

ローカルのopenapi.yamlから始めることもできます。

これはAPIゲートウェイですか？

いいえ。Apidog MCPサーバーとApidogプラットフォームは、APIの設計、モック、テスト、ドキュメント作成を支援するデザイン時のツールです。

APIを製品として扱い、ライフサイクルを管理するためのものです。本番トラフィックのルーティングやスロットリングは行いません。その用途にはKongやApigeeのようなAPIゲートウェイが必要です。

どのAIツールと連携できますか？

MCP対応のAIコーディングツールで利用できます。たとえば次のようなツールです。

  • Cursor
  • VS CodeのMCP対応環境
  • Claude Code

ツールごとにMCPサーバーを登録し、仕様ソースを指定すれば、エージェントがその仕様を照会できます。

まとめ

Apidog MCPサーバーを使うと、API契約をAIエージェントの作業コンテキストに直接渡せます。Cursor、Claude Code、VS Code内で仕様を参照できるため、エージェントは推測ではなく契約に基づいてコードを生成できます。

実用的な流れは次のとおりです。

  1. ApidogまたはOpenAPIでAPI契約を管理する
  2. MCPサーバーでエージェントに仕様を提供する
  3. 仕様に基づいてDTO、ハンドラー、クライアント、テストを生成する
  4. モックサーバーでバックエンド完成前に検証する
  5. apidog runでCI上のAPIテストを実行する

ただし、Apidog MCPサーバーはランタイムゲートウェイではありません。設計時のAPIライフサイクル管理に使うものです。

試す場合は、Apidogをダウンロードし、MCPサーバーをエディターに接続して、AIエージェントを実際のAPI仕様に向けてください。Apidogのプラットフォームドキュメントでは、各仕様ソースの使い方を確認できます。

Top comments (0)