Deploy automático de Claude Code / Cursor para a Vercel — Três fluxos com MCP, Plugin e GitHub Actions

"O Claude Code já fez a correção; agora faço o push na mão e abro o painel da Vercel no navegador..." Para cortar esse vai e vem, a Vercel oferece oficialmente três ferramentas: o Vercel MCP (um servidor que permite às ferramentas de IA trabalhar com seus projetos, deploys e logs da Vercel), o Vercel Plugin (uma extensão que adiciona conhecimento da Vercel e comandos slash ao Claude Code, ao Cursor e a outros) e as Agent Skills (pacotes de instruções instalados com npx skills add). Os nomes são parecidos e os papéis parecem se sobrepor, por isso circulam explicações misturadas como "conectar as Agent Skills via MCP".

A conclusão primeiro: vale pensar no deploy de um agente de IA para a Vercel como três abordagens. ① A integração com Git (git push → deploy automático) basta para quase todo trabalho solo. ② Direto do editor (Vercel MCP, Vercel Plugin) é para quem quer que a IA cuide também do que envolve o deploy: ler logs, mexer em variáveis de ambiente. ③ GitHub Actions + Claude Code Action é para equipes que querem que o @claude corrija a partir dos comentários do PR e publicar só depois de passar em testes ou aprovações. Não existe um "melhor": depende de quanto você entrega à IA e onde uma pessoa a detém.

Este artigo foi escrito depois de reler a documentação original da Vercel e da Anthropic em 30 de setembro de 2026. Exemplos de configuração, comandos e condições de plano são dessa data (as duas mudam rápido: confira as páginas linkadas antes de confiar). Boas leituras complementares: A IA recomenda a Vercel, O que é o Cursor e A IA dá conta da infraestrutura?.

1. "Agent Skills", "MCP" e "Plugin" não são a mesma coisa

Mesmo com a IA escrevendo o código, conferir o deploy acontece em outra tela: voltar ao terminal para git add . && git commit -m "fix" && git push, abrir o painel da Vercel no navegador, copiar a URL de preview e colar no Slack. A Vercel foi adicionando, passo a passo, portas de entrada pensadas para IA para reduzir essa troca de contexto.

Colocá-las em ordem desfaz a confusão. Em 4 de agosto de 2025, o Vercel MCP entrou em beta pública (anúncio da Vercel): um servidor MCP remoto com autenticação OAuth em https://mcp.vercel.com. No mesmo mês, agosto de 2025, a Claude Code GitHub Action da Anthropic chegou à v1.0 (a tag v1.0.0 é de 2025-08-25). Em 17 de março de 2026 chegou o Vercel Plugin (anúncio) e em 23 de julho de 2026 o Vercel MCP passou a poder fazer deploy de código diretamente (anúncio).

E as Agent Skills não são MCP. A página de Agent Skills da Vercel as descreve como capacidades empacotadas, instaladas com npx skills add <owner/repo>, que ensinam a um agente uma forma específica de trabalhar, e que funcionam em mais de 18 agentes, entre eles Claude Code, GitHub Copilot e Cursor. Se o MCP é o meio de agir na sua conta, as Skills são o saber fazer. Veja também O que é MCP e Claude Agent SDK.

2. As cinco portas de entrada da Vercel: o que cada uma faz e como autentica

Estas são as vias pelas quais um agente de IA chega à Vercel, como descritas na documentação oficial (em 30 de setembro de 2026). A coluna de autenticação — o que você entrega à IA — decide o tamanho de um acidente.

Fontes: Vercel MCP, referência de ferramentas MCP, Vercel Plugin, Agent Skills, por que os commits não disparam deploys (KB da Vercel).

Como ler: se você só precisa que "faça o deploy", a integração com Git basta. MCP e Plugin compensam quando você quer que a conversa cubra o que envolve o deploy: a IA ler os logs para achar por que um build falhou, mostrar diferenças de variáveis de ambiente, voltar a produção um passo.

3. As três abordagens em um relance

Estas são as três abordagens segundo o que a IA recebe × profundidade da automação × onde uma pessoa a detém.

Regras práticas: se você costuma abrir o painel depois de um deploy só para ler logs, vá de ②. Se revisar PR é rotina e você só quer publicar mudanças testadas, vá de ③. Para um blog pessoal ou um app pequeno, ① basta: complicar custa mais em manutenção do que economiza. As três não se excluem; o comum é ① como base e ② ou ③ por cima.

4. Abordagem 1: integração com Git (deploy automático no git push)

