MCP Inspector como servidor MCP

Un servidor MCP ligero que permite a los LLM inspeccionar y probar otros servidores MCP. Esta es una implementación autónoma que utiliza el SDK de MCP directamente, sin depender de CLI externas.

Características

• Integración directa con el SDK: Utiliza @modelcontextprotocol/sdk directamente tanto para operaciones de servidor como de cliente

• Todos los tipos de transporte: Soporta transportes stdio, SSE y HTTP (con streaming)

• Huella mínima: Una sola dependencia (@modelcontextprotocol/sdk)

• Inspección MCP completa: Listar herramientas, llamar a herramientas, listar recursos, leer recursos, listar prompts, obtener prompts

• Gestión de sesiones: Conexiones persistentes con recolección de basura automática

• Almacenamiento en búfer de eventos: Captura notificaciones, tráfico y errores para depuración

Instalación

npm install
npm run build

Uso

Como servidor MCP

Añádelo a tu configuración de MCP. Aunque existen ligeras variaciones entre diferentes implementaciones, el formato general es el mismo:

{
  "mcpServers": {
    "mcp-inspector": {
      "command": "node",
      "args": ["/path/to/mcp-inspector-as-mcp-server/dist/server.js"]
    }
  }
}

Herramientas disponibles

Gestión de sesiones (NUEVO en v2.0)

Herramientas de inspección

Parámetros de conexión

Todas las herramientas aceptan los siguientes parámetros de conexión:

Para transporte stdio (comandos locales):

• command: Comando a ejecutar (ej. "node", "python")

• args: Matriz de argumentos (ej. ["path/to/server.js"])

Para transporte SSE/HTTP (servidores remotos):

• url: URL del servidor (ej. "http://localhost:3000/sse")

• headers: Objeto de cabeceras HTTP opcional

Comunes:

• transport: Fuerza el tipo de transporte ("stdio", "sse" o "http"). Se detecta automáticamente si no se especifica.

• session_id: (Opcional) Utiliza una sesión persistente existente en lugar de crear una conexión efímera.

Flujo de trabajo de sesiones

Para depurar el comportamiento de servidores con estado, utiliza sesiones persistentes:

1. insp_connect → returns session_id
2. insp_tools_list (with session_id) → uses persistent connection
3. insp_tools_call (with session_id) → state is preserved
4. insp_read_events (with session_id) → see notifications
5. insp_disconnect (with session_id) → cleanup

Las sesiones se cierran automáticamente tras 30 minutos de inactividad.

Guía humana y observabilidad

El inspector permite flujos de trabajo human-in-the-loop donde puedes observar y guiar las pruebas MCP impulsadas por LLM en tiempo real.

Cómo funciona

┌─────────────┐     MCP calls      ┌─────────────────┐     forwards     ┌─────────────┐
│   LLM Agent │ ◄────────────────► │  MCP Inspector  │ ◄──────────────► │  Target MCP │
│  (Antigravity)                   │    (v2.0)       │                  │   Server    │
└─────────────┘                    └────────┬────────┘                  └─────────────┘
                                            │
                                   Events logged to
                                   session EventBuffer
                                            │
                    ┌───────────────────────┼───────────────────────┐
                    │                       │                       │
                    ▼                       ▼                       ▼
            insp_read_events         HTTP :9847/api          mcp-steer CLI
            (LLM reads events)       (external access)       (human injection)

Ver actividad

Vía LLM: El agente puede llamar a insp_read_events para ver qué está sucediendo:

{
  "session_id": "sess_abc123",
  "types": ["traffic_in", "traffic_out"],
  "limit": 20
}

Vía HTTP: Consulta la API de guía directamente:

curl http://127.0.0.1:9847/api/sessions

Guiar al agente

Inyecta mensajes de guía que aparecerán en la siguiente respuesta de herramienta del LLM.

Usando la CLI:

