Contexto Visual para tu Agente de Código con MCP

Los agentes de código trabajan con texto, pero tu interfaz es visual. Tres servidores MCP, Vibe Annotations, mcp-screenshot-server y Playwright MCP, cierran esa brecha dando a tu agente la capacidad de ver capturas, leer anotaciones y verificar cambios en el navegador. En este artículo configuras las tres herramientas y aprendes cuándo usar cada una.

El Problema: Tu Agente de Código Es Ciego

Describir un bug visual en texto a un agente de código es como explicar un color por teléfono. Puedes decir "el botón de login está desalineado 10 píxeles a la derecha", pero el agente no tiene forma de verificar si su corrección resolvió el problema. Trabaja a ciegas.

Los agentes de IA como Claude Code, Cursor o Copilot operan en un mundo fundamentalmente textual. Leen tu código, ejecutan tests, analizan logs. Pero cuando el trabajo implica interfaces visuales, CSS, layouts o componentes gráficos, la comunicación se rompe.

El flujo habitual es frustrante: haces una captura de pantalla, la guardas como archivo, copias la ruta, la pegas en el prompt del agente, y luego describes en texto qué tiene de malo. El agente propone un cambio, tú verificas manualmente, y el ciclo se repite. Cada iteración consume minutos y contexto.

Este problema no es teórico. A marzo de 2026, Claude Code en Windows ni siquiera soporta pegar imágenes del portapapeles de forma nativa. En macOS funciona con Ctrl+V, pero la experiencia sigue siendo limitada. Hay múltiples issues abiertas en GitHub pidiendo soporte nativo, sin fecha confirmada por Anthropic.

La solución no viene del propio agente. Viene de su ecosistema de herramientas.

Conceptos Clave

¿Qué es el contexto visual en agentes de código?

Contexto visual es cualquier información gráfica que un agente puede procesar para entender el estado de una interfaz. Incluye capturas de pantalla, anotaciones sobre elementos del DOM, diagramas, y el árbol de accesibilidad del navegador. Sin contexto visual, el agente solo puede inferir cómo se ve tu app leyendo el código fuente, lo que falla con CSS complejo, estados dinámicos y contenido renderizado por el servidor.

¿Qué es MCP y por qué importa aquí?

MCP (Model Context Protocol) es un estándar abierto creado por Anthropic que define cómo los modelos de IA se comunican con herramientas externas. Funciona como un adaptador universal: escribes un servidor MCP una vez y funciona con cualquier cliente compatible, ya sea Claude Code, Cursor, Copilot o Windsurf.

Para el contexto visual, MCP permite que herramientas de captura y anotación expongan sus funciones directamente al agente. El agente no necesita "saber" cómo tomar una captura de pantalla. Solo llama a la herramienta MCP correspondiente y recibe el resultado como parte de su conversación.

Desde que Anthropic donó MCP a la Linux Foundation a finales de 2025, el ecosistema ha crecido a miles de servidores. Los tres que cubrimos aquí resuelven distintos aspectos del contexto visual.

Tres Herramientas MCP para Contexto Visual

1. Vibe Annotations: Anota Directamente en tu App

Vibe Annotations es una extensión de navegador combinada con un servidor MCP local. En lugar de describir un problema, haces clic en el elemento de tu app y dejas un comentario. El agente lee las anotaciones via MCP e implementa los cambios.

Instalación:

# Instalar el servidor globalmente
npm install -g vibe-annotations-server

# Iniciar el servidor
vibe-annotations-server start

# Verificar que está corriendo
vibe-annotations-server status

Configuración en Claude Code:

# Transporte HTTP (recomendado por estabilidad)
claude mcp add --transport http vibe-annotations http://127.0.0.1:3846/mcp

Configuración en Cursor (settings JSON):

{
  "mcpServers": {
    "vibe-annotations": {
      "url": "http://127.0.0.1:3846/mcp"
    }
  }
}

El flujo es directo: instalas la extensión desde la Chrome Web Store, navegas a tu app en localhost, haces clic en "Annotate" en la barra flotante, seleccionas un elemento y escribes tu feedback. El agente recibe la anotación con el contexto del DOM, los estilos CSS y, opcionalmente, una captura recortada del elemento. Cuando el agente implementa el fix, la anotación se elimina automáticamente.

Funciona en URLs locales: localhost, 127.0.0.1, dominios .local, .test y .localhost. Los datos se almacenan en ~/.vibe-annotations y nunca salen de tu máquina. Es gratuito y open source.

2. mcp-screenshot-server: Capturas con Anotación Programática

