Cursor Composer 2.5 でAPIを構築する方法

Cursor Composer 2.5は高速かつ安価なため、エージェントがAPIクライアント全体やルートハンドラを記述できます。しかし、そのコードが実際のサービスに触れた瞬間に問題が発生します。モデルは/v2/ordersにきれいなリクエストを記述しますが、実際にはサービスは/ordersを公開しており、異なるペイロードを期待しているのです。コードはコンパイルされますが、動作せず、3つのファイルを見た後にその問題に気づきます。

このガイドでは、その問題を解決するワークフローを紹介します。Composer 2.5をMCP経由で実際のAPI仕様に向けさせ、実際のコントラクトに基づいてコードを生成させ、チームメイトに渡す前にApidogで結果を検証します。このモデルが初めての方のために、Cursor Composer 2.5ガイドでは、その概要とアクセス方法について説明しています。

ボタン

なぜエージェント型モデルはAPIの形状を推測するのか

Composer 2.5は、長く多段階にわたるエージェントタスク向けに構築されています。「請求サービス用のクライアントを追加し、それを決済フローに組み込む」ように指示すると、計画を立て、複数のファイルを編集し、テストが成功するまで実行します。これがComposer 2からのアップグレードであり、非常に便利です。

弱点はバグではなく、構造的なものです。モデルがあなたのAPIコントラクトをコンテキストに持っていない場合、それは統計的に最も可能性の高い形状でそのギャップを埋めます。一般的なフィールド名、RESTの慣習、トレーニングで最も多く見たバージョンプレフィックスなどです。出力は正しく見えます。Linterも通過します。しかし、あなたのサーバーに対しては失敗します。なぜなら、あなたのサーバーはインターネット上のあらゆるAPIの平均ではないからです。

この3つの症状です。

ほぼ一致するエンドポイント（/api/users/{id}とあなたの/users/{userId}の違いなど）。
リクエストボディ内の誤った、または勝手に作成されたフィールド。
サービス本来のスキームではなく、汎用的な方法で処理される認証。

プロンプトで一部を回避することはできますが、OpenAPIファイル全体をチャットに貼り付けるのは不安定でコンテキストを消費します。永続的な解決策は、モデルに仕様への構造化されたアクセスを与えることです。

解決策：MCPを介してComposer 2.5を実際のAPI仕様に基づかせる

Model Context Protocol (MCP) は、ツールとデータをAIモデルに提供するためのオープン標準です。CursorはMCPサーバーをサポートしており、Apidog MCPサーバーは、ApidogのAPI仕様を、モデルがコーディング中にクエリできる構造化された情報源として公開します。

実際の違いは、Composer 2.5が推測する代わりに、実際のエンドポイント、スキーマ、パラメーター、レスポンスの形状を読み取り、それらに基づいてコードを記述することです。これは、Apidog MCPサーバーでのバイブコーディングの背後にある考え方と同じで、現在はタスク全体を実行できるほど強力になったモデルに適用されています。

ステップ1: ApidogでAPI仕様を準備する

あなたのAPIコントラクトは、モデルが読み取れる場所に存在する必要があります。スキーマ、エンドポイント、例が最新になるように、ApidogでAPIを設計またはインポートしてください。既存のドキュメントから始める場合は、ApidogはOpenAPIとPostmanコレクションを直接インポートできます。仕様はモデルが従う真実の源であるため、それを正確に保つことが最も重要です。

ステップ2: Apidog MCPサーバーをCursorに接続する

Cursorは、プロジェクト内の設定ファイル（通常.cursor/mcp.json）からMCPサーバーを読み取ります。Apidog MCPサーバーはnpxを介して実行され、あなたのプロジェクトを指します。典型的な設定は次のようになります。

{
  "mcpServers": {
    "apidog-api-spec": {
      "command": "npx",
      "args": ["-y", "apidog-mcp-server@latest", "--project=<your-project-id>"],
      "env": { "APIDOG_ACCESS-TOKEN": "<your-access-token>" }
    }
  }
}

これらの値はあなたのアカウントとサーバーのバージョンに固有のものであるため、Apidog MCPセットアップウォークスルーに記載されている正確なコマンド、プロジェクトID、およびトークンを使用してください。保存後、新しいサーバーが認識されるようにCursorを再起動してください。

ステップ3: Composer 2.5が仕様を認識できることを確認する

エージェントセッションを開き、モデルピッカーでcomposer-2.5を選択し、まず読み取り専用の質問をしてください。

「apidog-api-spec MCPサーバーを使用して、注文リソースのエンドポイントと注文作成に必要なフィールドをリストアップしてください。」

もしそれが実際のエンドポイントとフィールドを返せば、接続は機能しています。もし一般的な知識から回答する場合、サーバーは接続されていません。設定を再確認し、再起動してください。

