Créer des APIs avec Cursor Composer 2.5

Cursor Composer 2.5 est assez rapide et abordable pour laisser un agent générer des clients API complets et des gestionnaires de routage. Le risque apparaît quand ce code touche un service réel : le modèle écrit une requête propre vers /v2/orders, alors que votre service expose /orders et attend une charge utile différente. Le code compile, mais il échoue à l’exécution.

Essayez Apidog aujourd’hui

Ce guide montre un flux de travail plus fiable : connecter Composer 2.5 à votre spécification API réelle via MCP, générer du code aligné sur le contrat, puis vérifier les appels dans Apidog avant de les partager avec l’équipe. Si vous découvrez le modèle, le guide de Cursor Composer 2.5 explique ce que c’est et comment y accéder.

Pourquoi les modèles agentiques devinent les formes d’API

Composer 2.5 est conçu pour des tâches longues et multi-étapes. Par exemple :

Ajoute un client pour notre service de facturation et intègre-le au processus de paiement.

Le modèle peut planifier, modifier plusieurs fichiers, exécuter des tests et corriger jusqu’à obtenir un résultat cohérent. C’est l’amélioration par rapport à Composer 2, et c’est utile pour du vrai travail d’implémentation.

La limite est structurelle : si le modèle n’a pas votre contrat API en contexte, il complète les blancs avec ce qui semble statistiquement probable :

• conventions REST courantes ;
• noms de champs fréquents ;
• préfixes comme /api ou /v1 ;
• schémas d’authentification génériques.

Résultat : le code semble correct, passe parfois les tests unitaires locaux, mais échoue contre le serveur réel.

Symptômes fréquents :

• endpoints presque corrects : /api/users/{id} au lieu de /users/{userId} ;
• champs inventés ou mal nommés dans les bodies ;
• authentification implémentée de façon générique au lieu du schéma réel ;
• gestion d’erreurs incomplète ou alignée sur des statuts inexistants.

Coller une spécification OpenAPI complète dans le chat peut dépanner, mais ce n’est pas robuste : le contexte devient lourd, se périme vite et peut être ignoré partiellement. La meilleure approche consiste à fournir au modèle un accès structuré à la spécification.

La solution : ancrer Composer 2.5 dans votre spécification API réelle via MCP

Le Model Context Protocol, ou MCP, permet d’exposer des outils et des données aux modèles d’IA. Cursor prend en charge les serveurs MCP, et le serveur MCP Apidog expose votre spécification API Apidog comme source structurée consultable par le modèle pendant qu’il code.

En pratique, Composer 2.5 ne devine plus les endpoints, paramètres, schémas et réponses. Il les lit depuis votre contrat API, puis génère du code aligné dessus. C’est le même principe que le "vibe coding" avec le serveur MCP Apidog, appliqué à un modèle capable de gérer une tâche complète.

Étape 1 : préparez votre spécification API dans Apidog

Avant de connecter Cursor, vérifiez que votre contrat API est exploitable par le modèle.

À faire dans Apidog :

1. Concevez ou importez votre API.
2. Vérifiez que les endpoints sont à jour.
3. Renseignez les paramètres requis.
4. Documentez les schémas de requête et de réponse.
5. Ajoutez des exemples réalistes.
6. Confirmez les codes d’erreur importants, par exemple 400, 401, 409, 422 ou 500.

Si vous avez déjà une source existante, Apidog peut importer des spécifications OpenAPI et des collections Postman. L’objectif est simple : votre spécification doit devenir la source de vérité que Composer 2.5 consultera.

Étape 2 : connectez le serveur MCP Apidog à Cursor

Cursor lit les serveurs MCP depuis un fichier de configuration dans votre projet, généralement :

.cursor/mcp.json

Une configuration typique ressemble à ceci :

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

Remplacez :

• <your-project-id> par l’ID de votre projet Apidog ;
• <your-access-token> par votre jeton d’accès Apidog.

Utilisez la commande exacte indiquée dans le guide de configuration MCP Apidog, car les valeurs dépendent de votre compte et de la version du serveur.

Après avoir enregistré le fichier :

1. redémarrez Cursor ;
2. ouvrez votre projet ;
3. vérifiez que le serveur MCP est disponible dans l’environnement agent.

Étape 3 : confirmez que Composer 2.5 voit la spécification

Avant de lui demander de modifier du code, commencez par une requête en lecture seule.

Sélectionnez composer-2.5 dans Cursor, puis demandez :

En utilisant le serveur MCP apidog-api-spec, liste les endpoints de la ressource commandes et les champs requis pour créer une commande.

Si la réponse contient vos vrais endpoints et vos vrais champs, la connexion fonctionne.

Si Composer répond avec des routes génériques comme /api/orders ou /v1/orders alors qu’elles ne correspondent pas à votre spécification :

1. vérifiez .cursor/mcp.json ;
2. confirmez le jeton Apidog ;
3. vérifiez l’ID du projet ;
4. redémarrez Cursor ;
5. relancez la question de vérification.

Ne passez pas à l’implémentation tant que cette étape n’est pas validée.

Étape 4 : générez le client en imposant la source de vérité

Une fois le serveur MCP disponible, donnez une consigne explicite à Composer 2.5.

Exemple de prompt :

En utilisant le serveur apidog-api-spec comme source de vérité, écris un client TypeScript typé pour l’API des commandes, incluant les appels createOrder et getOrder. Fais correspondre exactement les schémas de requête et de réponse. Ajoute la gestion des erreurs pour la réponse de validation 422 définie dans la spécification.

Ce type de prompt force trois choses :

• le modèle doit consulter la spécification ;
• les types doivent refléter les vrais schémas ;
• les erreurs doivent suivre le contrat documenté.

