Despliegue automático de Claude Code / Cursor a Vercel — Tres flujos con MCP, Plugin y GitHub Actions

«Claude Code ya hizo el arreglo; ahora hago push a mano y abro el panel de Vercel en el navegador...». Para recortar ese ir y venir, Vercel ofrece oficialmente tres herramientas: Vercel MCP (un servidor que permite a las herramientas de IA trabajar con tus proyectos, despliegues y logs de Vercel), el Vercel Plugin (una extensión que añade conocimiento de Vercel y comandos slash a Claude Code, Cursor y otros) y las Agent Skills (paquetes de instrucciones que se instalan con npx skills add). Los nombres se parecen y los papeles parecen solaparse, así que circulan explicaciones mezcladas como «conectar las Agent Skills por MCP».

La conclusión primero: conviene pensar el despliegue de un agente de IA a Vercel como tres enfoques. ① La integración con Git (git push → despliegue automático) basta para casi todo el trabajo en solitario. ② Directo desde el editor (Vercel MCP, Vercel Plugin) es para quien quiere que la IA se ocupe también de lo que rodea al despliegue: leer logs, tocar variables de entorno. ③ GitHub Actions + Claude Code Action es para equipos que quieren que @claude corrija desde los comentarios del PR y publicar solo tras pasar tests o aprobaciones. No hay un «mejor»: depende de cuánto delegas en la IA y dónde la frena una persona.

Este artículo se escribió tras releer la documentación original de Vercel y Anthropic el 30 de septiembre de 2026. Los ejemplos de configuración, comandos y condiciones de plan son de esa fecha (ambas cambian rápido: comprueba las páginas enlazadas antes de fiarte). Complementan bien La IA recomienda Vercel, Qué es Cursor y ¿Puede la IA gestionar la infraestructura?.

1. «Agent Skills», «MCP» y «Plugin» no son lo mismo

Aunque la IA escriba el código, comprobar el despliegue ocurre en otra pantalla: volver al terminal para git add . && git commit -m "fix" && git push, abrir el panel de Vercel en el navegador, copiar la URL de preview y pegarla en Slack. Vercel ha ido añadiendo puertas de entrada pensadas para la IA para reducir ese cambio de contexto.

Ordenarlas en el tiempo deshace la confusión. El 4 de agosto de 2025, Vercel MCP entró en beta pública (anuncio de Vercel): un servidor MCP remoto con autenticación OAuth en https://mcp.vercel.com. Ese mismo mes, agosto de 2025, la Claude Code GitHub Action de Anthropic llegó a la v1.0 (la etiqueta v1.0.0 es del 2025-08-25). El 17 de marzo de 2026 llegó el Vercel Plugin (anuncio) y el 23 de julio de 2026 Vercel MCP pasó a poder desplegar código directamente (anuncio).

Y las Agent Skills no son MCP. La página de Agent Skills de Vercel las describe como capacidades empaquetadas que se instalan con npx skills add <owner/repo> para enseñar a un agente una forma concreta de trabajar, y funcionan en más de 18 agentes, entre ellos Claude Code, GitHub Copilot y Cursor. Si MCP es el medio para actuar sobre tu cuenta, las Skills son el saber hacer. Consulta también Qué es MCP y Claude Agent SDK.

2. Las cinco puertas de entrada a Vercel: qué hace cada una y cómo se autentica

Estas son las vías por las que un agente de IA puede llegar a Vercel, tal como las describe la documentación oficial (a 30 de septiembre de 2026). La columna de autenticación —lo que entregas a la IA— decide lo grave que puede ser un accidente.

Fuentes: Vercel MCP, referencia de herramientas MCP, Vercel Plugin, Agent Skills, por qué los commits no disparan despliegues (KB de Vercel).

Cómo leerla: si solo necesitas que «se despliegue», la integración con Git basta. MCP y el Plugin compensan cuando quieres que la conversación cubra lo que rodea al despliegue: que la IA lea los logs para ver por qué falló un build, mostrar diferencias de variables de entorno, volver producción un paso atrás.

3. Los tres enfoques de un vistazo

Estos son los tres enfoques según qué recibe la IA × profundidad de la automatización × dónde la frena una persona.

Reglas prácticas: si sueles abrir el panel tras un despliegue solo para leer logs, ve a ②. Si revisar PR es rutina y solo quieres publicar cambios probados, ve a ③. Para un blog personal o una app pequeña, ① basta: complicarlo cuesta más en mantenimiento de lo que ahorra. Los tres no se excluyen; lo habitual es ① como base y ② o ③ encima.

