Como Criar APIs com Cursor Composer 2.5

O Cursor Composer 2.5 é rápido e barato o suficiente para gerar clientes de API, hooks e manipuladores de rotas. O problema aparece quando o código toca um serviço real: o modelo cria uma requisição limpa para /v2/orders, mas sua API expõe /orders e espera outro payload. O código compila, passa no lint e falha só quando você testa contra o servidor.

Experimente o Apidog hoje

Este guia mostra um fluxo de trabalho mais seguro: conectar o Composer 2.5 à sua especificação real via MCP, gerar código contra esse contrato e validar as chamadas no Apidog antes de enviar para revisão. Se você ainda não conhece o modelo, veja o guia do Cursor Composer 2.5.

Por que modelos de agente adivinham APIs

O Composer 2.5 foi feito para tarefas longas e com múltiplos passos. Você pode pedir algo como:

“Adicione um cliente para nosso serviço de faturamento e conecte-o ao fluxo de checkout.”

Ele planeja, edita vários arquivos e executa testes. Essa é a evolução em relação ao Composer 2.

A limitação é estrutural: se o contrato de API não está no contexto, o modelo preenche lacunas com padrões prováveis:

• endpoints parecidos, mas errados: /api/users/{id} em vez de /users/{userId};
• campos inventados ou incorretos no body;
• autenticação genérica em vez do esquema real;
• códigos de erro e formatos de resposta assumidos.

Colar um arquivo OpenAPI inteiro no chat até funciona em casos pequenos, mas é frágil e consome contexto. A solução mais estável é expor a especificação como uma fonte estruturada via MCP.

Solução: conectar o Composer 2.5 à especificação real via MCP

O Model Context Protocol (MCP) permite fornecer ferramentas e dados estruturados para modelos de IA. O Cursor suporta servidores MCP, e o servidor MCP do Apidog expõe sua especificação de API ao modelo.

Na prática, o Composer 2.5 deixa de inferir endpoints e passa a consultar:

• paths reais;
• métodos HTTP;
• parâmetros;
• schemas de request e response;
• exemplos;
• códigos de erro;
• requisitos de autenticação.

É a mesma ideia por trás do vibe coding com o servidor MCP do Apidog, aplicada a um modelo capaz de executar a tarefa de ponta a ponta.

Passo 1: prepare a especificação no Apidog

Antes de pedir código ao Composer, garanta que o contrato está atualizado no Apidog.

Checklist mínimo:

• endpoints com paths e métodos corretos;
• schemas de request e response;
• campos obrigatórios marcados corretamente;
• exemplos válidos;
• autenticação documentada;
• respostas de erro definidas.

Se você já tem uma especificação existente, importe OpenAPI ou coleções Postman no Apidog. Essa especificação será a fonte da verdade usada pelo modelo.

Passo 2: conecte o servidor MCP do Apidog ao Cursor

O Cursor lê servidores MCP a partir de um arquivo de configuração no projeto, geralmente em:

.cursor/mcp.json

Uma configuração típica fica assim:

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

Substitua:

• <your-project-id> pelo ID do projeto no Apidog;
• <your-access-token> pelo token da sua conta;
• o comando/argumentos conforme a versão indicada no passo a passo de configuração do Apidog MCP.

Depois de salvar o arquivo, reinicie o Cursor para que ele detecte o servidor MCP.

Passo 3: confirme que o Composer 2.5 consegue ler a especificação

Antes de pedir alterações no código, faça uma consulta somente leitura.

No Cursor, selecione composer-2.5 e envie:

“Usando o servidor MCP apidog-api-spec, liste os endpoints do recurso de pedidos e os campos obrigatórios para criar um pedido.”

Resultado esperado:

• o modelo retorna endpoints reais do seu projeto;
• os campos obrigatórios batem com a especificação;
• os códigos de resposta são os mesmos documentados.

Se ele responder de forma genérica, como se estivesse inventando uma API REST comum, verifique:

• se .cursor/mcp.json está no local correto;
• se o nome do servidor bate com o prompt;
• se o token está válido;
• se o Cursor foi reiniciado;
• se o projeto do Apidog contém a especificação correta.

Passo 4: gere código ancorado no contrato

Agora peça a implementação real e cite explicitamente a fonte MCP:

“Usando apidog-api-spec como fonte da verdade, escreva um cliente TypeScript tipado para a API de pedidos, incluindo as chamadas create-order e get-order. Corresponda exatamente aos schemas de request e response. Adicione tratamento de erros para a resposta de validação 422 definida na especificação.”

Um bom prompt deve deixar claro:

