Cursor Composer 2.5 es lo suficientemente rápido y económico como para delegarle a un agente la escritura de clientes API completos y manejadores de rutas. El problema aparece cuando ese código toca un servicio real: el modelo puede generar una solicitud limpia a /v2/orders, aunque tu backend exponga /orders y espere otro payload. El código compila, pero falla en ejecución.
En esta guía verás un flujo de trabajo práctico para evitarlo: conectar Composer 2.5 con tu especificación API real mediante MCP, generar código contra ese contrato y validar el resultado en Apidog antes de enviarlo a revisión. Si aún no conoces el modelo, la guía de Cursor Composer 2.5 explica qué es y cómo acceder a él.
Por qué los modelos agentivos adivinan las formas de la API
Composer 2.5 está diseñado para tareas largas y de varios pasos. Puedes pedirle algo como:
Agrega un cliente para nuestro servicio de facturación y conéctalo al flujo de pago.
El modelo planificará, editará varios archivos y ejecutará pruebas hasta que pasen. Esa es una mejora importante frente a Composer 2.
El problema no es un bug puntual, sino una limitación de contexto. Si el modelo no tiene tu contrato API real, rellena los huecos con patrones probables:
- Convenciones REST comunes.
- Nombres de campos frecuentes.
- Prefijos como
/apio/v2. - Esquemas de autenticación genéricos.
Eso produce código que parece correcto, pero no necesariamente coincide con tu backend.
Síntomas típicos:
- Endpoints que casi coinciden:
/api/users/{id}en lugar de/users/{userId}. - Campos inventados o mal nombrados en el body.
- Headers de autenticación incorrectos.
- Tipos TypeScript que no representan la respuesta real.
- Manejo de errores que no contempla los códigos definidos por tu API.
Puedes intentar resolverlo pegando tu OpenAPI en el prompt, pero eso consume contexto y se rompe fácilmente. La solución más estable es darle al modelo acceso estructurado a la especificación.
La solución: fundamentar Composer 2.5 en tu especificación API real mediante MCP
El Protocolo de Contexto de Modelo, o MCP, permite exponer herramientas y datos estructurados a modelos de IA. Cursor admite servidores MCP, y el servidor MCP de Apidog permite que Composer consulte tu especificación API desde Apidog mientras escribe código.
En la práctica, el flujo cambia así:
Sin MCP:
Prompt -> Composer -> código basado en suposiciones
Con MCP:
Prompt -> Composer -> consulta la especificación real -> código alineado al contrato
Composer puede leer endpoints, parámetros, esquemas de request, esquemas de response y errores definidos. Esta es la misma idea detrás de la programación "vibe" con el servidor MCP de Apidog, aplicada a tareas más completas con Composer 2.5.
Paso 1: Prepara tu especificación API en Apidog
Antes de generar código, asegúrate de que tu contrato API esté actualizado.
En Apidog puedes:
- Diseñar endpoints nuevos.
- Importar una especificación OpenAPI.
- Importar colecciones de Postman.
- Definir ejemplos de request y response.
- Documentar códigos de error.
- Mantener parámetros, headers y esquemas sincronizados.
La especificación será la fuente de verdad del agente. Si está incompleta o desactualizada, Composer heredará esos problemas.
Checklist mínimo antes de continuar:
- Los endpoints tienen paths definitivos.
- Los métodos HTTP son correctos.
- Los campos requeridos están marcados.
- Los headers obligatorios están definidos.
- Los códigos de error esperados están documentados.
- Los ejemplos reflejan datos realistas.
Paso 2: Conecta el servidor MCP de Apidog a Cursor
Cursor lee servidores MCP desde un archivo de configuración dentro del proyecto, comúnmente:
.cursor/mcp.json
Una configuración típica para exponer tu especificación de Apidog se ve así:
{
"mcpServers": {
"apidog-api-spec": {
"command": "npx",
"args": ["-y", "apidog-mcp-server@latest", "--project=<tu-id-de-proyecto>"],
"env": {
"APIDOG_ACCESS_TOKEN": "<tu-token-de-acceso>"
}
}
}
}
Usa el comando exacto, el ID de proyecto y el token indicados en la guía de configuración de Apidog MCP, porque esos valores dependen de tu cuenta y de la versión del servidor.
Después de guardar el archivo:
- Reinicia Cursor.
- Abre el proyecto.
- Comprueba que el servidor MCP aparece disponible.
- Selecciona
composer-2.5en el selector de modelos.
Paso 3: Confirma que Composer 2.5 puede leer la especificación
Antes de pedirle que genere código, haz una consulta de solo lectura.
Ejemplo de prompt:
Usando el servidor MCP apidog-api-spec, enumera los endpoints del recurso de pedidos y los campos requeridos para crear un pedido.
La respuesta debe incluir datos reales de tu especificación.
Si Composer responde con información genérica, revisa:
- Que
.cursor/mcp.jsonesté en la ruta correcta. - Que el nombre del servidor coincida con el prompt.
- Que
APIDOG_ACCESS_TOKENsea válido. - Que el ID del proyecto sea correcto.
- Que hayas reiniciado Cursor.
Paso 4: Genera el cliente contra el contrato real
Cuando la conexión funcione, pide la tarea real y nombra explícitamente la fuente MCP.
Ejemplo:
Usando el servidor apidog-api-spec como fuente de verdad, escribe un cliente TypeScript tipado para la API de pedidos.
Incluye:
- createOrder
- getOrder
- tipos para request y response
- manejo de errores para la respuesta 422 definida en la especificación
No inventes campos. Usa exactamente los esquemas de la especificación.
Un resultado esperado podría tener esta estructura:
src/
api/
orders/
client.ts
types.ts
errors.ts
Ejemplo del tipo de código que quieres obtener:
// src/api/orders/client.ts
import type {
CreateOrderRequest,
CreateOrderResponse,
GetOrderResponse
} from "./types";
export class OrdersApiClient {
constructor(
private readonly baseUrl: string,
private readonly token: string
) {}
async createOrder(payload: CreateOrderRequest): Promise<CreateOrderResponse> {
const response = await fetch(`${this.baseUrl}/orders`, {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${this.token}`
},
body: JSON.stringify(payload)
});
if (response.status === 422) {
const errorBody = await response.json();
throw new Error(`Validation error: ${JSON.stringify(errorBody)}`);
}
if (!response.ok) {
throw new Error(`Create order failed with status ${response.status}`);
}
return response.json();
}
async getOrder(orderId: string): Promise<GetOrderResponse> {
const response = await fetch(`${this.baseUrl}/orders/${orderId}`, {
method: "GET",
headers: {
Authorization: `Bearer ${this.token}`
}
});
if (!response.ok) {
throw new Error(`Get order failed with status ${response.status}`);
}
return response.json();
}
}
La clave no es que el código tenga exactamente esta forma, sino que Composer lo derive del contrato real y no de patrones genéricos.
Paso 5: Valida el código generado en Apidog
Fundamentar el modelo reduce alucinaciones, pero no reemplaza la verificación. Una especificación puede estar desactualizada respecto al servicio en ejecución, o el modelo puede interpretar mal un caso borde.
Cierra el ciclo con Apidog:
- Copia las llamadas generadas por Composer.
- Ejecútalas como requests reales en Apidog.
- Valida:
- status codes;
- body de respuesta;
- headers requeridos;
- autenticación;
- manejo de errores;
- payloads inválidos.
- Guarda las requests correctas como escenarios de prueba.
- Usa mocks cuando el backend aún no esté implementado.
Este flujo encaja bien con los patrones de agentes de IA y pruebas de API.
Ejemplo de flujo completo: agregar reembolsos
Supongamos que necesitas implementar una función de reembolsos en un servicio de pagos.
1. Define o importa la API
En Apidog ya tienes un recurso de reembolsos con:
POST /refundsGET /refunds/{refundId}- header
idempotency-key - respuesta
201para creación correcta - respuesta
409para duplicados - respuesta
422para errores de validación
2. Conecta Apidog MCP a Cursor
Tu proyecto incluye:
{
"mcpServers": {
"apidog-api-spec": {
"command": "npx",
"args": ["-y", "apidog-mcp-server@latest", "--project=<tu-id-de-proyecto>"],
"env": {
"APIDOG_ACCESS_TOKEN": "<tu-token-de-acceso>"
}
}
}
}
3. Pide a Composer que genere el cliente y el hook
Prompt recomendado:
Usando apidog-api-spec como fuente de verdad, construye el cliente de reembolsos y un hook de React que lo consuma.
Requisitos:
- Sigue exactamente el esquema de la especificación.
- Incluye el header idempotency-key requerido.
- Maneja los errores 409 y 422 según la especificación.
- No inventes campos ni endpoints.
- Ejecuta las pruebas del proyecto al terminar.
4. Revisa los archivos modificados
Antes de aceptar el cambio, verifica:
- Que el path sea el correcto.
- Que el header
idempotency-keyesté presente. - Que los tipos coincidan con la especificación.
- Que los errores
409y422tengan manejo explícito. - Que no existan campos inventados.
- Que las pruebas pasen.
5. Prueba el comportamiento en Apidog
En Apidog:
- Ejecuta una creación de reembolso válida.
- Repite la llamada con la misma
idempotency-key. - Confirma que el backend responde con el comportamiento esperado.
- Prueba un payload inválido.
- Guarda los casos exitosos y de error como pruebas automatizadas.
Lo que evitas: un cliente que olvida el header de idempotencia y permite duplicar un reembolso en pruebas o producción.
Prompts útiles para Composer 2.5 + Apidog MCP
Generar cliente API
Usando apidog-api-spec como fuente de verdad, genera un cliente TypeScript para el recurso <recurso>.
Incluye:
- funciones para cada endpoint documentado;
- tipos de request y response;
- manejo de errores documentados;
- tests unitarios básicos.
No uses endpoints ni campos que no estén en la especificación.
Revisar código existente contra la especificación
Usando apidog-api-spec, revisa el cliente API existente en src/api/<recurso>.
Busca:
- endpoints incorrectos;
- parámetros faltantes;
- headers faltantes;
- tipos que no coincidan con la especificación;
- errores documentados que no estén manejados.
Devuelve una lista de cambios y luego aplícalos.
Crear pruebas desde el contrato
Usando apidog-api-spec, crea pruebas para los casos principales del recurso <recurso>.
Incluye:
- caso exitoso;
- payload inválido;
- autenticación faltante;
- error de validación documentado.
Alinea los fixtures con los ejemplos de la especificación.
Preguntas frecuentes
¿Composer 2.5 es compatible con MCP?
Sí. Composer 2.5 puede usar las herramientas de agente de Cursor, incluidos servidores MCP. Selecciónalo en el selector de modelos y configura el servidor en tu proyecto. La guía de Composer 2.5 cubre la selección del modelo.
¿Necesito Apidog para usar MCP con Composer 2.5?
Necesitas una fuente de especificación estructurada. El servidor MCP de Apidog es el enfoque usado aquí porque combina especificación, pruebas y mocking en el mismo flujo. También existen otras opciones en la recopilación de los mejores servidores MCP para Cursor.
¿Fundamentar el modelo en una especificación elimina todas las alucinaciones?
No todas, pero elimina una de las categorías más costosas: endpoints, parámetros y esquemas inventados. Aun así, debes probar contra un servidor real o mockeado, porque una especificación puede desviarse del comportamiento en ejecución.
¿Vale la pena para un proyecto pequeño?
Sí, si el modelo toca una API real. La configuración es principalmente un archivo MCP, y el beneficio es que cada llamada generada parte del contrato en lugar de una suposición plausible.
Conclusión
Composer 2.5 puede acelerar mucho el desarrollo de código relacionado con APIs, pero solo es seguro si trabaja contra tu contrato real. Conecta tu especificación mediante el servidor MCP de Apidog, pide a Composer que use esa fuente de verdad y valida las llamadas en Apidog antes de fusionar cambios.
El flujo recomendado es simple:
Especificación real -> Composer 2.5 con MCP -> código generado -> pruebas en Apidog -> CI/mocks
La combinación de generación fundamentada y verificación convierte la velocidad del agente en funcionalidades listas para implementar.
Top comments (0)