MCP Inspector: como usar para testar e depurar um servidor MCP

MCP Inspector: como usar para testar e depurar um servidor MCP

Para usar o MCP Inspector, você o executa com o comando npx @modelcontextprotocol/inspector, escolhe o transporte do seu servidor (stdio ou HTTP), conecta e chama cada ferramenta, recurso e prompt pela interface, vendo as mensagens trocadas. Assim você confirma esquemas, formato das respostas, transporte e autenticação sem depender de um modelo de linguagem, que adicionaria incerteza ao teste.

Principais pontos

• O Inspector é um cliente de teste: ele isola o servidor MCP do agente e mostra exatamente o que entra e o que sai.
• Teste primeiro com entradas válidas, depois com entradas inválidas, vazias e maliciosas, para checar o esquema e as mensagens de erro.
• Falhas de transporte costumam vir de comando errado, saída poluída no stdio, endereço incorreto ou sessão HTTP mal configurada.
• Autenticação deve ser testada com credenciais corretas, ausentes, expiradas e com permissão insuficiente.
• Só ligue o servidor a um agente depois de um checklist curto, com limites de ação e registro dos testes.

O que é o MCP Inspector e quando usar

O Model Context Protocol (MCP) é um protocolo aberto que define como aplicações de IA se conectam a ferramentas e fontes de dados. Se você quer a visão geral, a introdução oficial ao MCP é o ponto de partida. O MCP Inspector é a ferramenta de teste e depuração mantida junto ao projeto. Ele faz o papel de um cliente MCP com interface visual: conecta ao seu servidor, lista o que ele expõe e deixa você exercitar cada item manualmente.

A principal vantagem é a separação de causas. Quando um agente falha ao usar uma ferramenta, o problema pode estar no servidor, no esquema, na autenticação, no transporte, na instrução do agente ou no próprio modelo. Com o Inspector, você elimina todas as causas que não são do servidor. Se a ferramenta funciona ali e falha no agente, o foco muda para a descrição da ferramenta e o contexto. Se falha ali, o servidor ainda não está pronto.

Use o Inspector em três momentos: durante o desenvolvimento de um servidor próprio, na avaliação de um servidor de terceiros (junto com o processo descrito em como auditar um servidor MCP antes de instalar na empresa) e depois de qualquer mudança de versão, esquema ou credencial.

Como abrir o Inspector: passo a passo

Você precisa de Node.js instalado. O Inspector roda direto pelo npx, sem instalação permanente. Como a ferramenta evolui, confira sempre o README do repositório oficial para a versão que for usar, porque opções e telas podem mudar.

O roteiro básico é este:

• Rode npx @modelcontextprotocol/inspector no terminal. Ele sobe uma interface local e mostra o endereço para abrir no navegador.
• Em versões recentes, o terminal também exibe um token de sessão para o proxy local. Se a página recusar a conexão, verifique se o endereço aberto contém esse token ou se você o informou nas configurações.
• No painel de conexão, escolha o tipo de transporte: stdio para servidores que rodam como processo local, ou HTTP (streamable HTTP, e SSE em servidores mais antigos) para servidores remotos.
• No caso de stdio, informe o comando, os argumentos e as variáveis de ambiente. No caso de HTTP, informe a URL e, se necessário, cabeçalhos de autenticação.
• Clique em conectar e observe se a inicialização termina com sucesso. Depois dela, as abas de ferramentas, recursos e prompts mostram o que o servidor declarou.

Também é possível passar o comando do servidor direto na linha de comando do Inspector, o que facilita repetir o mesmo teste. Se você já configurou o servidor em algum cliente, vale comparar com o que descrevemos em configurar MCP no Claude Code: o comando e as variáveis que funcionam no Inspector devem ser os mesmos que irão para a configuração final.

Como validar ferramentas e esquemas

Na aba de ferramentas, o Inspector lista cada ferramenta com nome, descrição e esquema de entrada. Essa tela é, na prática, o que o modelo vai enxergar. Leia como se fosse o modelo: a descrição diz com clareza quando usar e quando não usar a ferramenta? Os nomes dos parâmetros são autoexplicativos? Os campos obrigatórios estão marcados?

A Anthropic tem um bom material sobre esse ponto em escrevendo ferramentas eficazes para agentes. A ideia central é que descrições ambíguas e respostas excessivamente longas pioram o uso da ferramenta. O Inspector deixa esses problemas visíveis antes de qualquer agente entrar em cena.

