Diseño de API para agentes

A principios de 2025, Webflow comenzó a trabajar en MCP antes de que existiera un manual claro para API preparadas para agentes. Anunciamos públicamente nuestro servidor MCP en abril de 2025 y luego nos unimos al Demo Day de Cloudflare en mayo de 2025 junto a la primera oleada de servidores MCP remotos.

Nuestro primer enfoque fue sencillo: adaptar las API existentes como herramientas MCP. Pero pronto aprendimos que las API diseñadas para desarrolladores no funcionan bien para los agentes. Las API para desarrolladores asumen que los humanos pueden leer documentación, investigar u obtener respuestas de diversas fuentes externas, componer endpoints granulares, gestionar estados y manejar errores manualmente. Los agentes operan con mucho menos contexto implícito y dependen en gran medida de la propia superficie de la API para guiar la planificación, la ejecución y decidir si deben reintentar, revisar o detenerse. Por eso, exponer directamente las API de desarrollador a los agentes hizo que nuestras primeras herramientas MCP fueran demasiado básicas y excesivamente conversacionales, requiriendo a menudo muchas llamadas a herramientas para tareas simples y teniendo dificultades con flujos de trabajo más complejos. El resultado fueron fallos sutiles, tiempos de ejecución ineficientes y una finalización de tareas poco fiable.

Durante el año siguiente, iteramos intensamente: rediseñamos las herramientas en torno a intenciones en lugar de endpoints, simplificamos los esquemas, mejoramos la eficiencia de las llamadas a herramientas e hicimos que las respuestas fueran más fáciles de procesar para los agentes. También seguimos invirtiendo profundamente en los cimientos, desde la capa de código hasta las abstracciones del sistema de archivos, para respaldar flujos de trabajo de agentes más fiables y capaces.

Muchas de esas decisiones ahora se asemejan a patrones emergentes en la industria: herramientas orientadas a tareas, esquemas legibles por agentes, orientación de errores procesable y API diseñadas en torno a la intención en lugar de detalles de implementación. Esta publicación comparte las lecciones que dieron forma al servidor MCP de Webflow y por qué diseñar para agentes terminó siendo mucho más amplio que simplemente exponer API a través de MCP. Requirió repensar cómo los sistemas autónomos descubren capacidades, coordinan la ejecución, navegan por las superficies de los productos y operan de manera fiable durante el tiempo de ejecución.

Por qué las API para desarrolladores no funcionan bien para los agentes

Un usuario podría pedirle a un agente que actualice el encabezado de la página de inicio. En una API tradicional, eso puede convertirse en una cadena de operaciones de bajo nivel:

list pages
→ find homepage
→ fetch page content
→ inspect content tree
→ find hero section
→ update content

Las primeras implementaciones de MCP a menudo exponían las API de desarrollador existentes directamente como herramientas MCP:

getPages()
getPageContent(pageId)
updateContent(contentId, payload)
publishPage(pageId)

MCP en sí no era el problema. El protocolo funcionaba según lo previsto. Un LLM solo ve descripciones de herramientas, esquemas, respuestas previas y la ventana de contexto actual. Tiene que inferir la estrategia de ejecución de forma dinámica mientras preserva el estado intermedio a través de múltiples llamadas a herramientas. Ahí es donde empiezan a aparecer los modos de fallo. Cada llamada adicional a una herramienta aumenta la latencia, el consumo de tokens, la presión sobre el contexto y la probabilidad de error en la ejecución. Ahora el agente tiene que:

• preservar correctamente los identificadores intermedios
• seleccionar el recurso correcto a partir de resultados ambiguos
• interpretar respuestas ruidosas o demasiado genéricas
• coordinar operaciones dependientes en secuencia
• decidir si los fallos son reintentables o terminales

Incluso cuando la API admite técnicamente el flujo de trabajo, gran parte del presupuesto de tiempo de ejecución del modelo se dedica a navegar por la API en lugar de completar la tarea del usuario.

Lo que necesita una API para agentes

La lección para nosotros fue que exponer API a través de MCP era solo el punto de partida. La fiabilidad de la ejecución del agente dependía mucho más de la forma y la semántica de las propias herramientas. Las API para desarrolladores suelen optimizarse para la flexibilidad y la componibilidad. Las API para agentes deben optimizarse para la fiabilidad de la ejecución: menos opciones ambiguas, menos llamadas dependientes, menos estado que preservar y una guía más clara cuando algo sale mal.

Para la actualización del encabezado de la página de inicio, la mejor interfaz es una herramienta a nivel de tarea que coincida directamente con la intención del usuario:

update_page_section({
  page: "home",
  section: "hero",
  changes: {
    heading: "Build faster with Webflow"
  }
})

Las API declarativas convierten flujos de trabajo complejos de varios pasos en una única llamada basada en la intención. En lugar de requerir que el agente descubra estructuras internas, preserve el estado intermedio, coordine operaciones dependientes o se recupere de fallos parciales, la plataforma gestiona la orquestación internamente. Esto reduce los modos de fallo y permite que el agente se centre en el objetivo del usuario en lugar de en los detalles de ejecución.

Pasar de API de bajo nivel a herramientas a nivel de tarea fue un acierto, pero introdujo un nuevo problema a la escala de Webflow: la explosión de herramientas. Webflow admite demasiados flujos de trabajo válidos como para modelar cada uno como su propia herramienta MCP. Un diseño puramente orientado a tareas crea rápidamente una superficie de herramientas grande y superpuesta que se vuelve difícil de navegar para los agentes. Para resolver este problema, existen básicamente 2 enfoques y discutiremos ambos patrones con más profundidad en las secciones siguientes:

1. Una arquitectura de herramientas en capas: En lugar de exponer cientos de herramientas independientes, agrupamos capacidades relacionadas en herramientas de dominio más amplias con acciones tipadas y componibles en su interior. Esto dio a los agentes un mapa más estructurado y navegable de la superficie del producto, manteniendo el espacio de herramientas de alto nivel manejable.
2. Introducción de abstracciones del sistema de archivos con representaciones de código de los proyectos de Webflow: Los agentes podían operar sobre una representación estructurada del proyecto utilizando flujos de trabajo familiares de programación y tipo shell. Esto desplazó parte del modelo de interacción de la orquestación de API hacia entornos de ejecución y manipulación basada en código.

Lanzamiento y escalado de nuestro servidor MCP

Una de las lecciones que aprendimos fue que diseñar API para agentes va más allá de la propia superficie de la API. Una vez que los agentes se convirtieron en participantes activos en flujos de trabajo de larga duración, muchas decisiones del sistema circundante comenzaron a afectar directamente la calidad de la ejecución: la arquitectura de sesiones, la organización de herramientas, la coordinación en tiempo de ejecución, la observabilidad e incluso la distribución.

En la práctica, crear sistemas de agentes fiables se convirtió en un problema de diseño full-stack. Esto definió cómo abordamos el servidor MCP de Webflow en cuatro áreas:

• infraestructura para la ejecución con estado y la coordinación en tiempo de ejecución
• diseño de la interfaz de herramientas para mayor claridad y descubrimiento eficiente de capacidades
• sistemas de observabilidad para comprender el comportamiento real de los agentes
• patrones de distribución que redujeron la fricción en la configuración y escalaron la adopción

1. Infraestructura

Los requisitos de infraestructura para un servidor MCP resultaron ser muy distintos a los de un servicio API tradicional. Aunque MCP en sí no requiere un estado del lado del servidor, los flujos de trabajo de los agentes en el mundo real son altamente dependientes del estado. Un agente puede autenticarse una vez, inspeccionar el contexto del sitio, llamar a múltiples herramientas en diferentes superficies del producto y continuar razonando a través de un flujo de trabajo de larga duración. Tratar cada interacción como algo totalmente sin estado obligaría al modelo a reconstruir repetidamente el contexto y el estado de ejecución, lo que aumentaría tanto la latencia como la probabilidad de error.

Construimos el servidor MCP de Webflow en Cloudflare utilizando Durable Objects porque proporcionaban un modelo de ejecución orientado a sesiones muy natural. Cada sesión de MCP posee su propia instancia de servidor, gestionando el contexto del usuario, las herramientas disponibles y la coordinación en tiempo de ejecución sin necesidad de una infraestructura de sesión independiente.

También tuvimos que dar soporte a dos entornos de ejecución diferentes. Algunas operaciones se ejecutan de forma autónoma (headless) a través de las API de Webflow, mientras que las acciones del Diseñador —como insertar elementos o actualizar estilos— dependen del lienzo del navegador en tiempo real. Para esos flujos de trabajo, el servidor MCP mantiene un puente WebSocket con una extensión del Diseñador que se ejecuta dentro de la sesión activa de Webflow del usuario.