Este servidor MCP en Python permite al agente capturar pantalla completa, anotar con formas geométricas, texto, flechas y números, y exportar el resultado. Es la opción cuando necesitas que el agente documente visualmente lo que ve o cuando trabajas fuera del navegador.

Instalación:

# Con pip
pip install mcp-screenshot-server

# O con uv (más rápido)
uv add mcp-screenshot-server

Configuración en Claude Code o Cursor:

{
  "mcpServers": {
    "screenshot": {
      "command": "mcp-screenshot-server",
      "args": []
    }
  }
}

El servidor expone más de 30 herramientas organizadas en categorías: captura (capture_screenshot, load_image), anotación inteligente (annotate, precise_annotate, batch_annotate), edición (blur_region, crop_image, resize_image) y exportación (save_image, copy_to_clipboard).

El flujo con visión AI: el agente captura una pantalla, el modelo de visión analiza la imagen e identifica coordenadas de elementos, y luego llama a precise_annotate para marcar dónde está el problema. Compatible con Claude, Gemini y otros modelos con capacidad de visión. Requiere Python 3.10+ y licencia MIT.

3. Playwright MCP: Automatización de Navegador

El servidor MCP oficial de Microsoft usa Playwright para dar al agente control directo del navegador. No solo toma capturas: navega, hace clic, rellena formularios y verifica resultados. Es la opción para verificación automática de cambios UI.

Instalación en Claude Code:

# Un solo comando
claude mcp add playwright npx @playwright/mcp@latest

La instalación de binarios del navegador es automática. La primera vez que el servidor detecta que falta un navegador, lo descarga e instala sin intervención manual. Requiere Node.js 18+.

El caso de uso clave es el "round-trip visual": el agente modifica un componente CSS, abre tu app en el navegador via Playwright, toma una captura con browser_take_screenshot, la analiza con visión, y verifica si el cambio es correcto. Si algo no coincide, itera automáticamente. Todo sin que toques el teclado.

Una diferencia importante: Playwright MCP usa el árbol de accesibilidad del navegador para interactuar con la página, no capturas de pantalla. Esto lo hace más eficiente en tokens y más estable que enfoques puramente visuales. Expone 34 herramientas incluyendo navegación, clics, escritura y assertions.

Comparativa: ¿Cuál Elegir?

Criterio	Vibe Annotations	mcp-screenshot-server	Playwright MCP
Tipo de contexto	Anotaciones en DOM + CSS	Capturas anotadas (imagen)	Navegador + árbol de accesibilidad
Dirección	Developer hacia agente	Bidireccional	Agente autónomo
Instalación	npm + extensión Chrome	pip / uv	npx (una línea)
Caso ideal	Feedback visual directo	Documentación visual, QA	Verificación automática post-cambio
Agentes compatibles	Claude Code, Cursor, Windsurf, Copilot	Claude, Gemini, Cursor	Cualquier cliente MCP
Requiere modelo con visión	No (envía datos estructurados)	Sí (envía imágenes)	Opcional (accesibilidad es texto)
Privacidad	100% local	100% local	100% local
Licencia	Open source	MIT	Apache 2.0

No son excluyentes. En un flujo de desarrollo frontend puedes usar las tres: Vibe Annotations para comunicar qué quieres cambiar, Playwright MCP para que el agente verifique el resultado, y mcp-screenshot-server para documentar el antes y después.

Caso Práctico: Debugging Visual de Frontend

Imagina un componente de checkout donde el botón de pago se solapa con el resumen del pedido en pantallas de 768px. Sin contexto visual, tendrías que escribir algo como: "El botón .checkout-btn se solapa con .order-summary en viewports de 768px, probablemente un problema de flex-wrap o margin-bottom insuficiente."

Con Vibe Annotations, haces clic en el botón solapado, escribes "este botón se solapa con el resumen en 768px" y el agente recibe el HTML, los estilos computados y el ancho del viewport. Con esa información, aplica un fix de CSS y usa Playwright MCP para abrir la página en un viewport de 768px, tomar una captura y verificar que la superposición desapareció.

El ciclo se reduce de 5-10 minutos de ida y vuelta manual a una sola interacción. Y lo más importante: el agente puede verificar su propio trabajo sin depender de tu confirmación visual.

En Producción

Estas herramientas funcionan en local, pero hay consideraciones cuando las integras en tu workflow diario.

Consumo de tokens. Cada servidor MCP activo inyecta sus definiciones de herramientas en el contexto del modelo. Playwright MCP expone 34 herramientas. mcp-screenshot-server, más de 30. Con siete servidores MCP activos, puedes consumir un 25% de tu ventana de 200k tokens antes de escribir un prompt. Activa solo los servidores que necesitas para la tarea actual y desactiva el resto.