Para cada ferramenta, execute pelo menos estes testes:

• Entrada válida típica: confirme que a resposta tem o formato esperado e traz só o necessário, sem dados extras que o agente não deveria ver.
• Campo obrigatório ausente: o servidor deve recusar com erro claro, não com falha genérica nem com valor padrão silencioso.
• Tipo errado: texto onde se espera número, lista vazia, valor nulo, texto muito longo.
• Valor fora do domínio: uma data impossível, um identificador que não existe, um valor negativo onde só cabe positivo.
• Entrada hostil: texto com instruções embutidas ou caracteres especiais. Isso não prova segurança, mas mostra se o servidor trata a entrada como dado.
• Repetição: chame a mesma ferramenta duas vezes com os mesmos argumentos e veja se a segunda chamada duplica algum efeito, como criar dois registros.

Presta atenção à diferença entre ferramentas de leitura e de escrita. O protocolo permite anotações que indicam, por exemplo, que uma ferramenta é somente leitura ou destrutiva, mas elas são dicas para o cliente, não uma barreira de segurança. A barreira real precisa estar no servidor e nas permissões da credencial usada. Para uma visão mais ampla de validação de entrada, saída e ação, veja guardrails para agentes de IA.

Teste também recursos e prompts, se o servidor os oferece. Em recursos, verifique se a listagem não expõe mais do que deveria. Em prompts, confira se os argumentos são validados e se o texto gerado não carrega dados sensíveis.

Como achar erros de transporte

Erros de transporte são os mais frustrantes porque o sintoma é quase sempre o mesmo: a conexão não abre ou cai logo depois de abrir. O Inspector ajuda porque mostra em qual etapa a falha ocorre.

No transporte stdio, as causas mais comuns são:

• Comando ou caminho incorreto: o processo nem inicia. Teste o mesmo comando manualmente no terminal.
• Saída poluída: no stdio, a saída padrão carrega as mensagens do protocolo. Qualquer log, aviso ou print escrito nela corrompe a comunicação. Logs devem ir para a saída de erro.
• Variáveis de ambiente ausentes: o servidor sobe, mas falha ao buscar uma chave ou um endereço. Confira se elas foram informadas no painel de conexão.
• Versão de runtime diferente: o servidor funciona no seu terminal e falha no Inspector porque o ambiente do processo é outro.

No transporte HTTP, os suspeitos mudam:

• URL ou caminho do endpoint errado, que resulta em resposta de não encontrado.
• Tipo de transporte escolhido no Inspector diferente do que o servidor implementa, por exemplo SSE antigo contra um servidor streamable HTTP.
• Proxy, balanceador ou firewall que encerra conexões longas ou bufferiza respostas em fluxo.
• Falta de cabeçalhos exigidos, como o de autorização.
• Sessões que expiram ou são perdidas quando há mais de uma instância do servidor atrás de um balanceador sem afinidade de sessão.

Use a área de notificações e o histórico de mensagens do Inspector para ver a ordem do que aconteceu: pedido de inicialização, resposta, lista de ferramentas. Se a inicialização nunca é respondida, o problema é de transporte ou de processo. Se a inicialização funciona e a lista de ferramentas falha, o problema está na implementação do servidor.

Como depurar autenticação e permissões

Servidores remotos quase sempre exigem credenciais. Teste a autenticação como um conjunto de casos, não como um único teste de sucesso. O guia de autorização da OWASP recomenda negar por padrão e verificar permissões em cada requisição, e esses princípios orientam os testes abaixo.

• Sem credencial: o servidor deve responder com recusa clara, não com dados parciais.
• Credencial válida: a conexão funciona e as ferramentas aparecem.
• Credencial expirada ou revogada: a recusa deve ser imediata e a mensagem não deve vazar detalhes internos.
• Credencial com escopo menor: ferramentas de escrita devem falhar para quem só tem leitura.
• Credencial de outro usuário ou outra unidade: um dado que pertence a outra pessoa não pode ser retornado.

Se o servidor usa OAuth, o fluxo de autorização tem etapas próprias (redirecionamento, consentimento, troca de código por token, renovação). Para entender cada etapa, a documentação de OAuth 2.0 do Google é uma referência didática. Versões recentes do Inspector oferecem suporte a testar esse fluxo; se a sua versão não oferecer, obtenha o token por outro meio e informe-o no cabeçalho de autorização, lembrando de usar uma credencial de teste, nunca a de produção.