A configuração mais básica. Conecte a Vercel ao GitHub e a Vercel fará o build a cada git push e publicará quando terminar. O trabalho da IA se resume a escrever código, escrever a mensagem do commit e fazer push. O próprio guia de GitHub Actions da Vercel diz que, como a integração com Git já cuida das URLs de preview, dos deploys imutáveis e do rollback instantâneo, a maioria das equipes não precisa de pipeline nenhum.

# Configuração (uma vez)
1. Painel da Vercel → Add New → Project
2. Escolha seu repositório do GitHub → Import
3. Framework Preset: detecção automática (Next.js etc.)
4. Environment Variables: adicione as necessárias
5. Deploy

# Fluxo diário (dentro do Cursor / Claude Code)
> Deixe este botão vermelho. Quando terminar, faça push para uma branch feature/red-button.

# Comandos que a IA executa
git switch -c feature/red-button
git add app/components/Button.tsx
git commit -m "feat: change primary button to red"
git push -u origin feature/red-button

# A Vercel faz o build de um preview → o PR recebe uma URL de preview

O valor real aqui é que cada branch ganha sua URL de preview automaticamente. As URLs de preview da Vercel são de dois tipos: uma URL da branch, que sempre aponta para o mais recente dela, e uma URL do commit, que aponta para aquele deploy exato (Environments). Se só os merges na main vão para produção, a IA pode fazer quantos pushes quiser e tudo para no preview.

Atenção: o plano Hobby é restrito a uso pessoal e não comercial (plano Hobby). Dá para criar 100 deploys por dia no Hobby e 6.000 no Pro, e o Hobby roda um build por vez (Limits). Se a IA fizer push em passos minúsculos, você bate nesses limites antes. Para as armadilhas de preço, veja o §5 de A IA recomenda a Vercel.

5. Abordagem 2: direto do editor (Vercel MCP e Vercel Plugin)

Para deixar a IA cuidar do que envolve o deploy, use o Vercel MCP ou o Vercel Plugin. Nenhum dos dois exige escrever um token em arquivo.

Configurando o Vercel MCP (Cursor): segundo as instruções oficiais, basta colocar uma URL no .cursor/mcp.json (do projeto ou global).

{
  "mcpServers": {
    "vercel": {
      "url": "https://mcp.vercel.com"
    }
  }
}

Depois de adicionado, o Cursor tenta conectar e mostra o aviso Needs login. Clique nele para entrar na Vercel pelo navegador e escolher quais times o Cursor pode usar. No Claude Code, são duas linhas:

claude mcp add --transport http vercel https://mcp.vercel.com
# depois inicie o claude e autentique com /mcp

A documentação também traz npx add-mcp https://mcp.vercel.com, que registra o servidor em vários clientes de uma vez. Atenção: adicionar o servidor não conclui a autorização. Até você fazer login e liberar o acesso a um time, a IA não vê os deploys nem os logs dele (referência de ferramentas).

O MCP oferece ferramentas, não comandos slash. Você pede algo como "veja os erros do meu último deploy" e a IA escolhe e chama ferramentas como estas (trecho da lista em 30 de setembro de 2026):

O Vercel Plugin (npx plugins add vercel/vercel-plugin) adiciona conhecimento da Vercel e cinco comandos slash, com namespace: /vercel-plugin:deploy (com prod para produção), /vercel-plugin:env (list, pull, add, remove, diff), /vercel-plugin:status, /vercel-plugin:bootstrap e /vercel-plugin:marketplace (Vercel Plugin). Lendo a definição do comando deploy, dá para ver que ele aciona a sua Vercel CLI local (vercel, vercel --prod), faz preview por padrão e espera um "sim" explícito antes da produção. Não existem comandos /logs nem /rollback; logs e rollback ficam com as ferramentas do MCP ou com a CLI (vercel rollback).

A grande vantagem é que tudo fica dentro da conversa. Peça "adicione esta API, faça deploy em preview e, se der erro, leia os logs e corrija" e a IA segue por mudança de código → deploy → checar o log do build → corrigir → novo deploy. Nos termos de A IA dá conta da infraestrutura?, isso fica na zona "capaz, mas perigoso". A Vercel deixa claro que uma conexão MCP dá à IA o mesmo acesso da sua conta de usuário da Vercel e recomenda sempre ativar a confirmação humana. Não deixe as chamadas de ferramenta em aprovação automática.

6. Abordagem 3: GitHub Actions (@claude e portões de verificação)