./bin/mcp-steer.mjs "Focus on testing the error handling paths"
./bin/mcp-steer.mjs --session sess_abc123 "Try calling with invalid params"

Usando HTTP:

curl -X POST http://127.0.0.1:9847/api/steer \
  -H "Content-Type: application/json" \
  -d '{"message": "Check the authentication flow next"}'

Usando la herramienta MCP:

{
  "tool": "insp_inject_steering",
  "arguments": {
    "session_id": "sess_abc123",
    "message": "Great progress! Now test edge cases."
  }
}

Tipos de eventos

Flujo de trabajo típico

1. El LLM crea una sesión: insp_connect → obtiene sess_abc123

2. El LLM comienza las pruebas: insp_tools_call con session_id

3. El humano observa: curl http://127.0.0.1:9847/api/sessions

4. El humano guía: ./bin/mcp-steer.mjs "Also test the batch endpoint"

5. El LLM recibe la guía: La siguiente respuesta de herramienta incluye ⚡ STEERING from human: ...

6. El LLM se adapta: Toma en cuenta la guía humana

Ejemplos

Listar herramientas de un servidor MCP local (efímero):

{
  "command": "node",
  "args": ["/path/to/some-mcp-server/dist/server.js"]
}

Crear una sesión persistente:

{
  "command": "node",
  "args": ["/path/to/some-mcp-server/dist/server.js"]
}
// Returns: { "session_id": "sess_abc123", "server_info": {...} }

Llamar a una herramienta usando una sesión:

{
  "session_id": "sess_abc123",
  "tool_name": "search",
  "tool_args": {"query": "hello"}
}

Arquitectura

├── src/
│   ├── server.ts     # MCP server exposing inspector tools
│   ├── client.ts     # Client wrapper (hybrid stateless/session mode)
│   ├── transport.ts  # Transport factory (stdio, SSE, HTTP) + TracingWrapper
│   ├── session.ts    # SessionRegistry with GC (30-min TTL)
│   └── events.ts     # EventBuffer (ring buffer for notifications)
├── bin/
│   └── mcp-steer.mjs # CLI tool for human steering
├── tests/            # Integration test scripts (run with npx tsx)
└── vitest.config.ts  # Unit test + coverage config

Por qué existe esto

El MCP Inspector original es una combinación de interfaz web y CLI repartida en múltiples proyectos. Esto consolida la funcionalidad principal en un único servidor MCP ligero que un LLM puede usar para:

1. Desarrollar y depurar servidores MCP de forma iterativa

2. Probar la funcionalidad del servidor MCP sin salir de la conversación

3. Explorar qué herramientas/recursos/prompts expone un servidor MCP

4. Depurar el comportamiento con estado mediante sesiones persistentes

Desarrollo

npm install          # install dependencies
npm run build        # compile TypeScript
npm run dev          # watch mode
npm test             # run unit tests
npm run test:cov     # run tests with coverage
npm run lint         # lint source files
npm run format       # auto-format with Prettier
npm run typecheck    # type-check without emitting

Registro de cambios

v2.1.0

• Se añadió guía humana (insp_inject_steering) para flujos de trabajo human-in-the-loop

• Se añadió API HTTP en el puerto 9847 para guía/observabilidad externa

• Se añadió la herramienta CLI mcp-steer.mjs para una interacción humana sencilla

• Se corrigió un error crítico en TracingTransportWrapper donde el tiempo de captura del manejador causaba pérdida de mensajes

v2.0.0

• Se añadió gestión de sesiones (insp_connect, insp_disconnect, insp_list_sessions)

• Se añadió almacenamiento en búfer de eventos (insp_read_events)

• Todas las herramientas de inspección ahora soportan session_id opcional para conexiones persistentes

• Se añadió recolección de basura automática (TTL de 30 minutos para sesiones inactivas)

• Compatible con versiones anteriores: omite session_id para el comportamiento efímero original

v1.0.0

• Lanzamiento inicial con conexiones efímeras

Licencia

MIT