Akira

Posted on May 19 • Originally published at apidog.com

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

Cursor Composer 2.5は高速かつ低コストなので、APIクライアントやルートハンドラの生成をエージェントに任せやすくなりました。ただし、モデルが実際のAPIコントラクトを知らないままコードを書くと、/v2/ordersのような存在しないエンドポイントや、実サービスとは異なるペイロードを生成することがあります。コードはコンパイルされても、実行時に失敗します。

今すぐApidogを試す

この記事では、Cursor Composer 2.5をMCP経由で実際のAPI仕様に接続し、仕様に基づいてコードを生成し、チームに渡す前にApidogで検証するワークフローを説明します。Composer 2.5自体の概要や利用方法は、Cursor Composer 2.5ガイドを参照してください。

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

Composer 2.5は、複数ファイルの編集、テスト実行、修正を含む長いエージェントタスクに向いています。

たとえば、次のような依頼ができます。

請求サービス用のクライアントを追加し、それを決済フローに組み込んでください。

Composer 2.5は計画を立て、必要なファイルを編集し、テストが通るまで作業します。これはComposer 2からの大きな改善点です。

ただし、モデルがAPIコントラクトをコンテキストに持っていない場合、空白を「もっともらしい形」で補完します。

よくある失敗は次の3つです。

エンドポイントが微妙に違う
- 例: モデルは/api/users/{id}を書くが、実際は/users/{userId}
リクエストボディに存在しないフィールドを追加する
認証方式をサービス固有の方式ではなく、一般的なBearerトークンなどとして扱う

OpenAPIファイルをそのままチャットに貼ることもできますが、長くなりやすく、コンテキストも消費します。より安定した方法は、モデルにAPI仕様への構造化されたアクセスを与えることです。

解決策: MCPを介してComposer 2.5を実際のAPI仕様に接続する

Model Context Protocol、つまりMCPは、AIモデルにツールやデータを提供するためのオープン標準です。

CursorはMCPサーバーをサポートしています。Apidog MCPサーバーを使うと、Apidog内のAPI仕様を、Composer 2.5がコーディング中に参照できる構造化データとして公開できます。

これにより、Composer 2.5は次の情報を推測ではなく仕様から取得できます。

実際のエンドポイント
パスパラメーター
クエリパラメーター
リクエストスキーマ
レスポンススキーマ
エラーレスポンス
認証要件

これは、Apidog MCPサーバーでのバイブコーディングと同じ考え方を、より長い実装タスクに適用する方法です。

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

まず、モデルが参照する「真実の源」を用意します。

ApidogでAPIを設計するか、既存の仕様をインポートしてください。ApidogはOpenAPIやPostmanコレクションのインポートに対応しています。

準備時に確認するポイントは次のとおりです。

エンドポイントが実サービスと一致している
リクエストボディのスキーマが最新である
レスポンス例が実際の形式に近い
エラー時のステータスコードとレスポンスが定義されている
認証方式が明記されている

Composer 2.5はこの仕様をもとにコードを書くため、仕様が古いと生成コードも古くなります。最初に仕様を整えることが重要です。

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

Cursorは、プロジェクト内の設定ファイルからMCPサーバーを読み取ります。通常は.cursor/mcp.jsonを使用します。

典型的な設定例は次のとおりです。

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

<your-project-id>と<your-access-token>は、自分のApidogプロジェクトに合わせて置き換えてください。

正確なコマンド、プロジェクトID、トークンの取得方法は、Apidog MCPセットアップウォークスルーを確認してください。

設定後は、Cursorを再起動します。再起動しないと、新しいMCPサーバーが認識されないことがあります。

ステップ3: Composer 2.5が仕様を読めるか確認する

いきなり実装を依頼する前に、読み取り専用の質問で接続を確認します。

Cursorでエージェントセッションを開き、モデルピッカーでcomposer-2.5を選択します。

次のように質問します。

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

期待する結果は、Apidogに定義されている実際のエンドポイントとフィールドが返ることです。

もし一般的なREST APIの例のような回答が返る場合、Composer 2.5は仕様を読めていません。その場合は次を確認します。

.cursor/mcp.jsonの場所が正しいか
MCPサーバー名がプロンプト内の名前と一致しているか
ApidogのプロジェクトIDが正しいか
アクセストークンが有効か
Cursorを再起動したか

ステップ4: コントラクトに基づいてコードを生成させる

接続確認ができたら、実装タスクを依頼します。

重要なのは、仕様ソースを明示することです。

例:

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

より実装寄りにするなら、次のように条件を追加できます。

apidog-api-specを参照して、注文APIクライアントを実装してください。

要件:
- TypeScriptで実装する
- createOrderとgetOrderを提供する
- リクエスト型とレスポンス型を仕様に合わせる
- 422レスポンスをValidationErrorとして扱う
- 既存のHTTPクライアントラッパーを再利用する
- 生成後に関連テストを実行する

Composer 2.5は複数ファイルにまたがる作業を維持できるため、次のような構成の実装にも向いています。