A configuração para equipes. Com o Claude Code GitHub Actions, você menciona @claude num comentário de issue ou PR e o Claude faz commit da correção e responde na mesma conversa. O deploy de preview continua a cargo da integração com Git da abordagem 1: quando o Claude faz push na branch do PR, a Vercel refaz o preview.

# Configuração
1. Rode /install-github-app dentro do Claude Code (só repositórios do github.com)
2. Instale a Claude GitHub App; guarde ANTHROPIC_API_KEY (ou CLAUDE_CODE_OAUTH_TOKEN) em Secrets
3. O .github/workflows/claude.yml chega como pull request

# .github/workflows/claude.yml (exemplo da documentação oficial)
name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    timeout-minutes: 30          # parar jobs descontrolados (recomendado pela doc)
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write            # necessário para a autenticação padrão via GitHub App
      actions: read              # ler resultados de CI nos PRs
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          claude_args: "--max-turns 10"   # limitar os turnos por execução

timeout-minutes e --max-turns foram acrescentados como exemplo: são as duas medidas que a seção "Manage costs" da documentação recomenda (ajuste os valores ao seu projeto). Por padrão, nenhum limite de turnos é aplicado, então defina você mesmo.

Se você também quer que o GitHub Actions faça o deploy — só quando precisa de testes, varreduras de segurança, orçamentos de desempenho ou aprovação humana antes do deploy —, siga o guia oficial da Vercel. São necessários três secrets: VERCEL_TOKEN, VERCEL_ORG_ID e VERCEL_PROJECT_ID (os dois últimos estão no .vercel/project.json criado pelo vercel link).

# .github/workflows/vercel-preview.yml (formato da KB da Vercel)
name: Vercel Preview Deployment
env:
  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
on:
  push:
    branches-ignore:
      - main
jobs:
  Deploy-Preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install --global vercel@latest
      - run: vercel pull --yes --environment=preview --token=${{ secrets.VERCEL_TOKEN }}
      # coloque aqui os testes e as varreduras
      - run: vercel build --token=${{ secrets.VERCEL_TOKEN }}
      - run: vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }}

# vercel.json — desliga os deploys disparados pelo Git para que os dois não façam deploy
{ "git": { "deploymentEnabled": false } }

O mesmo guia lista as armadilhas: se a integração com Git continuar ligada enquanto o Actions também faz deploy, os dois disparam no mesmo commit; sem --prebuilt, a Vercel faz o build da mesma coisa de novo. Ao contrário, se você só quer rodar testes, é mais leve manter a integração com Git, rodar os testes contra o preview no evento deployment_status e usar Deployment Checks para segurar a promoção para produção.

# Como fica na prática
# Um dev abre um PR → a integração com Git faz o build de um preview
[Bot] Vercel Preview: https://<url-do-preview>

# Um revisor comenta no PR
@claude faça este botão mudar de cor no hover também

# O Claude adiciona um commit e responde → a Vercel refaz o preview
# O revisor confere → approve → merge → deploy em produção

Atenção: em repositórios privados, o autor do commit precisa ser membro do time na Vercel (no Hobby, o dono) ou nada é publicado (KB da Vercel). Se commits feitos dentro do Actions não geram preview, confira primeiro o comentário do Vercel Bot e o autor do commit.

Essa configuração torna realista o cenário "nenhuma pessoa mexe no código até o PR ficar pronto". Como vimos em Veteranos vs. juniores e A IA vai eliminar os empregos de escritório?, a equipe se concentra na revisão enquanto a IA implementa.

7. Como usar os ambientes de preview: branch → URL → compartilhar

O que rende nas três abordagens é aproveitar ao máximo os ambientes de preview. A Vercel cria automaticamente deploys de preview para branches que não são de produção e para PRs, então dá para colocar várias versões da mesma mudança lado a lado sem configuração extra.

Fontes: Environments (opções de staging e planos), Password Protection (preço), Sharable Links (um no Hobby), tudo em 30 de setembro de 2026. A proteção padrão sem senha é a Vercel Authentication (só membros do time podem ver), que a Vercel apresenta como o método recomendado.

8. Quatro armadilhas: vazamento de env, limites e custos, conflitos, rollback

Ao entregar os deploys a um agente de IA, é fácil esbarrar nestas quatro. Todas podem ser contidas com configuração prévia.

Fontes: ferramentas MCP de variáveis de ambiente (get_project_env devolve o valor descriptografado), Spend Management (sem custo extra no Pro e em alguns planos Enterprise; o uso é checado a cada poucos minutos, então a pausa chega com algum atraso), Instant Rollback, configuração do Git.

