Guía para Pruebas de Servidor MCP: Manuales y Automatizadas con Apidog

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, la comunidad de Claude Desktop lo probó y aparecieron más preguntas del tipo “¿debería escribir uno para X?”. MCP pasó de ser un experimento de Anthropic a una capa de integración de agentes en menos de un año.

Prueba Apidog hoy

Ese crecimiento deja un problema práctico: probar servidores MCP sigue siendo incómodo. Ejecutar JSON-RPC sobre stdio a mano funciona para un “hola mundo”, pero se rompe cuando el servidor tiene 12 herramientas, 3 prompts y una API ascendente inestable. Esta guía muestra cómo probar servidores MCP manualmente y cómo automatizar esas pruebas con Apidog, tratando el servidor como cualquier otra API: con contrato, mocks y regresión en CI.

Si viene de un contexto de agentes más general, nuestra guía agents.md combina bien con esto; las convenciones allí facilitan comunicar contratos de servidores MCP dentro del equipo.

TL;DR

• MCP es el Protocolo de Contexto de Modelo de Anthropic. Usa JSON-RPC 2.0 sobre stdio o HTTP y expone herramientas, recursos y prompts.
• Probar un servidor MCP implica verificar llamadas como initialize, tools/list, tools/call, resources/read y prompts/get.
• Empiece manualmente: ejecute el servidor desde la terminal, confirme respuestas y corrija errores de forma.
• Automatice después: capture tráfico JSON-RPC en Apidog, guarde cada llamada, añada aserciones y ejecute el conjunto en CI.
• Use mocks de Apidog para simular APIs ascendentes y mantener pruebas deterministas.
• Descargue Apidog para centralizar solicitudes, mocks y ejecución de pruebas.

Qué es MCP realmente

La especificación del Protocolo de Contexto de Modelo define una interfaz JSON-RPC 2.0. Un cliente, como Claude Desktop, Cursor o un agente propio, inicia un servidor MCP, ejecuta un handshake initialize y luego envía llamadas.

Las llamadas que más debería probar son:

• initialize: negocia versión y capacidades.
• tools/list: devuelve herramientas disponibles y sus argumentos mediante JSON Schema.
• tools/call: invoca una herramienta por nombre.
• resources/list y resources/read: exponen contenido direccionable por URI.
• prompts/list y prompts/get: exponen plantillas de prompts renderizables.

El transporte puede ser:

• stdio: tramas JSON-RPC delimitadas por nueva línea en stdin/stdout.
• HTTP transmitible: normalmente POST / con SSE para streaming.

La mayoría de servidores locales usan stdio; los remotos suelen usar HTTP.

El motivo para probarlo bien es simple: si tools/list cambia de forma o devuelve un esquema inválido, todos los clientes MCP pueden romperse al mismo tiempo.

Qué debería probar en un servidor MCP

Un conjunto de pruebas útil cubre seis áreas.

1. Conformidad del protocolo

Verifique que initialize devuelve el protocolVersion esperado y que las capacidades anunciadas coinciden con lo que el servidor soporta.

Ejemplo de aspectos a validar:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2026-04-01",
    "capabilities": {}
  }
}

2. Corrección del esquema

Para cada herramienta en tools/list, valide que exista:

• name
• description
• inputSchema

También confirme que inputSchema sea JSON Schema válido y que los campos requeridos estén definidos correctamente.

Las descripciones vacías o demasiado genéricas dificultan la selección de herramientas por parte de clientes como Claude.

3. Comportamiento de herramientas

Para cada tools/call, valide que la respuesta tenga bloques de contenido correctos:

{
  "content": [
    {
      "type": "text",
      "text": "Resultado"
    }
  ]
}

También pruebe errores esperados. En MCP, un fallo de ejecución de herramienta debería devolver un resultado normal con isError: true, no un error JSON-RPC de protocolo.

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Falta el argumento requerido: city"
    }
  ]
}

4. Acceso a recursos