src/
  api/
    orders.ts
  types/
    orders.ts
  hooks/
    useOrder.ts
  tests/
    orders.test.ts

プロンプト内でMCPソースを指定しておくことで、モデルが一般知識に戻ってエンドポイントやフィールドを推測するリスクを下げられます。

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

MCPでモデルを仕様に根拠づけると、誤ったエンドポイントやスキーマの生成は大きく減ります。ただし、検証は不要にはなりません。

理由は2つあります。

仕様が実サービスより遅れている可能性がある
モデルがエッジケースを誤解する可能性がある

そのため、生成後はApidogで実際に検証します。

1. 生成された呼び出しを実リクエストとして送信する

Composer 2.5が生成したエンドポイント、ヘッダー、ボディをApidogで実行します。

確認する項目は次のとおりです。

ステータスコードが想定通りか
レスポンスボディの形が型定義と一致しているか
認証ヘッダーが正しく送信されているか
エラー時のレスポンスがコードの分岐と一致しているか

2. 動作する呼び出しをテストに変換する

検証済みのリクエストは、Apidog上で自動テストシナリオとして保存します。

これにより、次回以降の変更でAPIコントラクトが壊れた場合、ユーザーではなくCIやテストで検出できます。

3. 未実装のAPIはモック化する

バックエンドがまだ実装していないエンドポイントでも、仕様がApidogにあるならモックを使えます。

たとえば、Composer 2.5にフロントエンドクライアントを生成させ、Apidogのモックサーバーに対して動作確認できます。

この流れは、AIエージェントとAPIテストのパターンとも相性が良いです。

基本方針はシンプルです。

モデルはコントラクトに基づいて初稿を書く。人間とテストは、それが実サービスに対して正しく動くことを確認する。

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

決済サービスに返金機能を追加する例で考えます。

前提:

返金エンドポイントとスキーマはApidogプロジェクトに定義済み
Apidog MCPサーバーはCursorに接続済み
CursorではComposer 2.5を選択済み

Composer 2.5には次のように依頼します。

apidog-api-specを使用して、返金クライアントとそれを呼び出すReactフックを構築してください。

要件:
- 仕様が要求するidempotency-keyヘッダーを含める
- リクエストボディとレスポンス型は仕様に正確に合わせる
- 重複リクエスト時の409エラーを処理する
- 既存のAPIクライアント構成に合わせる
- 実装後に関連テストを実行する

期待する作業の流れは次のとおりです。

Composer 2.5がApidog MCPから返金APIの仕様を読む
クライアント関数、型、Reactフックを生成する
既存のプロジェクト構成に合わせてファイルを配置する
テストを実行し、失敗があれば修正する
Apidogで実際の返金作成リクエストを送信する
idempotency-keyの動作と、重複時の409エラーを確認する
正常系と重複エラー系をテストシナリオとして保存する

このワークフローで避けられる典型的なバグは、べき等ヘッダーの付け忘れです。返金処理では、この種のミスが二重返金のような重大な問題につながります。

よくある質問

Composer 2.5はMCPをサポートしていますか？

はい。Cursorのエージェントツールセットにアクセスでき、MCPサーバーも利用できます。

モデルピッカーでComposer 2.5を選び、プロジェクトでMCPサーバーを設定してください。モデル選択については、Composer 2.5ガイドで説明されています。

Composer 2.5でMCPを使うにはApidogが必要ですか？

必要なのは、構造化されたAPI仕様ソースです。

この記事では、仕様、テスト、モックを同じ場所で扱えるため、Apidog MCPサーバーを使っています。

他の選択肢は、Cursor向けの最高のMCPサーバーのまとめも参考になります。

モデルを仕様に根拠づけると、すべての幻覚が止まりますか？

いいえ。

ただし、モデルが推測ではなく実際のコントラクトを読むため、誤ったエンドポイントやスキーマを生成するリスクは大きく下がります。

それでもテストは必要です。仕様が実行中のサービスとずれている場合や、モデルがエラー処理を誤解する場合があるためです。

小規模プロジェクトでも価値がありますか？

はい。モデルが実際のAPIに触れるなら価値があります。

設定は基本的に一度だけです。その後は、生成されるAPI呼び出しが「一般的にありそうな形」ではなく、自分のプロジェクトのコントラクトに基づくようになります。

結論

Composer 2.5は、APIクライアントや関連実装をエージェントに任せられるほど高速で低コストです。ただし、実運用に近いコードを生成するには、モデルを実際のAPIコントラクトに接続する必要があります。

Apidog MCPサーバーを使って仕様をCursorに公開し、Composer 2.5が正しいエンドポイント、スキーマ、レスポンスを読めるようにします。そのうえで、Apidogをダウンロードし、ライブリクエスト、テスト、モックで検証します。

仕様に基づく生成と実リクエストでの検証を組み合わせることで、エージェントの速度をそのまま出荷可能な実装につなげられます。

DEV Community