4. Enfoque 1: integración con Git (despliegue automático con git push)

La configuración más básica. Conecta Vercel con GitHub y Vercel construirá en cada git push y publicará al terminar el build. El trabajo de la IA se reduce a escribir código, escribir el mensaje del commit y hacer push. La propia guía de GitHub Actions de Vercel dice que, como la integración con Git ya se ocupa de las URL de preview, los despliegues inmutables y el rollback instantáneo, la mayoría de los equipos no necesita ningún pipeline.

# Configuración (una sola vez)
1. Panel de Vercel → Add New → Project
2. Elige tu repositorio de GitHub → Import
3. Framework Preset: detección automática (Next.js, etc.)
4. Environment Variables: añade las que necesites
5. Deploy

# Flujo diario (dentro de Cursor / Claude Code)
> Pon este botón en rojo. Cuando termines, haz push a una rama feature/red-button.

# Comandos que ejecuta la IA
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

# Vercel construye un preview → el PR recibe una URL de preview

El valor real aquí es que cada rama recibe su URL de preview automáticamente. Las URL de preview de Vercel son de dos tipos: una URL de rama que siempre apunta a lo último de esa rama y una URL de commit que apunta a ese despliegue exacto (Environments). Si solo los merges a main van a producción, la IA puede hacer push cuantas veces quiera y todo se queda en preview.

Atención: el plan Hobby está limitado a uso personal y no comercial (plan Hobby). Se pueden crear 100 despliegues al día en Hobby y 6.000 en Pro, y Hobby ejecuta un build a la vez (Limits). Si dejas que la IA haga push en pasos diminutos, chocarás antes con estos límites. Para las trampas de precios, consulta el §5 de La IA recomienda Vercel.

5. Enfoque 2: directo desde el editor (Vercel MCP y Vercel Plugin)

Para que la IA se ocupe de lo que rodea al despliegue, usa Vercel MCP o el Vercel Plugin. Ninguno exige escribir un token en un archivo.

Configurar Vercel MCP (Cursor): según las instrucciones oficiales, basta con poner una URL en .cursor/mcp.json (a nivel de proyecto o global).

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

Al añadirlo, Cursor intenta conectar y muestra un aviso Needs login. Haz clic para iniciar sesión en Vercel desde el navegador y elegir qué equipos puede usar Cursor. En Claude Code son dos líneas:

claude mcp add --transport http vercel https://mcp.vercel.com
# luego inicia claude y autentícate con /mcp

La documentación también incluye npx add-mcp https://mcp.vercel.com, que registra el servidor en varios clientes a la vez. Ojo: añadir el servidor no completa la autorización. Hasta que inicies sesión y concedas acceso a un equipo, la IA no ve sus despliegues ni sus logs (referencia de herramientas).

MCP ofrece herramientas, no comandos slash. Pides algo como «revisa los errores de mi último despliegue» y la IA elige y llama a herramientas como estas (extracto de la lista a 30 de septiembre de 2026):

El Vercel Plugin (npx plugins add vercel/vercel-plugin) añade conocimiento de Vercel y cinco comandos slash, con espacio de nombres: /vercel-plugin:deploy (con prod para producción), /vercel-plugin:env (list, pull, add, remove, diff), /vercel-plugin:status, /vercel-plugin:bootstrap y /vercel-plugin:marketplace (Vercel Plugin). Si lees la definición del comando deploy, verás que maneja tu Vercel CLI local (vercel, vercel --prod), por defecto crea un preview y espera un «sí» explícito antes de producción. No existen comandos /logs ni /rollback; los logs y el rollback se hacen con herramientas MCP o con la CLI (vercel rollback).

La gran ventaja es que todo queda dentro de la conversación. Pide «añade esta API, despliégala en preview y, si hay un error, lee los logs y corrígelo» y la IA avanzará por cambio de código → despliegue → revisar el log del build → corregir → redesplegar. En los términos de ¿Puede la IA gestionar la infraestructura?, esto cae en la zona «capaz pero peligroso». Vercel deja claro que una conexión MCP da a la IA el mismo acceso que tu cuenta de usuario de Vercel y recomienda activar siempre la confirmación humana. No pongas las llamadas a herramientas en aprobación automática.

6. Enfoque 3: GitHub Actions (@claude y compuertas de verificación)