Compruebe que cada URI devuelta por resources/list se puede leer con resources/read.

También pruebe paginación si su servidor devuelve recursos en varias páginas.

5. Renderizado de prompts

Valide que prompts/get devuelve arrays messages bien formados y que los argumentos se sustituyen en el lugar correcto.

6. Modos de fallo

Pruebe escenarios que ocurren en producción:

• API ascendente caída.
• Argumento requerido ausente.
• Tipo de argumento inválido.
• Timeout.
• Respuestas incompletas.
• Errores concurrentes.

Pruebas manuales con stdio

Empiece con la ruta más simple: terminal, binario del servidor y JSON-RPC.

Si todavía no tiene un servidor, puede crear uno con el inicio rápido oficial del SDK de MCP en Python o TypeScript. El ejemplo de clima con dos herramientas es suficiente para practicar.

Ejecute el servidor con el inspector oficial:

npx @modelcontextprotocol/inspector node your-server.js

El inspector abre una UI local que habla con su servidor vía MCP. Úselo para confirmar:

• El proceso arranca.
• initialize responde.
• Las capacidades se anuncian.
• tools/list devuelve herramientas.
• tools/call responde con contenido válido.

Cuando el flujo funcione en el inspector, capture llamadas JSON-RPC sin procesar.

Ejemplo con stdio:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2026-04-01","capabilities":{}}}' | node your-server.js

Guarde la solicitud y la respuesta. Repita con:

• tools/list
• tools/call
• resources/list
• resources/read
• prompts/list
• prompts/get

Al final tendrá entre 6 y 12 pares solicitud-respuesta que definen el contrato básico de su servidor MCP.

Dos detalles importantes

Primero, los bloques de contenido pueden mezclar tipos:

{
  "content": [
    {
      "type": "text",
      "text": "Resumen"
    },
    {
      "type": "image",
      "data": "...",
      "mimeType": "image/png"
    }
  ]
}

Segundo, no confunda errores de herramienta con errores de protocolo. Si una herramienta falla por un input inválido, devuelva isError: true. Reserve errores JSON-RPC para fallos del protocolo.

De manual a automatizado con Apidog

Las pruebas manuales sirven para encontrar errores obvios. La automatización sirve para responder: “¿mi último cambio rompió el contrato?”.

El flujo recomendado:

1. Capture solicitudes y respuestas MCP.
2. Cree un proyecto en Apidog.
3. Guarde cada llamada JSON-RPC como una solicitud.
4. Añada aserciones.
5. Simule APIs ascendentes con mocks.
6. Ejecute el conjunto en CI.

1. Cree un proyecto de Apidog para su servidor MCP

Abra Apidog y cree un proyecto nuevo.

Si su servidor MCP expone HTTP, configure la URL base del endpoint MCP.

Si su servidor usa solo stdio, ejecútelo detrás de un wrapper HTTP ligero durante pruebas. El inspector oficial incluye opciones para este flujo. También puede crear un script Node que reciba JSON-RPC por HTTP y lo reenvíe al proceso por stdio.

El mismo patrón se usa en pruebas de API sin Postman en 2026 para backends no HTTP.

2. Guarde solicitudes canónicas

Cree una solicitud guardada por cada llamada relevante:

• initialize
• tools/list
• tools/call
• resources/list
• resources/read
• prompts/list
• prompts/get

Ejemplo de cuerpo para tools/call:

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "city": "Tokyo"
    }
  }
}

Mantenga IDs estables en pruebas para facilitar depuración.

3. Añada aserciones

La parte importante no es enviar la solicitud, sino validar la respuesta.

Para tools/list, añada aserciones como:

• $.result.tools existe.
• $.result.tools.length es mayor que 0.
• Cada herramienta tiene name.
• Cada herramienta tiene description.
• Cada herramienta tiene inputSchema.
• Cada inputSchema es válido.

Para tools/call con entrada correcta:

• $.result.isError es false o no existe.
• $.result.content es un array.
• $.result.content[0].type tiene el valor esperado.
• $.result.content[0].text existe si el tipo es text.