O conselho tão repetido de "colocar um proxy da Cloudflare na frente da Vercel" não é uma defesa que recomendamos. Num artigo oficial da KB, a Vercel diz que não recomenda pôr um proxy externo na frente, porque o Vercel Firewall perde visibilidade do tráfego e o desempenho cai.

Mais um cuidado: não recomendamos automatizar por completo os deploys em produção com IA. Mesmo nas abordagens ② e ③, mantenha a aprovação final de uma pessoa para produção. Como vimos em O que não entregar a uma IA, a IA pode quebrar a produção com erros sem má intenção. Automatize até preview e staging e exija aprovação humana para produção: um portão em duas etapas.

Resumo

Ao pensar em deploy na Vercel a partir do Claude Code ou do Cursor, primeiro distinga a integração com Git, a CLI, o Vercel MCP, o Vercel Plugin e as Agent Skills. O MCP é o meio de agir, conectado via OAuth; o Plugin traz os comandos /vercel-plugin:* e conhecimento; as Skills são instruções. O deploy em si, na maioria dos casos, a integração com Git resolve bem.

A escolha depende de quanto você entrega à IA e onde uma pessoa a detém: ① trabalho solo → integração com Git; ② você quer que a IA investigue logs e gerencie o env → Vercel MCP / Plugin (sem token em arquivo: login com OAuth); ③ equipes com revisão de PR rotineira → GitHub Actions (@claude corrige; o deploy vem da integração com Git, ou de Actions + CLI quando você precisa de portões de verificação). Use os previews para comparação A/B, staging e revisão com o cliente, e enfrente as quatro armadilhas com confirmação das chamadas de ferramenta, ajustes de limites e gastos, um procedimento de rollback e aprovação humana para produção.

Para leituras relacionadas, veja A IA recomenda a Vercel, Vercel AI SDK, v0 vs Bolt vs Lovable, O que é o Cursor e A IA dá conta da infraestrutura?.

Perguntas frequentes

P. Dá para fazer o mesmo em outras hospedagens (Cloudflare, Netlify)?
R. Dá. As duas publicam servidores MCP oficiais. A Cloudflare mantém um catálogo de servidores MCP remotos aos quais você se conecta com OAuth, incluindo um para os builds do Workers (servidores MCP da Cloudflare). A Netlify tem o Netlify MCP Server. Escolha pelo encaixe com seu framework e pelo preço, não pela existência de integração com agentes. Veja também os critérios de A IA recomenda a Vercel.

P. O que é melhor para fazer deploy na Vercel, Claude Code ou Cursor?
R. Os dois são compatíveis com o Vercel MCP e com o Vercel Plugin, então o que dá para fazer na Vercel é quase igual. A diferença está no fluxo: o Claude Code é centrado no terminal, com integração oficial com GitHub Actions; o Cursor é centrado no editor, com adição do MCP em um clique. Se você vive no VS Code, o Cursor é natural; se vive no terminal, o Claude Code.

P. Posso deixar a IA automatizar por completo os deploys em produção?
R. Não é recomendado. Automatize até preview e staging, mas mantenha sempre a aprovação final de uma pessoa para produção. Os motivos: a IA pode quebrar a produção sem má intenção e a responsabilidade fica nebulosa quando algo dá errado. Use o Branch Protection do GitHub para bloquear push direto na main e exigir PRs aprovados.

P. Posso versionar o .cursor/mcp.json no git?
R. Com a configuração oficial do Vercel MCP, ele não contém segredos. Só tem a URL https://mcp.vercel.com; a autenticação é feita com OAuth e fica do lado do navegador, então versioná-lo para compartilhar com a equipe não tem problema. É diferente se você escreve a chave de API de outro servidor MCP direto num cabeçalho: esse arquivo não vai para o git. O VERCEL_TOKEN usado no CI fica nos Secrets do GitHub, nunca no arquivo do workflow.

P. Estou preocupado com o custo do GitHub Actions.
R. Segundo a documentação oficial, o custo vem de duas coisas: os minutos do GitHub Actions e os tokens da API do Claude (se você autentica com um token OAuth de assinatura, as execuções usam sua assinatura do Claude em vez da cobrança por API). O valor por execução depende do tamanho do prompt, da complexidade da tarefa e do tamanho do código. As formas de reduzir que a documentação cita: limitar os turnos com --max-turns em claude_args, pôr timeouts no workflow, escrever pedidos @claude específicos e manter o CLAUDE.md enxuto. Por padrão não há limite de turnos, então defina você mesmo.