Esta arquitectura ofrece a los agentes una superficie MCP unificada, al tiempo que permite al sistema dirigir las operaciones al entorno de ejecución correcto entre bastidores. Al mismo tiempo, hemos ido trasladando progresivamente más capacidades del Diseñador a API autónomas. Reducir la dependencia de la ejecución en el navegador simplifica la arquitectura de tiempo de ejecución, disminuye la complejidad de la coordinación y mejora la estabilidad y fiabilidad generales de los flujos de trabajo de los agentes.

2. Diseño de la superficie de herramientas

Como mencionamos anteriormente, encontramos dos enfoques distintos que ayudan a reducir la sobrecarga de orquestación y descubrimiento para los agentes: la organización de herramientas por capas y las abstracciones de sistemas de archivos con representaciones en código de los proyectos de Webflow. Con el tiempo, empezamos a verlos como soluciones a corto y largo plazo para el mismo problema subyacente.

A corto plazo, la arquitectura de herramientas por capas ayuda a medida que la superficie MCP se expande, ya que ofrecemos a los agentes un mapa mejor en lugar de exponer todas las herramientas al mismo tiempo. En lugar de exponer cada tarea como una herramienta MCP independiente, agrupamos las capacidades relacionadas en herramientas a nivel de dominio con acciones tipadas y componibles en su interior. Por ejemplo, las operaciones de CMS se agrupan bajo una superficie de herramientas compartida para colecciones, campos, elementos, publicación y actualizaciones, mientras que las capacidades del Diseñador se organizan en torno a elementos, estilos, variables, activos y componentes.

Más concretamente, la superficie de herramientas evolucionó en varias capas:

• Herramientas de dominio organizan áreas amplias del producto
• Acciones proporcionan primitivas tipadas y componibles dentro de cada dominio
• Herramientas de flujo de trabajo encapsulan tareas con gran carga de orquestación
• Herramientas de guía proporcionan instrucciones operativas y contexto del producto para una ejecución más segura

Aunque este enfoque ayudó sin duda a mitigar los problemas de la superficie de herramientas y la orquestación, no elimina el problema de raíz. A medida que las capacidades del producto se expanden, el número de flujos de trabajo y acciones válidas puede seguir creciendo rápidamente, incluso dentro de una arquitectura por capas. En cierto punto, el desafío pasa de simplemente organizar las herramientas a reducir por completo la dependencia del sistema del descubrimiento explícito de herramientas. Incluso las jerarquías de herramientas bien estructuradas siguen requiriendo que el modelo busque, seleccione capacidades, interprete esquemas y coordine la ejecución a través de las API.

Aquí es donde las abstracciones al estilo de un sistema de archivos y los entornos orientados al código cobran cada vez más importancia. En lugar de forzar cada interacción mediante la invocación explícita de herramientas MCP, los agentes pueden operar sobre una representación estructurada del proyecto, más parecida a un espacio de trabajo programable. Anthropic y Cloudflare han debatido direcciones similares en trabajos recientes sobre infraestructura de agentes. Consulta el siguiente ejemplo para una tarea de actualización de la página de inicio con el modo de código:

// agent edits your site as code
read src/pages/home.tsx
write src/components/Hero.tsx
write src/styles/theme.css

Esto se adapta mucho mejor a las fortalezas actuales de los LLM. Los modelos ya son altamente eficaces razonando sobre texto estructurado, generando código, editando archivos y operando dentro de entornos de ejecución. Al cambiar el modelo de interacción de la orquestación de API hacia la manipulación de estados estructurados, el sistema reduce la sobrecarga de descubrimiento, el consumo de contexto y la carga de coordinación en múltiples pasos.

La lección más profunda es que escalar los sistemas de agentes no consiste solo en añadir más herramientas. Se trata de ofrecer a los modelos un entorno operativo más navegable y eficiente.

3. Observabilidad

La observabilidad se volvió mucho más importante una vez que los agentes comenzaron a operar de forma autónoma en flujos de trabajo de larga duración.

Los registros y seguimientos tradicionales eran útiles para la depuración de la infraestructura: podían decirnos qué solicitudes fallaron, los patrones de latencia o las excepciones del lado del servidor. Pero eran poco adecuados para comprender el comportamiento de los agentes. No nos decían qué intentaba lograr realmente el agente, qué capacidades esperaba que existieran, dónde se volvían confusos los flujos de trabajo o por qué sesiones aparentemente "exitosas" seguían produciendo resultados deficientes.

Para cerrar esa brecha, integramos MCPCat como una capa de observabilidad alrededor del propio servidor MCP. Al envolver el servidor durante la inicialización, captura llamadas a herramientas, lecturas de recursos, intentos de uso de herramientas inexistentes, metadatos de sesión y patrones de respuesta a lo largo de todo el flujo de ejecución. La señal más valiosa resultó ser la intención.

