Use o MCP Inspector para depurar e testar tools sem precisar do Claude Desktop.
O MCP Inspector é a ferramenta oficial de debug para servers MCP. É uma interface web que se conecta ao seu server e permite visualizar todas as tools, resources e prompts registrados, executar tools manualmente com parâmetros personalizados e inspecionar respostas — tudo sem precisar do Claude Desktop.
O MCP Inspector atua como um client MCP visual. Ele inicia seu server, estabelece conexão via STDIO e apresenta uma interface web interativa onde você pode: ver a lista completa de tools (com descrições e parâmetros), resources (com URIs e tipos) e prompts (com argumentos). Você pode executar qualquer tool preenchendo os parâmetros na interface e ver a resposta formatada em tempo real. É essencial durante o desenvolvimento.
O Inspector é mantido pela equipe oficial do MCP no repositório modelcontextprotocol/inspector no GitHub. Ele suporta todas as versões do protocolo MCP e é atualizado junto com a especificação. Desenvolvedores que usam o Inspector durante o desenvolvimento reportam redução de 50% no tempo de debug comparado a testar diretamente via Claude Desktop, porque o ciclo de feedback é instantâneo.
Use o Inspector como seu primeiro passo de teste — antes mesmo de configurar o Claude Desktop. Se sua tool funciona no Inspector, vai funcionar no Claude. Se não funciona no Inspector, o problema está no seu server, não na configuração do client. O Inspector é sua ferramenta de isolamento de problemas.
A instalação do MCP Inspector é surpreendentemente simples — basta um único comando npx que baixa e executa tudo automaticamente. Não precisa instalar globalmente nem configurar nada. A interface abre no navegador e está pronta para uso.
O comando para executar o Inspector é:
O npx baixa o pacote temporariamente e o executa sem instalação global. O Inspector abre automaticamente no navegador em http://localhost:5173 (porta padrão). Na primeira execução pode demorar alguns segundos para baixar as dependências.
Certifique-se de ter Node.js instalado (versão 18 ou superior). Verifique com node --version.
Execute npx @modelcontextprotocol/inspector uv run server.py — isso inicia o Inspector E seu server simultaneamente.
O navegador abre automaticamente. Se não abrir, acesse manualmente http://localhost:5173.
Node.js é obrigatório para executar o Inspector. Se você não tem Node.js instalado, acesse nodejs.org e instale a versão LTS. No Linux, você pode usar sudo apt install nodejs npm ou instalar via nvm para gerenciar múltiplas versões.
O Inspector precisa saber como iniciar seu server MCP. Você especifica o comando de execução do server e o Inspector cuida de iniciar o processo, estabelecer a conexão STDIO e manter a comunicação ativa durante toda a sessão de debug.
O comando completo para conectar ao seu server:
O Inspector inicia o processo uv run server.py como subprocesso e se conecta via STDIO — o mesmo mecanismo que o Claude Desktop usa. Isso significa que se funcionar no Inspector, funcionará no Claude. Qualquer output que seu server envie para stdout é interpretado como mensagens MCP; logs devem ir para stderr.
Se você usa python diretamente em vez de uv, o comando seria npx @modelcontextprotocol/inspector python server.py. O Inspector aceita qualquer comando que inicie um processo MCP via STDIO. Certifique-se de que o ambiente virtual correto está ativado se estiver usando python diretamente.
A interface do Inspector mostra todas as tools registradas no seu server com suas descrições e parâmetros. Você pode preencher os campos de parâmetros, executar a tool e ver a resposta imediatamente — um ciclo de feedback rápido que acelera enormemente o desenvolvimento.
Na aba "Tools" do Inspector, você vê a lista completa de tools do server. Cada tool mostra seu nome, descrição (da docstring) e os parâmetros esperados (dos type hints). Ao clicar em uma tool, campos de formulário aparecem para cada parâmetro. Preencha os valores, clique em "Run Tool" e a resposta aparece formatada abaixo — incluindo o conteúdo retornado, tipo MIME e possíveis erros. Isso permite testar cada tool isoladamente, com diferentes combinações de parâmetros.
Na aba "Tools", encontre a tool que deseja testar na lista. Verifique se o nome e a descrição estão corretos.
Preencha os campos de parâmetros com valores de teste. Comece com valores válidos, depois teste edge cases.
Clique em "Run Tool" e observe a resposta. Verifique formato, conteúdo e tratamento de erros.
Ajuste o código do server, salve o arquivo. Reconecte o Inspector para testar as mudanças.
Crie uma lista de cenários de teste para cada tool: valores válidos normais, valores vazios, valores no limite do range, caracteres especiais, strings muito longas. Execute cada cenário pelo Inspector e verifique que a resposta é adequada em todos os casos. Isso é especialmente importante para tools que fazem requisições HTTP ou acessam arquivos.
O Inspector mostra as respostas das tools em formato estruturado, incluindo o JSON bruto da comunicação MCP. Isso permite verificar não apenas o conteúdo da resposta, mas também se o formato e os tipos estão corretos — informações essenciais para garantir que o modelo vai interpretar a resposta corretamente.
Ao executar uma tool no Inspector, a resposta é exibida em duas visões: a visão formatada (texto legível, imagens renderizadas) e o JSON bruto (a mensagem MCP exata que seria enviada ao client). O JSON bruto mostra o array de content com cada bloco tendo type e text. Comparar o JSON bruto com o resultado esperado é a forma mais confiável de validar que sua tool funciona corretamente.
Uma resposta MCP bem formatada segue a estrutura: {"content": [{"type": "text", "text": "..."}]}. O campo isError indica se a tool encontrou um erro. Quando retorna True, o modelo sabe que deve informar o erro ao usuário em vez de usar a resposta como dado válido. O Inspector mostra isso visualmente com cores diferentes.
Quando algo não funciona como esperado, o Inspector é seu melhor aliado para diagnosticar o problema. Desde servers que não conectam até tools que retornam erros inesperados, existe um processo sistemático de debug que resolve a maioria dos problemas em poucos minutos.
Os problemas mais comuns e suas soluções: Server não conecta — verifique se o comando está correto e se as dependências estão instaladas. Tool não aparece na lista — verifique se o decorator @mcp.tool() está presente e se a função não tem erros de sintaxe. Tool retorna erro — verifique os logs do server no terminal onde o Inspector está rodando; o stderr do server aparece ali. Resposta vazia — verifique se a função retorna algo (não é None).
O Inspector mostra "Connected" no topo? Se não, o comando do server está errado ou o server tem erro de importação.
A aba "Tools" mostra suas tools? Se não, verifique decorators, imports e se o server não crasha na inicialização.
Os parâmetros estão corretos na interface? Se faltam, verifique type hints na assinatura da função.
Se a tool executa mas retorna erro, olhe os logs no terminal. O stderr do server tem o stack trace completo.
Após editar o código, é necessário reconectar o Inspector para que as mudanças tenham efeito.
O erro mais comum e mais difícil de diagnosticar: print() no código do server. Como o MCP usa stdout para comunicação, qualquer print() no seu código corrompe o protocolo e causa desconexão imediata. Substitua todos os prints por logging.info() ou logging.debug() que vão para stderr.
npx @modelcontextprotocol/inspector — requer Node.js.
Este é o último módulo da Trilha 3! Próxima Trilha: Trilha 4 — Projetos do Mundo Real