Para tools/call con entrada inválida:

• $.result.isError es true.
• $.result.content[0].text contiene un mensaje útil.
• No se devuelve un error JSON-RPC de protocolo si el fallo es de validación de herramienta.

Ejemplo de respuesta esperada para entrada inválida:

{
  "jsonrpc": "2.0",
  "id": 43,
  "result": {
    "isError": true,
    "content": [
      {
        "type": "text",
        "text": "Falta el argumento requerido: city"
      }
    ]
  }
}

Apidog almacena las aserciones por solicitud y muestra los fallos en el reporte de ejecución.

4. Simule APIs ascendentes con mocks

Muchos servidores MCP envuelven APIs externas:

• Clima.
• GitHub.
• Linear.
• Notion.
• Bases de datos internas.
• Servicios internos.

No conviene que CI golpee esas APIs en cada commit. Introduce latencia, límites de uso y fallos no deterministas.

Con el servidor de mocks de Apidog puede definir endpoints ascendentes simulados y devolver respuestas JSON realistas.

Flujo práctico:

1. Defina cada endpoint ascendente como una ruta mock.
2. Configure el servidor MCP para usar la URL del mock en pruebas.
3. Mantenga la URL real solo para staging o producción.
4. Regrabe fixtures cuando la API real cambie.

Este enfoque se cubre también en desarrollo de API contract-first.

Resultado: pruebas rápidas, sin red externa y con fallos reproducibles.

5. Ejecute el conjunto en CI

Los proyectos de Apidog se pueden ejecutar desde CLI. El comando apidog run ejecuta solicitudes guardadas, evalúa aserciones y devuelve un código distinto de cero si algo falla.

Ejemplo mínimo con GitHub Actions:

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 }}

Con esto, cada push ejecuta el contrato MCP completo. Si una herramienta cambia su esquema, CI lo detecta antes del merge.

Cómo se ve una buena cobertura

Un plan de pruebas para un servidor MCP en Apidog suele incluir:

• 1 solicitud initialize con aserciones de versión y capacidades.
• 1 solicitud tools/list con aserciones de forma y JSON Schema.
• De 2 a 4 solicitudes tools/call por herramienta:
  • ruta feliz;
  • argumento faltante;
  • tipo inválido;
  • error ascendente.
• 1 resources/list.
• 1 resources/read por familia de recursos.
• 1 prompts/list.
• 1 prompts/get por plantilla.

Para un servidor con 10 herramientas, 3 recursos y 4 prompts, el conjunto puede tener entre 50 y 70 solicitudes.

Errores comunes al probar MCP

Saltarse initialize

Algunos servidores construyen el registro de herramientas durante initialize. Si ejecuta tools/list directamente, puede obtener falsos negativos.

Ejecute siempre:

1. initialize
2. tools/list
3. llamadas específicas

Afirmar cadenas de error exactas

Los mensajes de error cambian. Es mejor afirmar:

• isError: true
• un código estable, si existe;
• una expresión regular;
• la presencia de campos clave.

Dejar que el mock se desvíe de producción

Un mock incorrecto produce pruebas verdes para una integración rota. Regrabe fixtures a partir de respuestas reales cuando cambie la API ascendente.

Olvidar streaming

Los servidores MCP por HTTP pueden transmitir resultados mediante SSE. Si su endpoint usa streaming, habilítelo en la solicitud de prueba y valide el flujo ensamblado.

No probar concurrencia

Los clientes MCP pueden enviar varias llamadas tools/call en paralelo. Si su servidor comparte estado mutable, una prueba secuencial puede pasar mientras producción falla.

Añada pruebas paralelas para herramientas críticas.

Mezclar errores de protocolo y de herramienta

MCP separa esos errores a propósito. Si una herramienta falla, devuelva isError: true. Si el mensaje JSON-RPC está mal formado, use error de protocolo.

Este tipo de problema de contrato también aparece en desarrollo contract-first de plataforma API.

