Esta es una serie de 10 partes que comparte cómo Apidog desarrolló Apidog CLI, una herramienta de línea de comandos para pruebas de API y gestión del ciclo de vida de la API. Lee en orden o salta a cualquier publicación que te interese:
| Título | Enfoque | |
|---|---|---|
| 1 | Construimos 126 Herramientas MCP. Pero no es la Mejor Solución para el Agente | Descubrimiento del problema |
| 2 | Por qué Desarrollamos el Nuevo Apidog CLI | Desarrollo de arquitectura |
| 3 | La Regla de Oro: CLI Produce Hechos, el Modelo Actúa sobre los Hechos | Filosofía central |
| 4 | agentHints: Enseñando a los CLIs a Hablar con los Agentes |
Salida estructurada |
| 5 | HABILIDAD: Entregando Experiencia Operacional como Código | Experiencia operativa |
| 6 | Los Números no Mienten: 30% Menos Llamadas a Herramientas, 25% Menos Tokens | Resultados cuantitativos |
| 7 | De PRD al Bucle de Pruebas: Un Flujo de Trabajo Completo de Agente con Apidog CLI | Tutorial práctico |
| 8 | Por qué la Compatibilidad CI/CD es Innegociable para las Herramientas de Agente | Perspectiva DevOps |
| 9 | Rama de IA: Cambios de Proyecto Más Seguros con Agentes de IA | Capa de seguridad |
| 10 | "Spec-First" Fue Ayer. Bienvenido a "Skill-First". | Visión y futuro |
Cuando MCP se convirtió en el punto caliente de la industria, construimos un Servidor MCP completo con 126 herramientas generadas. Esto es lo que salió mal, y por qué más herramientas no significa una mejor habilitación del Agente.
El "Hype" de MCP
A principios de 2025, MCP (Protocolo de Contexto de Modelo) se convirtió en un punto caliente de la industria.
Anthropic promovió el protocolo. Cursor, Claude Code, Antigravity, varios IDEs de Agentes y numerosos productos SaaS le siguieron rápidamente. El protocolo prometía una forma estandarizada para que los Agentes de IA se conectaran a herramientas externas y fuentes de datos.
Durante ese período, a casi todos los productos con una API se les hizo la misma pregunta:
"¿Tienen MCP?"
Para Apidog, esta elección parecía especialmente natural.
Por qué MCP Parecía la Respuesta
Apidog había acumulado un conjunto completo de capacidades de desarrollo de API:
- Documentación de API
- Definiciones de esquemas
- Servidores mock
- Casos de prueba
- Escenarios de prueba
- Suites de prueba
- Informes de prueba
- Flujos de trabajo de importación/exportación
- Colaboración en ramas
- Y muchos más
Si los Agentes iban a convertirse en el nuevo punto de entrada del software, una nueva forma en que los usuarios interactúan con los productos, entonces exponer estas capacidades a través de MCP parecía una tarea necesaria de cumplir.
Creíamos que si podíamos empaquetar nuestras capacidades como herramientas MCP, los Agentes podrían:
- Consultar documentación de API
- Crear casos de prueba
- Ejecutar escenarios de prueba
- Importar/exportar datos de proyectos
- Gestionar entornos y variables
- Colaborar entre ramas
La lógica era sencilla: más capacidades expuestas = más habilitación del Agente.
Lo que Realmente Construimos
No nos tomamos esto a la ligera.
Apidog MCP no era una simple demostración con un puñado de endpoints escritos a mano. Era un Servidor MCP completo:
Sistema de Sesiones
El cliente MCP primero inicializa una sesión. El servidor genera un sessionId y guarda el estado de la sesión a través de Redis. Las solicitudes posteriores continúan accediendo con el sessionId.
En otras palabras, no era una llamada HTTP única, sino un sistema de sesiones a nivel de protocolo.
Categorías de Herramientas
La capa de herramientas tampoco fue escrita a mano con unos pocos endpoints fijos. Dividimos las herramientas de Apidog en varias categorías:
| Categoría | Descripción | Ejemplos |
|---|---|---|
| Herramientas de proyecto nativas | Construidas para operaciones a nivel de proyecto | Resúmenes de proyectos, estructuras de carpetas, detalles de recursos |
| Herramientas de dominio integradas | Funcionalidad principal de Apidog | Importación/exportación, detalles de endpoints, casos de prueba, escenarios de prueba |
| Herramientas OpenAPI generadas | Convertidas automáticamente a partir de definiciones OpenAPI | 126 herramientas con identificadores únicos, rutas, métodos HTTP, esquemas de entrada |
Esa última categoría: 126 herramientas generadas.
Cada herramienta generada tenía:
- Un identificador único
- Una ruta API específica
- Un método HTTP (GET, POST, PUT, DELETE, etc.)
- Un esquema de entrada completo con descripciones de campos, tipos y valores enum
- Una estructura de retorno definida
Divulgación Progresiva
Para reducir la presión de exposición de las herramientas, también construimos una capa de descubrimiento dinámico:
El Agente podía:
- Primero buscar herramientas de endpoint disponibles (
listOpenApiEndpoints) - Luego obtener los detalles de OpenAPI de una herramienta específica (
getOpenApiDetails) - Finalmente ejecutar la llamada HTTP real por id de herramienta (
executeOpenApi)
Este fue nuestro intento de divulgación progresiva. No expusimos simplemente todos los endpoints subyacentes de forma directa y explícita. Esperábamos que los Agentes buscaran primero, luego obtuvieran detalles y finalmente ejecutaran.
El Muro de Herramientas Aleatorias
Pero al entrar en tareas reales, los problemas surgieron rápidamente.
Consideremos una solicitud de usuario sencilla:
"Ayúdame a añadir una prueba para este endpoint y ejecutar la verificación."
Desde una perspectiva de implementación, esta es una solicitud razonable. Apidog tiene las capacidades para:
- Encontrar endpoints
- Crear casos de prueba
- Ejecutar escenarios de prueba
- Generar informes
Pero desde la perspectiva del Agente, esta simple solicitud en realidad desencadena una serie de juicios continuos:
| Punto de Decisión | Opciones | Incertidumbre |
|---|---|---|
| ¿Dónde empezar? | ¿Encontrar el proyecto primero? ¿Encontrar el endpoint primero? | Sin guía clara |
| ¿Qué leer? | ¿Leer detalles del endpoint? ¿Listar casos de prueba existentes? | Ambos parecen válidos |
| ¿Cómo crear? | ¿Usar createTestCase directamente? ¿Encontrar el grupo de casos primero? |
Requisito desconocido |
| ¿Cómo actualizar? | ¿Llamar directamente a la herramienta update? ¿Importar pasos y luego leer de nuevo? |
Flujo de trabajo oculto |
El Agente no solo necesita encontrar la herramienta adecuada. Necesita resolver el problema de "qué herramienta usar" primero, antes de que pueda empezar a resolver el problema del usuario.
Desde una perspectiva de implementación, todos estos problemas pueden resolverse a través de herramientas. Desde la perspectiva de la experiencia del Agente, forman un muro de herramientas aleatorias.
Los Cuatro Problemas Estructurales
A través de pruebas en el mundo real y retroalimentación interna, identificamos cuatro problemas estructurales con el enfoque MCP.
Problema 1: Los Costos de Descubrimiento de Herramientas Aumentan Rápidamente
Apidog no es un producto que pueda describirse con solo una docena de endpoints.
| Módulo | Desglose |
|---|---|
| Endpoints | Listar, obtener, crear, actualizar, eliminar |
| Esquemas | Listar, obtener, crear, actualizar, eliminar |
| Entornos | Listar, obtener, crear, actualizar, eliminar, variables |
| Mocks | Configurar, habilitar, deshabilitar |
| Casos de prueba | Listar, obtener, crear, actualizar, eliminar, duplicar |
| Escenarios de prueba | Listar, obtener, crear, actualizar, eliminar, importar pasos, ejecutar |
| Suites de prueba | Listar, obtener, crear, actualizar, eliminar |
| Informes | Listar, obtener, generar, descargar |
| Importar/exportar | Múltiples formatos, opciones |
| Ramas | Listar, crear, fusionar, eliminar |
Cuando las herramientas crecen de una docena a decenas o cientos, el Agente necesita resolver el problema de "qué herramienta usar" antes de poder empezar a resolver los problemas del usuario.
Intentamos escribir flujos de trabajo en la description de la herramienta (el campo utilizado para exponer herramientas a los Agentes de IA). Por ejemplo, la descripción de una herramienta declararía explícitamente:
"Antes de consultar los datos de un endpoint, primero debe confirmar el proyecto a través de otra herramienta, luego obtener los metadatos del proyecto a través de una tercera herramienta, y finalmente llamar a la herramienta actual."
Este método funciona en conjuntos de herramientas a pequeña escala. Pero en un muro masivo de herramientas, la propia description compite por la atención del modelo.
Cuanta más guía escribíamos en las descripciones, más tokens se consumían, y menos probable era que el Agente realmente las leyera y siguiera.
Problema 2: El Esquema de Negocio Invade el Contexto
Cada herramienta MCP no es solo un nombre de herramienta.
Detrás de cada herramienta están:
description(lo que hace la herramienta)input schema(parámetros, tipos, requeridos/opcionales)- Explicaciones de campos (estructuras anidadas, restricciones)
- Valores enum (opciones permitidas)
- Estructuras de retorno (formato de respuesta, manejo de errores)
Hagamos una estimación conservadora:
| Factor | Valor |
|---|---|
| Número de herramientas | 100+ |
| Tokens promedio por herramienta | ~500 |
| Tokens totales de descripción de herramientas | ~50,000 |
La pregunta de un usuario podría tener solo 50 caracteres. Pero el modelo se ve obligado a introducir primero 50,000 tokens de descripciones de herramientas, solo para un servidor MCP.
Esto no es teórico. Los datos de la industria lo respaldan.
La publicación oficial del blog de Cursor "Dynamic Context Discovery" proporcionó datos de referencia valiosos: al convertir las descripciones de herramientas MCP, las sesiones de terminal y las conversaciones largas en contexto cargable bajo demanda, el consumo de tokens en tiempo de ejecución se redujo en un 46.9%.
El enfoque de Trae fue más directo: limitar el número de herramientas MCP y la longitud de la descripción de una sola herramienta:
- Límite superior de herramientas: 40
- Límite de descripción de una sola herramienta: 8000 caracteres
De hecho, durante las primeras pruebas internas, muchos equipos informaron que Apidog MCP tenía problemas con algunas herramientas que no podían invocarse en Trae. El Agente se vio obligado a hacer concesiones debido al contexto limitado del modelo, y las herramientas externas fueron las primeras en ser "recortadas".
Todas estas soluciones apuntan al mismo hecho:
Las descripciones de las herramientas no pueden entrar infinitamente en el contexto del modelo.
Problema 3: Las Sesiones de Protocolo Hacen las Cadenas de Ejecución Más Pesadas
El servidor Apidog MCP necesita manejar:
| Estado del Protocolo | Descripción |
|---|---|
| Inicializar MCP | Saludo entre cliente y servidor |
| Generación de sessionId | Identificador único para la sesión |
| Almacenamiento de sesión en Redis | Persistencia del estado |
| Conexión/cierre de transporte | Gestión de conexiones |
| Toque de sesión | Mecanismo de "keep-alive" |
| Eliminar sesión | Limpieza al finalizar |
| Respuesta JSON o configuración SSE | Opciones de formato de salida |
Para una simple llamada a una herramienta, estos costos son aceptables. Para tareas de Agente con grandes números de llamadas y exploración frecuente, estos requisitos de gestión de estado aumentan la complejidad tanto en el lado del servidor como en el del cliente.
Al implementar Apidog MCP, el equipo consumió una energía significativa en la resolución de problemas y la adaptación a diferentes clientes de Agente (Cursor, Claude Code, Antigravity, Trae, etc.). Sin embargo, los problemas de compatibilidad del protocolo persistieron, y el protocolo MCP oficial continuó siendo parcheado con nuevas versiones.
Todas las partes sufrieron enormemente.
Problema 4: Las Herramientas Atómicas no Pueden Expresar Naturalmente la Semántica del Producto
En los escenarios de prueba de Apidog, no es solo una simple expresión de un array de steps.
Un escenario de prueba implica:
| Componente | Complejidad |
|---|---|
| Importar | Pasos de endpoints o casos existentes |
| Lectura de retorno | Obtener la estructura completa después de la importación |
| Casos internos | Solicitudes HTTP incrustadas en los pasos |
| Pre/post procesadores | Scripts antes/después de las solicitudes |
| Aserciones | Reglas de validación de respuesta |
| Extracción de variables | Captura de valores de las respuestas |
| Entorno de ejecución | Selección de entorno, variables |
| Verificación de informe | Comprobación de resultados de prueba |
Después de dividir esto en múltiples herramientas MCP, el Agente todavía tiene que realizar el trabajo de orquestación de pruebas por sí mismo.
Cuanto más atómicas son las herramientas, más necesita el modelo entender la semántica interna del producto:
- ¿Por qué la importación necesita una lectura de retorno?
- ¿Por qué los casos internos tienen diferentes marcadores de actualización?
- ¿Por qué las aserciones requieren comparadores específicos?
- ¿Por qué la extracción de variables tiene restricciones de tipo?
Esto está obviamente más allá del rango de capacidad del modelo.
Obligó al equipo de Apidog a realizar proactivamente ajustes de ingeniería técnica para la semántica interna del producto. Los endpoints atómicos añadieron pasivamente una capa de conversión, solo para adaptarse a una única capa de despacho de herramientas MCP.
Los desafíos de ingeniería y los costos de mantenimiento posterior son indudablemente arduos.
La Causa Raíz
La causa raíz de estos cuatro problemas es la misma:
MCP es mejor para conectar herramientas, pero las tareas complejas de I+D necesitan más que una conexión de herramientas: necesitan procesos de ingeniería ejecutables.
| Fortaleza de MCP | Limitación de MCP |
|---|---|
| Conexión estandarizada | No puede expresar el flujo de trabajo |
| Protocolo unificado | No puede guiar la secuencia |
| Exposición de herramientas | No puede forzar la validación |
| Descubrimiento dinámico | No puede proporcionar juicio |
Para productos simples con una docena de operaciones bien definidas, MCP funciona bien. El Agente puede adivinar razonablemente la herramienta correcta, llamarla y obtener un resultado.
Para productos como Apidog, con docenas de módulos, cientos de operaciones, estructuras anidadas, flujos de trabajo ocultos y semántica específica del producto, MCP por sí solo crea un muro de herramientas aleatorias que los Agentes luchan por navegar.
Lo que Aprendimos
| Lección | Implicación |
|---|---|
| Más herramientas ≠ mejor habilitación del Agente | El número de herramientas es un costo, no un beneficio |
| Las descripciones de las herramientas compiten por el contexto | 500 tokens por herramienta × 100 herramientas = 50,000 tokens de carga |
| Los protocolos de sesión añaden sobrecarga de ejecución | Cada llamada conlleva la gestión del estado del protocolo |
| Las herramientas atómicas requieren conocimiento del producto | Los Agentes deben comprender los internos para orquestar |
| Conexión ≠ ejecución | MCP conecta; CLI + HABILIDAD ejecuta |
El Giro
Esta realización nos llevó a hacer una pregunta diferente:
Si MCP no es la respuesta para la habilitación de agentes, ¿qué lo es?
No abandonamos el valor de MCP: proporciona conexiones estandarizadas, lo cual es importante para el ecosistema. Pero necesitábamos algo que pudiera:
- Expresar flujos de trabajo, no solo herramientas
- Guiar a los Agentes a través de secuencias
- Validar antes de escribir
- Imponer puertas de calidad de ingeniería
- Absorber la complejidad en el sistema
La respuesta a la que llegamos: CLI + HABILIDAD.
En la próxima publicación, Por qué Desarrollamos un Nuevo Apidog CLI, exploraremos el cambio arquitectónico, donde la complejidad se movió del contexto del modelo al sistema de ingeniería, y por qué eso lo cambia todo para la habilitación de Agentes.
Puntos Clave
- MCP se convirtió en la respuesta de la industria a "¿cómo se conectan los Agentes a las herramientas?"
- Construimos 126 herramientas MCP, pensando que más herramientas = mejor habilitación
- Las tareas reales revelaron cuatro problemas estructurales: costos de descubrimiento, invasión del contexto, sobrecarga de sesiones, semántica del producto
- La causa raíz: MCP conecta herramientas, pero las tareas complejas necesitan procesos ejecutables
- Más herramientas es un costo, no un beneficio, cuando las descripciones de las herramientas consumen contexto
Descarga Apidog para diseñar, simular, probar y documentar APIs en un solo espacio de trabajo. Obtén más información sobre Apidog CLI para pruebas de API de línea de comandos, automatización CI y flujos de trabajo de Agentes de IA.