Cursor Agent Mode: workflows avançados com MCPs

O Agent Mode representa uma mudança fundamental de como você interage com o Cursor. Em vez de um assistente que responde perguntas, você passa a ter um executor autônomo que planeja, age e corrige erros sozinho — com acesso a todas as suas ferramentas MCP.

Chat Mode vs Agent Mode

Exemplo concreto de diferença: migrar um projeto Next.js para TypeScript.

• Chat Mode: 10+ trocas de mensagens, 45-60 minutos, você aplica cada mudança manualmente
• Agent Mode: uma instrução, 5-10 minutos, o agente edita arquivos, executa tsc --noEmit, corrige os erros e reporta o resultado

O que o Agent faz autonomamente

O Cursor Agent tem acesso a um conjunto de ações que executa sem você precisar instruir cada passo:

Leitura e navegação:

• Lê e analisa a estrutura do projeto
• Navega entre arquivos para entender contexto
• Busca por padrões e dependências

Escrita e modificação:

• Edita múltiplos arquivos sistematicamente
• Cria novos arquivos seguindo convenções do projeto
• Refatora código mantendo consistência

Execução:

• Roda comandos no terminal (npm run build, pytest, etc.)
• Verifica saída de erros e auto-corrige
• Executa scripts e migrations

Ferramentas MCP:

• Seleciona e chama ferramentas MCP conforme necessário
• Encadeia múltiplas chamadas para completar tarefas compostas

Como MCPs se integram ao Agent

No Agent Mode, as ferramentas MCP ficam disponíveis automaticamente — você não precisa invocar cada ferramenta explicitamente. O agente decide qual ferramenta usar baseado na tarefa.

Exemplo de tarefa composta

Você instrui:

"Encontre o bug reportado na issue #42 do GitHub, corrija no código e feche a issue com um comentário resumindo a mudança"

O agente executa automaticamente:

1. GitHub MCP → busca issue #42 e lê a descrição
2. Lê os arquivos relevantes do projeto
3. Identifica e corrige o bug
4. Executa os testes para confirmar a correção
5. GitHub MCP → adiciona comentário na issue
6. GitHub MCP → fecha a issue
7. Reporta o que foi feito

Sem MCP, cada etapa exigiria intervenção manual sua.

Auto-run vs aprovação manual

Por padrão, o Cursor pede sua aprovação antes de executar cada ferramenta MCP. Você vê o que o agente vai fazer antes que aconteça.

Modo com aprovação (padrão)

Agente: Vou chamar `criar_issue` com título "Bug: crash no login"
        [Aprovar] [Negar] [Editar]

Recomendado para:

• Ferramentas que modificam dados em produção
• Operações irreversíveis (delete, drop, close)
• Quando você está aprendendo o comportamento do agente

Auto-run (modo autônomo)

Ative em Settings → Features → MCP → Auto-run tools.

Com auto-run, o agente executa ferramentas sem parar para pedir confirmação — similar a como já executa comandos de terminal internamente. Útil para:

• Ferramentas de leitura (buscar issues, consultar banco em modo read-only)
• Ambientes de desenvolvimento onde erros são reversíveis
• Tarefas longas com muitas chamadas de API

Atenção: com auto-run ativo, o agente pode criar issues, commits ou registros em bancos sem confirmação. Revise o escopo das ferramentas antes de ativar.

Estratégia de planejamento: Ask antes de Agent

Para tarefas complexas, uma estratégia eficaz é usar o Ask Mode para planejar e depois o Agent Mode para executar:

1. Ask Mode com modelo de raciocínio (o4-mini, Gemini 2.5 Pro):
   "Crie um plano detalhado passo a passo para adicionar
    autenticação JWT a este projeto Next.js"

2. Revise o plano gerado
   Ajuste o que não fizer sentido para seu contexto

3. Agent Mode:
   "Implemente exatamente este plano:
    [cole o plano aqui]
    Não pule etapas. Teste cada fase antes de avançar."