• qual servidor MCP usar;
• qual recurso implementar;
• quais operações incluir;
• que os tipos devem seguir a especificação;
• quais erros precisam ser tratados;
• onde o código deve ser criado ou alterado.

Exemplo de estrutura que você pode pedir ao Composer:

src/api/orders/client.ts
src/api/orders/types.ts
src/api/orders/errors.ts

Também vale pedir para o modelo explicar quais endpoints da especificação ele usou antes de editar arquivos:

“Antes de alterar o código, liste os endpoints, métodos, schemas e códigos de erro da especificação que você vai usar.”

Isso ajuda a detectar rapidamente se ele está olhando para o contrato certo.

Passo 5: valide no Apidog antes de confiar

Conectar a especificação reduz alucinações, mas não remove a necessidade de teste. A especificação pode estar desatualizada, o ambiente pode ter diferenças e o modelo ainda pode interpretar mal um caso limite.

Feche o loop com o Apidog:

1. Execute as chamadas geradas como requisições reais
   
   Pegue os endpoints que o Composer usou e envie no Apidog, contra um ambiente real ou mockado.

2. Compare o comportamento com o código gerado
   
   Verifique status codes, bodies, headers, autenticação e mensagens de erro.

3. Salve os cenários que funcionam como testes
   
   Transforme as requisições validadas em testes automatizados para detectar regressões.

4. Use mocks quando o backend ainda não existir
   
   Se o Composer gerou um cliente para um endpoint ainda não implementado, use o servidor de mock do Apidog para continuar o desenvolvimento do frontend. Esse fluxo se encaixa bem com práticas de agentes de IA e teste de API.

O princípio é simples: o agente gera o primeiro rascunho contra o contrato, e você valida o comportamento contra um servidor real ou mock controlado.

Exemplo de fluxo ponta a ponta

Imagine que você está adicionando reembolsos a um serviço de pagamentos.

1. Os endpoints e schemas de reembolso já existem no projeto Apidog.
2. O servidor MCP do Apidog está conectado ao Cursor.
3. O modelo selecionado é composer-2.5.
4. Você envia o prompt:

Usando apidog-api-spec como fonte da verdade, construa o cliente de reembolso e um hook React que o chame.

Siga exatamente o schema da especificação, incluindo o header idempotency-key exigido pela API.

Antes de editar arquivos, liste os endpoints e schemas que serão usados.

1. O Composer lê o contrato real e gera:

   • tipos TypeScript;
   • cliente HTTP;
   • hook React;
   • tratamento de erro;
   • testes do projeto, se aplicável.

2. Você abre o Apidog e executa:

   • criação de reembolso;
   • tentativa duplicada com a mesma idempotency-key;
   • validação do erro esperado, como 409, se definido na especificação.

3. Você salva os cenários como testes.

O bug evitado aqui é comum: gerar um cliente que esquece o header de idempotência, passa em revisão e causa comportamento incorreto em staging.

Perguntas frequentes

O Composer 2.5 suporta MCP?

Sim. Ele usa o conjunto de ferramentas de agente do Cursor, incluindo servidores MCP. Selecione composer-2.5 no seletor de modelo e configure o servidor no projeto. O guia do Composer 2.5 mostra como acessar o modelo.

Preciso do Apidog para usar MCP com o Composer 2.5?

Você precisa de uma fonte estruturada para a especificação. Este guia usa o servidor MCP do Apidog porque ele combina especificação, testes e mocks no mesmo fluxo. Também existem outras opções no resumo de melhores servidores MCP para Cursor.

Conectar a especificação elimina todas as alucinações?

Não. Isso remove uma das maiores fontes de erro: endpoints, schemas e parâmetros inventados. Mas você ainda precisa testar, porque a especificação pode divergir do serviço em execução ou o modelo pode interpretar um caso limite de forma incorreta.

Vale a pena em projetos pequenos?

Sim, se o modelo vai tocar qualquer API real. A configuração é basicamente um arquivo MCP, e o ganho é evitar que cada chamada gerada seja uma suposição plausível em vez de código baseado no contrato.

Conclusão

O Composer 2.5 pode acelerar trabalho real com APIs, mas só é confiável quando codifica contra o contrato correto. Conecte sua especificação ao Cursor via servidor MCP do Apidog, peça explicitamente para o modelo usar essa fonte da verdade e valide as chamadas no Apidog.

Depois, baixe o Apidog para executar requisições reais, confirmar respostas e transformar chamadas válidas em testes automatizados e mocks. Geração fundamentada mais verificação é o fluxo que transforma velocidade de agente em entrega confiável.