Una publicación de Show HN titulada "Ableton Live MCP" alcanzó 118 puntos y 78 comentarios a principios de esta semana. El patrón ya es familiar: alguien escribió un servidor de Protocolo de Contexto de Modelo (MCP) para una herramienta poco probable, a la comunidad de Claude Desktop le encantó, y le siguió una ola de publicaciones tipo "¿debería escribir uno para X?". El MCP pasó de ser un experimento exclusivo de Anthropic a una capa de integración de agentes predeterminada en menos de un año.
Lo que ese crecimiento oculta es un vacío en las herramientas: nadie ha implementado una forma limpia de probar servidores MCP. Ejecutar JSON-RPC sobre stdio a mano con un depurador está bien para un "hola mundo"; se desmorona en el momento en que su servidor tiene 12 herramientas, 3 prompts y una API ascendente inestable. Esta guía le ofrece un manual práctico para probar servidores MCP manualmente y automatizar esas pruebas con Apidog, para que pueda implementar servidores MCP de la misma manera que implementaría cualquier otra API: con un contrato, un mock y un conjunto de regresión.
Si viene de un contexto de agente más general, nuestra guía agents.md combina bien con esto; las convenciones allí facilitan la comunicación de los contratos de servidores MCP a su equipo.
TL;DR
- MCP es el Protocolo de Contexto de Modelo de Anthropic; es JSON-RPC 2.0 sobre stdio o HTTP y expone tres primitivas: herramientas, recursos y prompts.
- Probar un servidor MCP significa verificar sus respuestas
initialize,tools/list,tools/call,resources/readyprompts/getcontra un contrato. - Comience manualmente: ejecute el servidor desde la línea de comandos con stdio, confirme las respuestas visualmente y corrija los errores de forma antes de agregar clientes.
- Pase a la automatización: capture el tráfico JSON-RPC en Apidog, convierta cada llamada en una solicitud guardada, construya aserciones sobre la forma y el contenido de la respuesta, y ejecute el conjunto en CI.
- Use el servidor de mocks de Apidog para simular las API ascendentes a las que llama su servidor MCP, para que las pruebas sigan siendo deterministas.
- Descargue Apidog para obtener la colección de solicitudes, el servidor de mocks y el ejecutor de CI en un solo lugar.
Qué es realmente MCP, en dos minutos
La especificación del Protocolo de Contexto de Modelo define un formato de cable JSON-RPC 2.0 con una superficie pequeña. Un cliente (Claude Desktop, Cursor, su propio agente) inicia un servidor MCP, realiza un handshake initialize y luego emite llamadas.
Las cinco llamadas en las que pasará el 90 por ciento de su tiempo probando:
initialize: negociación de versiones y divulgación de capacidades.tools/list: el servidor devuelve las herramientas que expone, incluyendo JSON Schema para los argumentos.tools/call: el cliente invoca una herramienta por nombre con argumentos.resources/listyresources/read: el servidor expone contenido direccionable por URI legible.prompts/listyprompts/get: el servidor expone plantillas de prompts que el cliente puede renderizar.
El transporte es stdio (tramas JSON-RPC delimitadas por nueva línea en stdin/stdout) o HTTP transmitible (típicamente POST / con SSE para streaming). La mayoría de los servidores locales usan stdio; los servidores remotos usan HTTP.
Por qué las pruebas importan: cada usuario de Claude Desktop, cada usuario de Cursor, cada IDE que agregue soporte MCP va a llamar a su servidor. Los errores en la forma de tools/list rompen todos los clientes a la vez. El costo de una regresión es alto.
Qué debería estar probando
Un conjunto de pruebas de servidor MCP sólido cubre seis dimensiones.
Conformidad del protocolo. ¿initialize devuelve el protocolVersion correcto? ¿El servidor anuncia las capacidades que realmente soporta?
Corrección del esquema. ¿Cada herramienta en tools/list tiene un JSON Schema válido para los argumentos? ¿Los campos requeridos están marcados? ¿La descripción tiene más de tres palabras? Las descripciones vacías rompen la selección de herramientas en Claude.
Comportamiento de la herramienta. Para cada herramienta, ¿tools/call devuelve bloques de contenido del tipo correcto (text, image, resource)? ¿Los casos de error devuelven un resultado isError: true en lugar de lanzar errores JSON-RPC?
Acceso a recursos. ¿Los URI de resources/list se resuelven cuando se llaman a través de resources/read? ¿La paginación funciona más allá de la primera página?
Renderizado de prompts. ¿Los prompts devuelven arrays de messages bien formados? ¿Las sustituciones de argumentos aterrizan en los lugares correctos?
Modos de fallo. ¿Qué sucede cuando una API ascendente está caída? ¿Cuando falta un argumento de herramienta? ¿Cuando el cliente agota el tiempo de espera? Estos son los errores que aparecen en producción, no en el "hola mundo".
El resto de esta guía recorre cada uno de estos, primero manualmente, luego automatizado.
Pruebas manuales con stdio
Comience con la configuración más simple posible: una terminal, su binario de servidor y el inspector de MCP o JSON-RPC sin procesar a mano.
Si aún no ha construido un servidor, cree uno con el inicio rápido oficial del SDK de MCP en Python o TypeScript. El ejemplo de clima de dos herramientas es suficiente para probar.
Ejecute el servidor en modo inspector:
npx @modelcontextprotocol/inspector node your-server.js
El inspector inicia una interfaz de usuario web local que se comunica con su servidor a través de MCP y le muestra cada solicitud y respuesta. Esta es la forma más rápida de confirmar que el servidor se inicia, anuncia capacidades y responde a tools/list.
Una vez que la vista del inspector se vea correcta, ejecute el mismo flujo con stdio sin procesar para que pueda capturar tramas para Apidog:
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2026-04-01","capabilities":{}}}' | node your-server.js
Obtendrá una respuesta JSON-RPC en la salida estándar. Guarde la solicitud y la respuesta. Repita para tools/list, tools/call, resources/list y el resto. Al final de este ejercicio, tendrá de 6 a 12 pares canónicos de solicitud-respuesta que definen el contrato a nivel de cable de su servidor.
Dos cosas a tener en cuenta.
Primero, bloques de contenido. Un resultado de herramienta devuelve content: [{ type: "text", text: "..." }] o content: [{ type: "image", data: "...", mimeType: "image/png" }]. Se permite mezclar tipos en una respuesta; los clientes difieren en cómo los renderizan.
Segundo, errores. La especificación MCP es clara: los errores de ejecución de herramientas devuelven un resultado normal con isError: true y un bloque de contenido que describe el fallo. No lance respuestas de error JSON-RPC desde dentro de una herramienta; eso señala un fallo a nivel de protocolo, no a nivel de herramienta. Muchos clientes cierran la conexión ante errores de protocolo.
De manual a automatizado: construyendo el conjunto de pruebas en Apidog
Las pruebas manuales sacan a la luz los errores obvios. Se pasa a la automatización cuando se empieza a preguntar "¿mi último cambio rompió el esquema de argumentos de la herramienta 7?" y no se quieren escribir 12 comandos curl para averiguarlo.
El patrón: tome cada par de solicitud-respuesta que guardó durante las pruebas manuales, péguelo en Apidog como una solicitud guardada, agregue aserciones y ejecute el conjunto en cada push.
1. Cree un proyecto de Apidog para el servidor MCP
Abra Apidog, cree un nuevo proyecto, establezca la URL base en el endpoint HTTP de su servidor MCP (o la URL del puente stdio; vea abajo). Los proyectos de Apidog soportan tanto REST como JSON-RPC; cree un entorno JSON-RPC.
Para servidores stdio que no tienen una interfaz HTTP, ejecútelos detrás de un ligero wrapper HTTP para las pruebas. El inspector oficial incluye uno; alternativamente, un script Node de 30 líneas que lee JSON-RPC sobre HTTP y lo reenvía a stdio funciona bien. Usamos el mismo patrón en pruebas de API sin Postman en 2026 para backends no HTTP.
2. Guarde las solicitudes canónicas
Para cada una de initialize, tools/list, tools/call, resources/list, resources/read, prompts/list, prompts/get, guarde el cuerpo JSON-RPC como una solicitud. Apidog las almacena con el cuerpo, las cabeceras y el estado esperado.
Una solicitud tools/call se ve así en la vista del cuerpo de la solicitud de Apidog:
{
"jsonrpc": "2.0",
"id": 42,
"method": "tools/call",
"params": {
"name": "get_weather",
"arguments": {
"city": "Tokyo"
}
}
}
3. Agregue aserciones
El objetivo de la automatización es afirmar sobre la respuesta, no enviar la solicitud. Apidog admite aserciones JSONPath de forma nativa. Para tools/list, al menos querrá:
$.result.toolsexiste$.result.tools.lengthes mayor que cero- Cada herramienta tiene
name,descriptioneinputSchema - Cada
inputSchemaes un JSON Schema válido
Para tools/call con una entrada conocida buena querrá:
$.result.isErrores falso (o ausente)$.result.contentes un array- El primer bloque de contenido tiene el
typey el contenido esperados
Para tools/call con una entrada conocida mala (argumento requerido faltante) querrá:
$.result.isErrores verdadero$.result.content[0].textcoincide con su mensaje de error esperado
Apidog almacena estas aserciones por solicitud. Los fallos se muestran en el informe de ejecución.
4. Simule las API ascendentes (Mock)
La mayoría de los servidores MCP envuelven una API externa: datos meteorológicos, GitHub, Linear, una base de datos interna. No querrá que las ejecuciones de CI golpeen las API en vivo en cada commit. Dos razones: costo e inestabilidad.
El servidor de mocks incorporado de Apidog soluciona esto. Defina cada endpoint ascendente como una ruta simulada que devuelve un cuerpo JSON realista. Apunte la configuración de su servidor MCP a la URL del mock durante las pruebas y a la producción durante las ejecuciones reales. Cubrimos el flujo de trabajo de mocks en detalle en desarrollo de API contract-first.
El resultado: un conjunto de pruebas que se ejecuta en segundos, no requiere red externa y detecta regresiones de esquema mucho antes de que se implementen.
5. Ejecute el conjunto en CI
Los proyectos de Apidog se exportan a ejecutores de CLI. El comando apidog run toma una ID de proyecto, ejecuta cada solicitud guardada, evalúa las aserciones y sale con un código distinto de cero si falla. Conéctelo a sus Acciones de GitHub o a cualquier proveedor de CI que ya utilice.
Un flujo de trabajo mínimo:
name: MCP server tests
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: 22 }
- run: npm ci
- name: Start MCP HTTP wrapper
run: node test/wrapper.js &
- name: Run Apidog suite
run: npx apidog run --project-id $APIDOG_PROJECT --env ci
env:
APIDOG_PROJECT: ${{ secrets.APIDOG_PROJECT }}
APIDOG_TOKEN: ${{ secrets.APIDOG_TOKEN }}
Cada push ejecuta el contrato MCP completo. La regresión del esquema de la herramienta 7 no puede pasar sin ser detectada.
Cómo se ve una buena cobertura de pruebas
Un plan de pruebas completo para un servidor MCP en Apidog suele incluir:
- 1 solicitud
initializecon aserciones de capacidad - 1 solicitud
tools/listcon aserciones de forma y JSON Schema - De 2 a 4 solicitudes
tools/callpor herramienta: ruta feliz, argumento faltante, tipo inválido, error ascendente - 1
resources/listmás 1resources/readpor familia de recursos - 1
prompts/listmás 1prompts/getpor plantilla de prompt
Para un servidor de 10 herramientas con 3 recursos y 4 prompts, el conjunto realiza de 50 a 70 solicitudes. Apidog lo ejecuta localmente en menos de 10 segundos con el servidor de mocks caliente.
Errores comunes al probar servidores MCP
Estos son los patrones que vemos con mayor frecuencia.
Saltarse el viaje de ida y vuelta de initialize. Varios servidores fallan en tools/list si nunca se llamó a initialize porque construyen de forma perezosa su registro de herramientas dentro del handshake. Siempre ejecute initialize primero.
Afirmar sobre cadenas de error sin procesar. Los mensajes de error de la herramienta cambiarán. Afirme sobre isError: true y sobre un código de error estable o una expresión regular, no sobre coincidencias de cadena exactas.
Dejar que el mock se desvíe de la producción. Un mock que devuelve formas que la API real nunca devuelve le da pruebas verdes en una integración rota. Vuelva a grabar los fixtures del mock a partir de respuestas reales en cada lanzamiento.
Olvidarse del streaming. Los servidores MCP HTTP transmiten los resultados de las herramientas a través de SSE. Su ejecutor de pruebas debe manejar SSE; Apidog lo hace, pero debe habilitar el streaming en la solicitud.
No probar la concurrencia. Los clientes MCP envían solicitudes tools/call concurrentes en bucles de agente. Si su servidor mantiene un estado compartido sin bloqueos, las pruebas de una sola solicitud pasarán y la producción se romperá. Agregue una prueba de ejecución paralela al conjunto.
Confundir errores de protocolo con errores de herramienta. La especificación MCP los separa a propósito; mezclarlos hace que Claude Desktop cierre la conexión. Cubrimos el mismo tipo de error de contrato en desarrollo contract-first de plataforma API.
Casos de uso reales
Un equipo que construía un servidor MCP interno para la API de gestión de incidentes de su empresa detectó tres regresiones en una semana usando aserciones de Apidog sobre la forma de tools/list. Sin la prueba, los errores se habrían enviado a todos los ingenieros que usaban Claude Desktop simultáneamente.
Un desarrollador individual que publica un servidor MCP de código abierto para Notion utiliza los mocks de Apidog para ejecutar el conjunto de pruebas sin alcanzar los límites de velocidad de Notion durante CI. Su conjunto se ejecuta en cada PR, tarda 8 segundos y almacena en caché los fixtures de mock de Apidog en el repositorio para que los colaboradores no necesiten acceso a la API para desarrollar.
Un equipo de plataforma que ejecuta 14 servidores MCP internos creó un espacio de trabajo compartido de Apidog donde reside el contrato de cada servidor. Los nuevos servidores heredan un conjunto de pruebas base; los revisores pueden comparar las diferencias de esquema lado a lado antes de fusionar. El equipo informa de dos interrupciones prevenidas en el primer trimestre, ambas detectadas por aserciones de forma de tools/list en un PR que habría enviado un argumento renombrado a cada usuario de Claude Desktop dentro de la empresa.
Un segundo equipo que construye un servidor MCP para una plataforma de observabilidad interna utiliza el selector de entorno de Apidog para ejecutar el mismo conjunto contra staging y producción. Cada entorno apunta a un archivo de fixture de mock diferente, por lo que las mismas 60 aserciones confirman ambas implementaciones sin reescribir una sola solicitud.
Conclusión
MCP se volvió popular este año, pero la historia de las pruebas todavía es donde estaban las pruebas de API REST hace una década: ad hoc, manual, frágil. No tiene que esperar a que el ecosistema se ponga al día. Trate su servidor MCP como la API que es, diseñe un contrato, simule los sistemas ascendentes y ejecute aserciones en CI.
Cinco puntos clave:
- Un servidor MCP es una API JSON-RPC; pruébelo con el mismo rigor que una API REST.
- Comience manualmente con el inspector oficial, luego capture solicitudes canónicas y pase a la automatización.
- Apidog maneja JSON-RPC, aserciones, mocks y CI en un solo proyecto.
- Cubra las seis dimensiones: conformidad del protocolo, corrección del esquema, comportamiento de la herramienta, acceso a recursos, renderizado de prompts y modos de fallo.
- Simule API ascendentes en Apidog para que el conjunto de pruebas se mantenga rápido y determinista.
Siguiente paso: abra Apidog, cree un proyecto, pegue los cuerpos de solicitud que capturó manualmente, agregue aserciones JSONPath para tools/list y ejecute el conjunto. Sabrá en una hora si el contrato de su servidor es lo suficientemente sólido como para ser enviado.
Preguntas frecuentes
¿Qué es MCP?
MCP, el Protocolo de Contexto de Modelo, es la especificación abierta de Anthropic sobre cómo los clientes de IA (como Claude Desktop) llaman a herramientas, recursos y prompts externos. Es JSON-RPC 2.0 sobre stdio o HTTP transmitible. La especificación completa de MCP se publica en modelcontextprotocol.io.
¿Puedo probar un servidor MCP sin un wrapper HTTP?
Sí. El inspector oficial de MCP se comunica directamente con stdio y le proporciona una interfaz de usuario para pruebas manuales. Para pruebas automatizadas en Apidog, envuelva stdio en un servidor HTTP ligero durante CI; el tráfico de producción aún se realiza a través de stdio.
¿Cómo simulo las API ascendentes a las que llama mi servidor MCP?
Defina cada endpoint ascendente como un mock en su proyecto Apidog, apunte la configuración del servidor MCP a la URL del mock durante las pruebas y cambie a las URL de producción en tiempo de ejecución. Recorremos el mismo patrón en herramientas de prueba de API para ingenieros de control de calidad.
¿Qué pasa con los resultados de las herramientas de streaming?
Los servidores HTTP MCP transmiten los resultados de las herramientas a través de Server-Sent Events (SSE). Apidog admite SSE en solicitudes guardadas; actívelo en la configuración de la solicitud y afirme sobre el flujo ensamblado.
¿Debo probar la versión del protocolo?
Sí. Fije el protocolVersion que admite en initialize y afirme contra él. Las discrepancias causan incompatibilidad silenciosa con el cliente.
¿Puedo probar mi servidor MCP con Claude Desktop real?
Sí, y debería hacerlo al menos una vez antes de cada lanzamiento. Pero no confíe en Claude Desktop como su bucle de prueba; es lento, manual y no determinista. Use Apidog para el conjunto de regresión y Claude Desktop para la prueba de humo.
¿Dónde puedo ver ejemplos reales de servidores MCP?
El repositorio oficial de servidores MCP tiene implementaciones de referencia para sistemas de archivos, GitHub, Slack, Postgres y docenas más. Lea las definiciones de las herramientas; son la forma más sencilla de entender cómo debe ser una buena forma de MCP.