Los intentos de herramientas faltantes revelaron capacidades o patrones de nombres que los agentes esperaban pero no pudieron encontrar. La reproducción de sesiones sacó a la luz flujos de trabajo degradados en los que el modelo exploraba, reintentaba o cambiaba de dirección repetidamente sin llegar a producir un error crítico. En muchos casos, el sistema parecía saludable desde una perspectiva de infraestructura, mientras que la experiencia del agente seguía fallando silenciosamente.

Inicialmente esperábamos que la migración de CMS y la gestión de contenido dominaran el uso. En cambio, los Objetivos del Agente mostraron que diseñar directamente en el lienzo de Webflow a través de agentes de terceros representó el 27,7% de las sesiones. También descubrimos un error silencioso que afectaba a más del 10% de las sesiones y hallamos que el 58,7% de las sesiones se agrupaban en torno a tres flujos de trabajo principales.

Con el tiempo, nos dimos cuenta de que la observabilidad para los sistemas de agentes es fundamentalmente diferente de la observabilidad para las API. El objetivo no es solo entender si las solicitudes tuvieron éxito, sino comprender cómo los modelos razonan, exploran capacidades, se recuperan de la ambigüedad y fallan durante la ejecución.

4. Escalado de la distribución

El escalado de la distribución para un servidor MCP no consistía solo en gestionar más tráfico. Se trataba de reducir la fricción de adopción, ampliar los lugares donde los agentes podían usar Webflow y mejorar la calidad de los flujos de trabajo que esos agentes podían realizar.

La adopción se aceleró después de que lanzamos un conector MCP alojado a principios de 2026, comenzando con Claude, lo que redujo significativamente la fricción de configuración para los usuarios. En lugar de configurar manualmente las conexiones MCP y los flujos de autenticación, los usuarios podían conectarse a Webflow a través de una integración alojada y gestionada con mucha menos carga operativa. Hemos observado un crecimiento de 6,7 veces en las sesiones durante los últimos 3 meses.

Escalar la adopción también dejó clara una cosa: los agentes necesitan algo más que herramientas. Las herramientas exponen lo que un agente puede hacer; las habilidades codifican cómo hacerlo bien. Para Webflow, muchos resultados exitosos requieren criterio de producto, flujos de trabajo reutilizables y convenciones de dominio, no solo acceso a la API. Incorporar habilidades más útiles a la experiencia MCP de Webflow, como patrones de diseño, manuales de migración de CMS, flujos de trabajo de SEO, comprobaciones de accesibilidad y orientación sobre sistemas de marca, se vuelve fundamental a medida que los agentes pasan de simples llamadas a herramientas a un trabajo integral en el sitio.

A medida que aumentaba la adopción, los desafíos pasaron de la mecánica del protocolo a la experiencia de producto para sistemas autónomos: ofrecer un contexto de sitio más rico, ampliar la capa de habilidades y comprender si las acciones de los agentes realmente ayudaban a los usuarios a lograr resultados significativos.

Resumen

Los agentes no son solo otro cliente de API. Son un tipo diferente de participante en tiempo de ejecución: uno que razona a través del contexto, explora capacidades de forma dinámica, aprende de la estructura de la interfaz y depende del sistema para que la siguiente acción correcta sea descubrible y confiable.

Diseñar para ese tipo de usuario cambia mucho más que las API. Afecta a cómo estructuramos las herramientas, gestionamos la orquestación, exponemos el contexto, construimos entornos de ejecución, observamos los flujos de trabajo e incluso cómo se modelan las propias superficies del producto. Con el tiempo, nos encontramos diseñando no solo interfaces MCP, sino entornos operativos completos para sistemas autónomos.

Eso nos empujó hacia arquitecturas de herramientas en capas, abstracciones de flujo de trabajo, representaciones de proyectos al estilo de un sistema de archivos, una observabilidad más rica y capas de habilidades. El objetivo nunca fue simplemente exponer más capacidades a los agentes. Era ayudar a los modelos a tomar decisiones correctas con menos exploración, menos carga de orquestación y una mayor fiabilidad en la ejecución.

El trabajo que tenemos por delante no es solo hacer que Webflow sea programable para los agentes. Es hacer que Webflow sea legible, navegable y operativamente confiable para los sistemas autónomos sin perder la flexibilidad que hace que la plataforma sea poderosa para los humanos. Ese es tanto un desafío profundo de producto como un desafío de sistemas, y es exactamente el tipo de problema que nos entusiasma resolver en Webflow.