Coste de API. Las capturas de pantalla se envían como imágenes al modelo. Una captura de 1920x1080 en base64 consume entre 1.000 y 2.000 tokens de entrada. En un flujo de debugging con 10 capturas por sesión, eso suma entre 10.000 y 20.000 tokens adicionales, aproximadamente 0,15 a 0,30 euros por sesión con modelos como Claude Sonnet. Asumible, pero conviene ser consciente. Si el grueso de tu trabajo no requiere visión, usar modelos locales para tareas sin componente visual reduce el gasto.

Estabilidad de conexión. Vibe Annotations con transporte SSE puede experimentar desconexiones intermitentes (TypeError: terminated). La solución es cambiar a transporte HTTP: reemplaza /sse por /mcp en la configuración. Es un problema conocido y documentado en el repositorio oficial.

Escalabilidad y límites. Estas herramientas están pensadas para desarrollo local. No ejecutes servidores MCP de captura de pantalla en entornos CI/CD o servidores remotos sin interfaz gráfica. Para testing visual automatizado en pipelines, Playwright estándar (sin MCP) con comparación de capturas sigue siendo la opción madura.

En escenarios de producción con agentes IA, el contexto visual es una herramienta de desarrollo, no de despliegue. Tenlo presente al diseñar tus flujos.

Errores Comunes y Depuración

Error: Vibe Annotations no detecta la extensión. Causa: El servidor no está corriendo o la URL no es local. Solución: Ejecuta vibe-annotations-server status y verifica que estás en localhost, 127.0.0.1 o un dominio .local/.test.

Error: Playwright MCP intenta ejecutar via Bash en lugar de MCP. Causa: Claude Code no reconoce el servidor en la primera interacción. Solución: Menciona "usa playwright mcp" en tu primer prompt de la sesión para forzar el reconocimiento.

Error: performance is not defined al iniciar Playwright MCP. Causa: Node.js anterior a la versión 18. Solución: Actualiza con nvm install 18 o superior. Verifica con node --version.

Error: El agente no ve las herramientas MCP después de añadirlas. Causa: Claude Code carga las configuraciones MCP al inicio de sesión. Solución: Reinicia la sesión de Claude Code después de ejecutar claude mcp add. Verifica con el comando /mcp dentro de la sesión.

Preguntas Frecuentes

¿Necesito un modelo con capacidad de visión para usar estas herramientas?

Depende de la herramienta. Vibe Annotations envía datos estructurados (DOM, CSS, texto), no imágenes, así que funciona con cualquier modelo. mcp-screenshot-server y Playwright MCP envían capturas que requieren un modelo con visión como Claude Opus, Claude Sonnet o Gemini Pro. Si tu modelo no soporta imágenes, limita tu uso a herramientas basadas en texto y accesibilidad.

¿Puedo usar varias herramientas MCP de contexto visual a la vez?

Sí, pero con precaución. Cada servidor añade definiciones de herramientas al contexto. Con tres servidores visuales activos puedes consumir entre un 15% y un 20% de tokens solo en definiciones. La recomendación: activa Vibe Annotations como base (es ligero en contexto) y añade Playwright o mcp-screenshot-server solo cuando los necesites para una tarea concreta.

¿Funcionan estas herramientas con agentes de terminal como Gemini CLI?

Sí. Gemini CLI soporta MCP de forma nativa, tanto como cliente como servidor. Puedes conectar cualquiera de estas herramientas usando la misma configuración MCP. La compatibilidad cruzada entre agentes es una ventaja directa del estándar abierto.

Cierre

Hemos visto cómo la brecha entre lo visual y lo textual limita a los agentes de código, y cómo tres herramientas MCP la cierran desde ángulos complementarios. Vibe Annotations resuelve la comunicación developer-agente con un clic. Playwright MCP da al agente la capacidad de verificar sus propios cambios. Y mcp-screenshot-server documenta visualmente cada paso del proceso.

La clave no es elegir una sola herramienta, sino entender cuál resuelve qué parte del flujo. El contexto visual no reemplaza los tests ni las revisiones humanas. Los complementa donde el texto se queda corto. En próximos artículos exploraremos cómo configurar workflows multi-agente donde uno escribe código y otro revisa visualmente el resultado.

¿Has integrado herramientas de contexto visual en tu workflow con agentes de código? Cuéntame tu experiencia en Twitter @sergiomarquezp_.