La configuración para equipos. Con Claude Code GitHub Actions, mencionas a @claude en un comentario de issue o PR y Claude hace commit de la corrección y responde en el mismo hilo. El despliegue de preview lo sigue haciendo la integración con Git del enfoque 1: cuando Claude hace push a la rama del PR, Vercel reconstruye el preview.

# Configuración
1. Ejecuta /install-github-app dentro de Claude Code (solo repositorios de github.com)
2. Instala la Claude GitHub App; guarda ANTHROPIC_API_KEY (o CLAUDE_CODE_OAUTH_TOKEN) en Secrets
3. .github/workflows/claude.yml llega como pull request

# .github/workflows/claude.yml (ejemplo de la documentación 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          # detener trabajos desbocados (lo recomienda la doc)
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write            # necesario para la autenticación por defecto con la GitHub App
      actions: read              # leer resultados de CI en los PR
    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 los turnos por ejecución

timeout-minutes y --max-turns están añadidos como ejemplo: son las dos medidas que recomienda la sección «Manage costs» de la documentación (ajusta los valores a tu proyecto). Por defecto no se aplica ningún límite de turnos, así que ponlo tú.

Si además quieres que GitHub Actions despliegue —solo cuando necesitas tests, escaneos de seguridad, presupuestos de rendimiento o una aprobación humana antes del despliegue—, sigue la guía oficial de Vercel. Necesitas tres secretos: VERCEL_TOKEN, VERCEL_ORG_ID y VERCEL_PROJECT_ID (los dos últimos están en el .vercel/project.json que crea vercel link).

# .github/workflows/vercel-preview.yml (forma de la KB de 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 }}
      # aquí van los tests y los escaneos
      - run: vercel build --token=${{ secrets.VERCEL_TOKEN }}
      - run: vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }}

# vercel.json — desactiva los despliegues de Git para que no desplieguen los dos
{ "git": { "deploymentEnabled": false } }

La misma guía enumera las trampas: si dejas activa la integración con Git mientras Actions también despliega, ambos se disparan con el mismo commit; sin --prebuilt, Vercel vuelve a construir lo mismo. Al revés, si solo quieres ejecutar tests, es más ligero mantener la integración con Git, lanzar los tests contra el preview con el evento deployment_status y usar Deployment Checks para frenar la promoción a producción.

# Cómo se ve en la práctica
# Un desarrollador abre un PR → la integración con Git construye un preview
[Bot] Vercel Preview: https://<url-de-preview>

# Un revisor comenta en el PR
@claude haz que este botón también cambie de color al pasar el ratón

# Claude añade un commit y responde → Vercel reconstruye el preview
# El revisor comprueba → approve → merge → despliegue a producción

Atención: en repositorios privados, el autor del commit debe ser miembro del equipo de Vercel (en Hobby, el propietario) o no se despliega nada (KB de Vercel). Si los commits hechos dentro de Actions no generan preview, revisa primero el comentario del Vercel Bot y el autor del commit.

Esta configuración hace realista el escenario de «ninguna persona toca el código hasta que el PR está listo». Como vimos en Veteranos vs. juniors y ¿Eliminará la IA los empleos de oficina?, el equipo se centra en revisar mientras la IA implementa.

7. Cómo usar los entornos de preview: rama → URL → compartir

Lo que rinde en los tres enfoques es aprovechar a fondo los entornos de preview. Vercel crea automáticamente despliegues de preview para las ramas que no son de producción y para los PR, así que puedes poner varias versiones del mismo cambio lado a lado sin configuración extra.

Fuentes: Environments (opciones de staging y planes), Password Protection (precio), Sharable Links (uno en Hobby), todo a 30 de septiembre de 2026. La protección por defecto sin contraseña es Vercel Authentication (solo los miembros del equipo pueden ver), que Vercel presenta como el método recomendado.

8. Cuatro trampas: fugas de env, límites y costes, conflictos, rollback

Si delegas los despliegues en un agente de IA, es fácil toparse con estas cuatro. Todas se pueden contener con configuración previa.

Fuentes: herramientas MCP de variables de entorno (get_project_env devuelve el valor descifrado), Spend Management (sin coste extra en Pro y en algunos planes Enterprise; el uso se comprueba cada pocos minutos, así que la pausa llega con algo de retraso), Instant Rollback, configuración de Git.

