Como depurar um servidor MCP com o Inspector da Anthropic

A criação de servidores MCP se tornou comum. Os desenvolvedores estão adotando com entusiasmo a era dos LLMs, abraçando a revolução do MCP da Anthropic e criando servidores MCP. É possível começar a trabalhar com servidores MCP com menos de vinte linhas de código. Mas como depurá-los quando não se comportam como esperado?

Como começar com um servidor MCP simples em Node.js

Para depurar um servidor MCP, vamos começar com uma implementação bem simples em Node.js. Esse servidor MCP disponibiliza uma ferramenta que permite que quem implementa clientes MCP, como Cursor, Qodo, Claude Desktop e outros, obtenha informações sobre pacotes de código aberto de terceiros.

O código completo do servidor MCP está disponível no repositório snyk-labs/mcp-server-npm no GitHub. Veja abaixo o código na íntegra:

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 você pode ver no código do servidor MCP acima, ele depende da disponibilidade do utilitário de linha de comando do gerenciador de pacotes npm e, em seguida, inicia um processo do sistema com o argumento de linha de comando view para obter informações do registro oficial do npm.

A implementação do servidor MCP acima é intencionalmente vulnerável a injeção de comandos, para ensinar os desenvolvedores sobre os riscos de segurança de servidores MCP maliciosos e inseguros.

O MCP Inspector da Anthropic

A Anthropic disponibilizou uma interface de depuração chamada MCP Inspector no namespace oficial do pacote @modelcontextprotocol: @modelcontextprotocol/inspector.

Para uma depuração pontual, você pode executá-lo com npx, por exemplo: npx @modelcontextprotocol/inspector <mcp-server-command>. Substitua <mcp-server-command> pelo comando de linha de comando e seu argumento para o servidor MCP.

Para acessar rapidamente a ferramenta MCP Inspector, sugiro adicionar esta entrada ao package.json do Node.js:

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

Na primeira vez que você executar npm run debug, será solicitado que instale a ferramenta se você não passar o argumento -y para npx. A tela será semelhante a esta:

♥ 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)

Quando a instalação terminar e a ferramenta estiver pronta, você verá a seguinte saída no console:

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

Agora é só abrir http://127.0.0.1:6274 no navegador ;-)

Como nosso servidor MCP em Node.js é exposto por meio de STDIO do processo, vamos manter esse tipo de transporte e clicar no botão Connect.

Ao se conectar ao servidor MCP, uma nova aba horizontal é exibida na área de conteúdo principal, com todos os recursos disponíveis no servidor. No nosso caso, o servidor MCP disponibiliza apenas Tools (uma ferramenta para consultar informações de um pacote npm no registro do npm). Ao clicar em List Tools, será exibida uma lista com todas as ferramentas disponíveis:

Agora, podemos interagir diretamente com o servidor MCP pela interface web do MCP Inspector. Basta clicar em uma das ferramentas listadas — no nosso caso, getNpmPackageInfo — para exibi-la no painel à direita, junto com os parâmetros que você pode fornecer.

Veja uma captura de tela da execução com o pacote snyk como parâmetro

O MCP Inspector também exibe no console informações sobre as interações com servidores MCP. Para referência, veja a saída de depuração registrada durante as chamadas da ferramenta mostradas acima:

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

Saiba mais sobre como depurar servidores MCP

Outro aspecto comum da depuração de servidores MCP é exibir informações de depuração na tela com console.log() em JavaScript. No entanto, isso não funciona como esperado com servidores MCP STDIO baseados em processos. Por enquanto, recomendo uma solução simples: gravar os logs de depuração em um arquivo.