Um cuidado de LGPD: durante os testes, não use dados reais de clientes se puder evitar. Prefira uma base de teste com registros fictícios. Se for inevitável usar dados reais, limite a credencial ao mínimo necessário e não guarde capturas de tela ou logs com informações pessoais.

Cenário ilustrativo e checklist antes de ligar a um agente

Cenário ilustrativo: uma empresa de serviços cria um servidor MCP com duas ferramentas, uma que consulta o status de um pedido e outra que altera a data de entrega. No Inspector, a consulta funciona. Ao testar a alteração com uma data no passado, o servidor aceita e grava. Ao testar com um número de pedido de outro cliente usando a mesma credencial, a alteração também passa. Nenhum agente foi necessário para descobrir dois problemas sérios: falta de validação de domínio e falta de verificação de propriedade do pedido. Eles são corrigidos no servidor, e os mesmos testes são repetidos até a recusa aparecer.

Use este checklist antes da integração:

• Todas as ferramentas têm nome claro, descrição que diz quando usar e esquema com campos obrigatórios marcados.
• Cada ferramenta foi testada com entrada válida, ausente, de tipo errado, fora do domínio e repetida.
• Respostas trazem só os campos necessários e têm tamanho controlado, para não consumir a janela de contexto do agente sem necessidade.
• Mensagens de erro são claras para o modelo e não expõem detalhes internos.
• Transporte testado no ambiente real, não apenas na máquina de desenvolvimento.
• Autenticação testada nos cinco casos: sem credencial, válida, expirada, de escopo menor e de outro usuário.
• Ferramentas de escrita têm limite de ação, confirmação humana quando o risco justifica e registro de quem pediu o quê.
• O roteiro de testes está salvo, para ser repetido a cada mudança do servidor.

Depois da integração, lembre-se de que o agente pode chamar ferramentas em sequência e repetir chamadas. Limites de passos e de tempo continuam necessários, como explicamos em agente de IA em loop infinito.

Como o método mapear, limitar, pilotar e transferir se aplica

O Inspector cabe bem no método de trabalho que seguimos em projetos de IA. Em mapear, você lista quais ferramentas o servidor expõe e que processo de negócio cada uma toca. Em limitar, define quais ações ficam disponíveis, com que credencial e com qual aprovação humana. Em pilotar, usa o roteiro de testes do Inspector como base e acompanha um fluxo real com registros e um critério de sucesso combinado. Em transferir, entrega o roteiro, o checklist e os registros à equipe, que decide se amplia, ajusta ou interrompe. O Inspector não substitui avaliações do comportamento do agente, apenas garante que o servidor sob ele é previsível.

Perguntas frequentes

O MCP Inspector serve para servidores de terceiros? Serve, e é uma das melhores formas de conhecer o que o servidor realmente expõe antes de instalá-lo. Ele mostra ferramentas, descrições e respostas, mas não substitui a leitura do código, a revisão de permissões e a análise de segurança.

Posso usar o Inspector em produção? O mais seguro é testar em um ambiente separado, com credenciais de teste e dados fictícios. Se for indispensável diagnosticar algo em produção, use uma credencial de leitura com o menor escopo possível e evite chamar ferramentas que alteram dados.

A ferramenta funciona no Inspector e falha no agente. O que verificar? Compare a descrição e o esquema que o modelo vê, o tamanho das respostas e as instruções do agente. Também confirme que a configuração do cliente usa o mesmo comando, as mesmas variáveis e a mesma credencial que você testou. Se tudo isso for igual, o problema está no uso da ferramenta pelo modelo, e o caminho é ajustar descrições e avaliar o comportamento com casos de teste.

O Inspector testa segurança do servidor? Ele ajuda a encontrar falhas óbvias, como falta de validação e de controle de acesso, mas não é uma auditoria de segurança. Trate-o como a primeira camada de verificação e combine com revisão de código, permissões mínimas e práticas como as do OWASP Top 10 para aplicações com LLMs.

Fontes

• Model Context Protocol: introdução
• Anthropic: Writing effective tools for agents
• OWASP: guia de autorização
• Google: OAuth 2.0