Un client généré peut par exemple prendre cette forme :

type CreateOrderRequest = {
  customerId: string;
  items: Array<{
    productId: string;
    quantity: number;
  }>;
};

type OrderResponse = {
  id: string;
  status: string;
  createdAt: string;
};

type ValidationError = {
  message: string;
  errors?: Record<string, string[]>;
};

export async function createOrder(
  payload: CreateOrderRequest,
  token: string
): Promise<OrderResponse> {
  const response = await fetch("/orders", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${token}`
    },
    body: JSON.stringify(payload)
  });

  if (response.status === 422) {
    const error = (await response.json()) as ValidationError;
    throw new Error(error.message);
  }

  if (!response.ok) {
    throw new Error(`Order creation failed: ${response.status}`);
  }

  return response.json() as Promise<OrderResponse>;
}

Le code exact doit venir de votre spécification, pas de cet exemple. L’intérêt du MCP est justement d’éviter que le modèle invente /orders, les champs ou le format d’erreur.

Vérifiez avant de faire confiance : la boucle de test Apidog

Ancrer Composer 2.5 dans une spécification réduit fortement les hallucinations, mais ne remplace pas la vérification. Une spécification peut être légèrement en retard sur le service réel, et un modèle peut mal gérer un cas limite.

Utilisez cette boucle :

1. Exécutez les appels générés comme de vraies requêtes.
   
   Prenez les endpoints et payloads générés par Composer 2.5, puis exécutez-les dans Apidog contre un environnement réel ou simulé.

2. Comparez les hypothèses du code avec les réponses réelles.
   
   Vérifiez les codes HTTP, les bodies, les headers, l’authentification et les erreurs.

3. Transformez les appels valides en tests.
   
   Enregistrez les requêtes validées comme scénarios automatisés afin que les régressions soient détectées par la CI plutôt que par un utilisateur.

4. Simulez les endpoints non livrés.
   
   Si le backend n’est pas encore disponible, utilisez le serveur de mock d’Apidog pour renvoyer des réponses réalistes. Ce workflow complète les modèles décrits dans Agents IA et tests d’API.

Le modèle produit une première implémentation alignée sur le contrat. Vous confirmez ensuite que cette implémentation fonctionne contre un serveur réel ou simulé.

Exemple de workflow de bout en bout

Prenons une fonctionnalité de remboursement dans un service de paiement.

1. Le contrat existe dans Apidog

Votre projet Apidog contient déjà :

• l’endpoint de création de remboursement ;
• le schéma de requête ;
• le schéma de réponse ;
• l’en-tête idempotency-key requis ;
• les erreurs possibles, par exemple 409 en cas de doublon.

2. Cursor est connecté au serveur MCP Apidog

Votre projet contient .cursor/mcp.json, Cursor a été redémarré, et Composer 2.5 peut lire la spécification.

3. Vous donnez une tâche précise

Prompt :

En utilisant apidog-api-spec, construis le client de remboursement et un hook React qui l’appelle. Suis exactement le schéma, y compris l’en-tête idempotency-key requis par la spécification.

4. Composer 2.5 génère l’implémentation

Il peut créer ou modifier :

• un client API ;
• des types TypeScript ;
• un hook React ;
• des tests existants ou nouveaux.

Exemple de structure attendue :

src/
  api/
    refundsClient.ts
  hooks/
    useCreateRefund.ts
  types/
    refunds.ts

5. Vous vérifiez dans Apidog

Dans Apidog :

1. envoyez une requête de création de remboursement ;
2. confirmez que l’en-tête idempotency-key est requis ;
3. renvoyez la même requête pour vérifier le comportement en doublon ;
4. confirmez le 409 si la spécification le prévoit ;
5. enregistrez les deux requêtes comme scénarios de test.

Ce que vous évitez : un client généré qui oublie l’en-tête d’idempotence, passe en revue de code, puis déclenche deux remboursements en staging.

Foire aux questions

Composer 2.5 prend-il en charge MCP ?

Oui. Composer 2.5 a accès aux outils agent de Cursor, y compris les serveurs MCP. Sélectionnez-le dans le sélecteur de modèle et configurez le serveur dans votre projet. Le guide de Composer 2.5 couvre la sélection du modèle.

Ai-je besoin d’Apidog pour utiliser MCP avec Composer 2.5 ?

Vous avez besoin d’une source de spécification structurée. Le serveur MCP Apidog est l’option utilisée ici, car il combine spécification, test et mock dans le même outil. D’autres options sont présentées dans le récapitulatif des meilleurs serveurs MCP pour Cursor.

L’ancrage dans une spécification supprime-t-il toutes les hallucinations ?

Non. Il élimine surtout les erreurs de endpoints, paramètres et schémas, car le modèle lit le contrat réel au lieu de deviner. Mais vous devez toujours tester : une spécification peut diverger du service en cours d’exécution.

Est-ce utile pour un petit projet ?

Oui, dès qu’un modèle génère du code qui appelle une API réelle. La configuration tient dans un fichier, et le bénéfice est immédiat : chaque appel généré est basé sur votre contrat plutôt que sur une supposition plausible.

L’essentiel

Composer 2.5 peut accélérer le développement API, mais seulement s’il code contre votre contrat réel. Connectez votre spécification via le serveur MCP Apidog, demandez explicitement au modèle de l’utiliser comme source de vérité, puis vérifiez les appels dans Apidog.

Pour fermer la boucle, téléchargez Apidog, envoyez les requêtes générées, confirmez les réponses et transformez les appels valides en tests automatisés ou en mocks. La combinaison gagnante est simple : génération ancrée dans la spécification, puis vérification contre le comportement réel.