Isso reduz drasticamente alucinações e mudanças não solicitadas, porque o agente tem um roteiro claro para seguir.

Controle de contexto para projetos grandes

Em codebases grandes, o agente pode se perder ou usar tokens desnecessariamente. Use referências explícitas de contexto:

Escopo por arquivo

@src/components/Editor.tsx Refatore esta função para usar hooks

Escopo por pasta

@src/api/ Adicione rate limiting em todas as rotas de escrita

Escopo por git

@git:staged Revise as mudanças staged e adicione testes unitários

Escopo por símbolo

@handleSubmit Extraia a lógica de validação desta função para um hook separado

O Symbol Index do Cursor (ative em Settings → Features) reduz o uso de tokens em 30-50% e dobra a velocidade em projetos grandes ao indexar símbolos sem precisar ler arquivos inteiros.

Workflow com Cursor Rules

Crie regras que o agente segue automaticamente em todo o projeto.

Arquivo: .cursor/rules/projeto.mdc

---
globs: ["**/*.ts", "**/*.tsx"]
---

## Regras do Projeto

### Stack
- Next.js 16 com App Router
- TypeScript strict
- Tailwind CSS v4
- Drizzle ORM + PostgreSQL

### Convenções
- Sempre usar `import type` para imports apenas de tipos
- Componentes em PascalCase, hooks em camelCase com prefixo `use`
- Server Components por padrão; `'use client'` apenas quando necessário

### Proibido
- Nunca modificar arquivos em `src/db/migrations/` diretamente
- Nunca usar `any` sem um comentário explicando o motivo
- Nunca instalar dependências sem perguntar primeiro

### Testes
- Escrever teste junto com cada nova função de negócio
- Usar Vitest
- Testes ficam em `__tests__/` ao lado do arquivo testado

Workflow recomendado para tarefas complexas

Fase 1 — Entendimento
"Leia src/features/checkout/ e descreva em detalhes
 como o fluxo de pagamento funciona atualmente. PARE aqui."

→ Revise a descrição. Corrija qualquer mal-entendido.

Fase 2 — Planejamento
"Com base no que você leu, crie um plano para adicionar
 suporte a PIX. Liste os arquivos que serão modificados
 e as mudanças em cada um. PARE aqui."

→ Revise o plano. Remova o que não fizer sentido.

Fase 3 — Implementação
"Implemente o plano aprovado. Teste após cada fase.
 Se encontrar um erro que não sabe corrigir, PARE e me avise."

Fase 4 — Validação
"Execute os testes de integração do checkout.
 Se algum falhar, corrija e rode novamente."

MCPs que potencializam o Agent Mode

Limitações do Agent Mode a conhecer

• Limite de ferramentas: máximo de 40 ferramentas ativas entre todos os MCPs
• Contexto finito: projetos muito grandes podem exceder o context window; use referências explícitas
• Sem estado entre sessões (sem Memory MCP): cada nova conversa começa do zero
• Auto-run é irreversível: com ferramentas de escrita + auto-run, ações acontecem antes de você ver
• Modelos de raciocínio são lentos: o4-mini e Gemini 2.5 Pro são melhores para planejamento, mas mais lentos para implementação; use modelos mais rápidos para edições simples

Comandos rápidos para o Agent

# Análise sem ação
"Analise X e me diga o que encontrou. Não faça mudanças."

# Implementação com testes
"Implemente X. Escreva testes. Execute os testes e corrija falhas."

# Revisão de código
"Revise @src/api/payments.ts e aponte problemas de segurança."

# Refatoração incremental
"Refatore handleSubmit para usar React Hook Form. Mantenha os testes verdes."

# Debug com contexto do banco
"O endpoint POST /orders está retornando 500.
 Verifique os logs, consulte a tabela orders no banco e identifique o problema."

O Agent Mode com MCPs configurados transforma o Cursor de editor inteligente em um colega de equipe que executa tarefas end-to-end.