Cómo depurar un servidor MCP con Anthropic Inspector

La creación de servidores MCP se ha vuelto habitual. Los desarrolladores están adoptando con entusiasmo la era de los LLM gracias a la revolución MCP de Anthropic y creando servidores MCP de forma activa. Puedes poner en marcha servidores MCP con menos de veinte líneas de código, pero ¿cómo los depuras cuando se comportan de manera inesperada?

Primeros pasos con un servidor MCP sencillo en Node.js

Para depurar un servidor MCP, primero partimos de una implementación sencilla de un servidor MCP en Node.js. Este servidor expone una herramienta que permite a quienes implementan clientes MCP, como Cursor, Qodo, Claude Desktop y otros, obtener información sobre paquetes de código abierto de terceros.

El código completo del servidor MCP está disponible en el repositorio snyk-labs/mcp-server-npm de GitHub. A continuación, se muestra el código completo:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import { execSync } from "child_process";

const server = new McpServer({
  name: "npm JavaScript package management tools",
  version: "1.0.0",
  description: "Provides tools to get information about open source npm packages from the npmjs registry"
});

server.tool(
  "getNpmPackageInfo",
  "Get information about an npm package",
  {
    packageName: z.string()
  },
  async ({ packageName }) => {    
    const output = execSync(`npm view ${packageName}`, {
      encoding: "utf-8",
    });

    return {
      content: [
        {
          type: "text",
          text: output
        },
      ],
    };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

Como puedes ver en el código anterior del servidor MCP, este depende de que esté disponible la utilidad de línea de comandos del administrador de paquetes npm y, luego, inicia un proceso del sistema con el argumento de línea de comandos view para obtener información del registro oficial de npm.

La implementación anterior de un servidor MCP es deliberadamente vulnerable a la inyección de comandos, con el objetivo de enseñar a los desarrolladores los riesgos de seguridad de los servidores MCP maliciosos e inseguros.

MCP Inspector de Anthropic

Anthropic ofrece una interfaz de usuario de depuración llamada MCP Inspector en el espacio de nombres oficial del paquete @modelcontextprotocol: @modelcontextprotocol/inspector.

Para una depuración puntual, puedes ejecutarlo con npx, por ejemplo: npx @modelcontextprotocol/inspector <mcp-server-command>, donde debes reemplazar <mcp-server-command> por el comando de línea de comandos y sus argumentos del servidor MCP.

Para acceder rápidamente a la herramienta MCP Inspector, sugiero agregar la siguiente entrada de Node.js a package.json:

{
"scripts": {
  "debug": "npx -y @modelcontextprotocol/inspector node index.js"
}
}

La primera vez que ejecutes npm run debug, se te pedirá que instales la herramienta si no proporcionas el argumento -y a npx. Verás algo así:

♥ 18:22  npm run debug           

> mcp-server-npm@1.0.0 debug
> npx @modelcontextprotocol/inspector node index.js

Need to install the following packages:
@modelcontextprotocol/inspector@0.11.0
Ok to proceed? (y)

Cuando termine la instalación y todo esté listo, verás el siguiente resultado en la consola:

Starting MCP inspector...
⚙️ Proxy server listening on port 6277
🔍 MCP Inspector is up and running at http://127.0.0.1:6274 🚀

Esta es tu señal para abrir http://127.0.0.1:6274 en el navegador ;-)

Como nuestro servidor MCP de Node.js se expone mediante STDIO de proceso, dejaremos ese tipo de transporte tal como está y haremos clic en el botón Connect.

Al conectarte al servidor MCP, aparece una nueva pestaña horizontal en el área de contenido principal con todos los recursos disponibles del servidor. En nuestro caso, el servidor MCP solo expone Tools (una herramienta para buscar información de un paquete npm en el registro de npm), así que, al hacer clic en List Tools, se mostrará una lista con todas las herramientas disponibles:

Ahora podemos interactuar activamente con el servidor MCP desde esta interfaz web de MCP Inspector. Solo tienes que hacer clic en una de las herramientas de la lista (en nuestro caso, getNpmPackageInfo) para que aparezca en el panel derecho junto con los parámetros que puedes proporcionarle.

Aquí tienes una captura de pantalla de la ejecución con el paquete snyk como parámetro.

MCP Inspector también muestra en la consola información sobre las interacciones con los servidores MCP. Como referencia, este es el resultado de depuración que se mostró al registrar las llamadas a la herramienta anteriores:

New connection
Query parameters: [Object: null prototype] {
  command: 'node',
  args: 'index.js',
  env: '{"HOME":"/Users/lirantal","LOGNAME":"lirantal","PATH":"/Users/lirantal/.npm/,"SHELL":"/bin/zsh","TERM":"xterm-256color","USER":"lirantal"}',
  transportType: 'stdio'
}
Stdio transport: command=/Users/lirantal/.local/state/fnm_multishells/34121_1745832579143/bin/node, args=index.js
Spawned stdio transport
Connected MCP client to backing server transport
Created web app transport
Set up MCP proxy
Received message for sessionId 83514436-7b4b-492f-8026-957684f3b736
Received message for sessionId 83514436-7b4b-492f-8026-957684f3b736
Received message for sessionId 83514436-7b4b-492f-8026-957684f3b736

Más sobre la depuración de servidores MCP

Otro aspecto de la depuración de servidores MCP suele ser mostrar resultados de depuración en pantalla mediante console.log() en JavaScript. Sin embargo, esto no funciona como esperarías con los servidores MCP de STDIO basados en procesos. Por ahora, te recomiendo una solución sencilla: escribir los registros de depuración en un archivo de registro.