El consejo tan repetido de «poner un proxy de Cloudflare delante de Vercel» no es una defensa que recomendemos. En un artículo oficial de la KB, Vercel dice que no recomienda poner un proxy externo delante, porque el Vercel Firewall pierde visibilidad del tráfico y el rendimiento baja.

Un aviso más: no recomendamos automatizar por completo los despliegues a producción con IA. Incluso con los enfoques ② y ③, mantén la aprobación final de una persona para producción. Como vimos en Qué no darle a una IA, la IA puede romper producción con errores sin mala intención. Automatiza hasta preview y staging y exige aprobación humana para producción: una compuerta en dos etapas.

Resumen

Al pensar en desplegar a Vercel desde Claude Code o Cursor, primero distingue la integración con Git, la CLI, Vercel MCP, el Vercel Plugin y las Agent Skills. MCP es el medio para actuar, conectado por OAuth; el Plugin aporta comandos /vercel-plugin:* y conocimiento; las Skills son instrucciones. El despliegue en sí, en la mayoría de los casos, lo resuelve bien la integración con Git.

La elección depende de cuánto delegas en la IA y dónde la frena una persona: ① trabajo en solitario → integración con Git; ② quieres que la IA investigue logs y gestione el env → Vercel MCP / Plugin (sin token en archivos: inicio de sesión con OAuth); ③ equipos con revisión de PR habitual → GitHub Actions (@claude corrige; el despliegue viene de la integración con Git, o de Actions + CLI cuando necesitas compuertas de verificación). Usa los previews para comparación A/B, staging y revisión con el cliente, y afronta las cuatro trampas con confirmación de las llamadas a herramientas, ajustes de límites y gasto, un procedimiento de rollback y aprobación humana para producción.

Como lecturas relacionadas, consulta La IA recomienda Vercel, Vercel AI SDK, v0 vs Bolt vs Lovable, Qué es Cursor y ¿Puede la IA gestionar la infraestructura?.

Preguntas frecuentes

P. ¿Puedo hacer lo mismo con otros hostings (Cloudflare, Netlify)?
R. Sí. Ambos publican servidores MCP oficiales. Cloudflare mantiene un catálogo de servidores MCP remotos a los que te conectas con OAuth, entre ellos uno para los builds de Workers (servidores MCP de Cloudflare). Netlify tiene el Netlify MCP Server. Elige por encaje con tu framework y por precio, no por si existe integración con agentes. Consulta también los criterios de La IA recomienda Vercel.

P. ¿Qué es mejor para desplegar en Vercel, Claude Code o Cursor?
R. Ambos son compatibles con Vercel MCP y con el Vercel Plugin, así que lo que puedes hacer en Vercel es casi lo mismo. La diferencia está en el flujo: Claude Code es centrado en el terminal, con integración oficial con GitHub Actions; Cursor es centrado en el editor, con alta de MCP en un clic. Si vives en VS Code, Cursor resulta natural; si vives en el terminal, Claude Code.

P. ¿Puedo dejar que la IA automatice por completo los despliegues a producción?
R. No se recomienda. Automatiza hasta preview y staging, pero mantén siempre la aprobación final de una persona para producción. Las razones: la IA puede romper producción sin mala intención y la responsabilidad se vuelve difusa cuando algo sale mal. Usa Branch Protection de GitHub para bloquear el push directo a main y exigir PR aprobados.

P. ¿Puedo subir .cursor/mcp.json a git?
R. Con la configuración oficial de Vercel MCP no contiene secretos. Solo tiene la URL https://mcp.vercel.com; la autenticación se hace con OAuth y queda del lado del navegador, así que subirlo para compartirlo con el equipo está bien. Es distinto si escribes a mano la clave de API de otro servidor MCP en una cabecera: ese archivo no debe ir a git. El VERCEL_TOKEN que uses en CI va en los Secrets de GitHub, nunca en el archivo del workflow.

P. Me preocupa el coste de GitHub Actions.
R. Según la documentación oficial, el coste viene de dos cosas: los minutos de GitHub Actions y los tokens de la API de Claude (si te autenticas con un token OAuth de suscripción, las ejecuciones consumen tu suscripción de Claude en lugar de facturación por API). El importe por ejecución depende de la longitud del prompt, la complejidad de la tarea y el tamaño del código. Las formas de reducirlo que da la documentación: limitar los turnos con --max-turns en claude_args, poner timeouts al workflow, escribir peticiones @claude concretas y mantener CLAUDE.md breve. Por defecto no hay límite de turnos, así que ponlo tú.