Casos de uso reales

Un equipo que construía un servidor MCP interno para una API de gestión de incidentes detectó tres regresiones en una semana usando aserciones sobre tools/list. Sin esas pruebas, los errores habrían llegado a todos los usuarios internos de Claude Desktop al mismo tiempo.

Un desarrollador que mantiene un servidor MCP open source para Notion usa mocks de Apidog para ejecutar pruebas sin alcanzar límites de velocidad durante CI. El conjunto se ejecuta en cada PR, tarda pocos segundos y permite colaborar sin acceso directo a la API real.

Un equipo de plataforma con 14 servidores MCP internos creó un workspace compartido en Apidog. Cada contrato vive en el mismo lugar, los servidores nuevos heredan una base de pruebas y los revisores comparan cambios de esquema antes de fusionar.

Otro equipo que construye un servidor MCP para una plataforma interna de observabilidad usa entornos de Apidog para ejecutar el mismo conjunto contra staging y producción. Cambia fixtures y URLs por entorno, pero conserva las mismas aserciones.

Conclusión

MCP creció rápido, pero las pruebas todavía suelen ser manuales y frágiles. La solución es tratar su servidor MCP como una API JSON-RPC: definir contrato, simular dependencias y ejecutar regresión en CI.

Puntos clave:

• Un servidor MCP es una API JSON-RPC; pruébelo con el mismo rigor que una API REST.
• Empiece con el inspector oficial y capture solicitudes canónicas.
• Automatice en Apidog con solicitudes guardadas, aserciones, mocks y CI.
• Cubra protocolo, esquema, herramientas, recursos, prompts y fallos.
• Use mocks para mantener pruebas rápidas y deterministas.

Siguiente paso: abra Apidog, cree un proyecto, pegue las solicitudes MCP capturadas, añada aserciones JSONPath para tools/list y ejecute el conjunto. En menos de una hora sabrá si el contrato de su servidor está listo para enviarse.

Preguntas frecuentes

¿Qué es MCP?

MCP, el Protocolo de Contexto de Modelo, es la especificación abierta de Anthropic para que clientes de IA, como Claude Desktop, llamen herramientas, recursos y prompts externos. Usa JSON-RPC 2.0 sobre stdio o HTTP transmitible. La especificación completa de MCP está publicada en modelcontextprotocol.io.

¿Puedo probar un servidor MCP sin wrapper HTTP?

Sí. El inspector oficial de MCP se comunica directamente con stdio y ofrece una UI para pruebas manuales.

Para automatizar en Apidog, use un wrapper HTTP ligero durante CI. El tráfico de producción puede seguir usando stdio.

¿Cómo simulo APIs ascendentes?

Defina cada endpoint ascendente como un mock en Apidog, configure el servidor MCP para apuntar al mock durante pruebas y cambie a URLs reales en producción. El mismo patrón se explica en herramientas de prueba de API para ingenieros de control de calidad.

¿Qué pasa con resultados de herramientas en streaming?

Los servidores MCP HTTP pueden transmitir resultados mediante Server-Sent Events (SSE). Apidog admite SSE en solicitudes guardadas; actívelo en la configuración de la solicitud y valide el flujo ensamblado.

¿Debo probar la versión del protocolo?

Sí. Fije el protocolVersion soportado en initialize y añada una aserción. Las discrepancias pueden causar incompatibilidades silenciosas con clientes MCP.

¿Puedo probar con Claude Desktop real?

Sí, y debería hacerlo como prueba de humo antes de cada lanzamiento. Pero no lo use como bucle principal de regresión: es manual, lento y no determinista. Use Apidog para automatización y Claude Desktop para validación final.

¿Dónde puedo ver ejemplos reales de servidores MCP?

El repositorio oficial de servidores MCP incluye implementaciones para sistemas de archivos, GitHub, Slack, Postgres y más. Revise sus definiciones de herramientas para entender cómo debería verse una forma MCP bien diseñada.