ステップ4: コントラクトに基づいて構築させる

次に、実際のタスクを与え、仕様を明示的に指定します。

「真実の源としてapidog-api-specサーバーを使用して、注文API用の型付きTypeScriptクライアントを記述してください。これにはcreate-orderおよびget-order呼び出しを含めます。リクエストおよびレスポンススキーマを正確に一致させてください。また、仕様で定義されている422検証レスポンスのエラー処理も追加してください。」

Composer 2.5は長時間のタスクをうまく維持できるため、複数のファイルにわたってこれを実行し、コントラクトの一貫性を保つことができます。プロンプトでMCPソースを指定することで、モデルが仮定に戻ってしまうことなく、正確な情報に基づいた作業を継続できます。

信頼する前に検証する: Apidogテストループ

モデルを根拠づけることで、幻覚を大幅に減らすことができます。しかし、検証はオプションではありません。仕様は実行中のサービスよりもわずかに遅れることがあり、モデルは依然としてエッジケースを誤解する可能性があります。

ループを閉じます。

生成された呼び出しを実際の要求として送信します。 Composer 2.5が記述したエンドポイントをApidogで実際の環境またはモック環境に対して実行します。ステータスコード、レスポンスボディ、認証がコードが想定する通りに動作するかを確認します。
機能する呼び出しをテストに変換します。 検証済みのリクエストを自動テストシナリオとして保存し、次のリグレッションがユーザーではなくCIによって捕捉されるようにします。
まだ構築されていないものをモック化します。 モデルがバックエンドがまだ出荷していないエンドポイントのクライアントを記述した場合、Apidogのモックサーバーは現実的なレスポンスを返し、フロントエンドの作業を続行できます。これは、AIエージェントとAPIテストのパターンとうまく連携します。

原則：モデルはコントラクトに基づいて初稿を記述し、あなたはそれが実際のサーバーに対してどのように動作するかを確認します。エージェントによるスピードは、後でデバッグに時間を費やさなければ、初めてその真価を発揮します。

現実的なエンドツーエンドの例

決済サービスに返金機能を追加する場合を考えてみましょう。

返金エンドポイントとスキーマは、設計段階ですでにApidogプロジェクトに存在しています。
Apidog MCPがCursorに接続され、Composer 2.5が選択されています。
プロンプトを次のように入力します：「apidog-api-specを使用して、返金クライアントとそれを呼び出すReactフックを構築してください。仕様が要求するidempotency-keyヘッダーを含め、スキーマに正確に従ってください。」
Composer 2.5は実際のコントラクトを読み取り、クライアント、フック、型を記述し、プロジェクトのテストを実行します。
Apidogを開き、実際の返金作成リクエストを発行し、べき等動作と重複時の409エラーを確認した後、両方をテストシナリオとして保存します。

回避できたこと：べき等ヘッダーを忘れ、リリースされ、ステージング環境で顧客に二重返金してしまったクライアント。これは、根拠付けと検証によって取り除かれるバグの種類です。

よくある質問

Composer 2.5はMCPをサポートしていますか？ はい。Cursorの完全なエージェントツールセットにアクセスでき、MCPサーバーも含まれます。モデルピッカーでそれを選び、プロジェクトでサーバーを設定してください。Composer 2.5ガイドでは、モデルの選択について説明しています。

Composer 2.5でMCPを使用するにはApidogが必要ですか？ 構造化された仕様ソースが必要です。Apidog MCPサーバーは、テストとモックも同じ場所で提供するため、ここで取り上げられています。他の選択肢については、Cursor向けの最高のMCPサーバーのまとめにあります。

モデルを仕様に根拠づけることで、すべての幻覚が止まりますか？ それは、モデルが推測するのではなく実際のコントラクトを読み取るため、誤ったエンドポイントやスキーマという最大の問題カテゴリを排除します。しかし、テストに取って代わるものではありません。仕様は実行中のサービスから乖離することがあるため、依然として検証が必要です。

これは小規模プロジェクトでも価値がありますか？ モデルが実際のAPIに触れる場合、はい。設定は一度限りのコンフィグファイルです。得られるメリットは、もっともらしい推測ではなく、生成されるすべての呼び出しがあなたのコントラクトに一致することです。

結論

Composer 2.5は高速かつ安価なため、エージェントが実際のAPI作業を完全に担当できます。これは、モデルが平均的な推測ではなく、あなたの実際のコントラクトに基づいてコードを記述する場合にのみ効果を発揮します。Apidog MCPサーバーを介して仕様を接続し、Composer 2.5が真実を読み取れるようにします。その後、Apidogをダウンロードしてライブリクエストを送信し、応答を確認し、機能する呼び出しを自動テストとモックに固定します。根拠付けられた生成と検証は、エージェントのスピードを出荷可能な機能に変えるワークフローです。