Como testar e depurar servidores MCP com o MCP Inspector

Se você encontrou este conteúdo pesquisando por "MCP Inspector não conecta" ou "como testar meu servidor MCP", está no lugar certo. E se o seu servidor compila sem erros, mas você não faz ideia se ele realmente funciona corretamente até que um cliente real falhe ao usá-lo, este artigo é exatamente para você.

O MCP Inspector oferece um ciclo completo de depuração com reconhecimento de transporte para qualquer servidor MCP que você esteja criando ou mantendo. Mas apenas se você configurar corretamente o tipo de transporte, os caminhos e a autenticação desde o início. Erre qualquer um desses três pontos e você passará uma hora investigando um erro de conexão que não tem nada a ver com o código do seu servidor.

O que pode falhar antes mesmo de você se conectar

• O MCP Inspector exibe ferramentas, recursos e prompts separadamente, permitindo validar cada primitiva do protocolo de forma independente.
• Um tipo de transporte incorreto gera timeouts silenciosos, não erros úteis; é aqui que surge a maioria dos chamados de configuração.
• Servidores HTTP exigem o segmento de caminho /mcp; omiti-lo causa falhas de roteamento mesmo quando o servidor responde a pings.
• Um teste bem-sucedido no Inspector confirma uma conexão limpa e schemas corretos, não que seu cliente de produção terá comportamento idêntico.

Pré-requisitos para executar o MCP Inspector

Prepare estes itens antes de abrir o Inspector. A ausência de qualquer um deles gera um modo de falha diferente e confuso.

• Node.js e npm instalados

  O Inspector é iniciado via npx, que vem com o npm. Sem o Node.js instalado na sua máquina, o comando de CLI falha imediatamente com um erro de "comando não encontrado", que parece ser um problema do Inspector, mas não é. É um problema de runtime.

• Um servidor MCP em execução antes de conectar

  Esta é uma ferramenta open source para testes e depuração de desenvolvedores; ela não inicia seu servidor para você. Se o processo do servidor ainda não estiver em execução, o Inspector tentará se conectar, atingirá o timeout e mostrará um erro que parece uma configuração incorreta de transporte. O servidor precisa estar ativo antes de o Inspector entrar em cena.

• Um navegador moderno para a GUI

  O Inspector disponibiliza sua interface a partir de um processo local do Node na porta 6274. Use Chrome ou Firefox em uma versão atual. Navegadores mais antigos podem fazer a UI falhar ao renderizar. A ferramenta é uma GUI baseada em navegador, não um aplicativo desktop — e isso surpreende muita gente na primeira vez.

• VS Code com a extensão MCP instalada (se estiver usando a variante de IDE)

  O Inspector integrado disponível no VS Code e em IDEs semelhantes exige que a extensão esteja instalada para que a inicialização automática funcione. Ignorar isso e esperar que o caminho via npx inicie a variante integrada à IDE não produz nada útil.

• Credenciais OAuth prontas se seu servidor exigir autenticação

  O ID do cliente, o segredo do cliente e a URL de redirecionamento devem estar em mãos antes de você se conectar a um servidor protegido por autenticação. Tentar resolver as credenciais depois de o Inspector já estar aberto leva a fluxos parciais, confusão no estado da sessão e erros de token que parecem problemas do servidor.

Primeiros passos: como iniciar o MCP Inspector

Há duas formas principais de iniciar o Inspector. O caminho de CLI via npx é o mais direto e funciona onde quer que o Node esteja instalado. O caminho integrado à IDE é iniciado automaticamente no seu ambiente de desenvolvimento se você tiver a extensão correta. Ambos disponibilizam a mesma UI baseada em navegador no localhost.

Executando o MCP Inspector via CLI npx

Abra seu terminal e execute:

npx @modelcontextprotocol/inspector@latest

Isso é tudo para o comando. O que acontece em seguida: um processo local do Node é iniciado, e o Inspector disponibiliza sua UI no navegador — por padrão, em http://localhost:6274. Seu navegador deve abrir automaticamente. Se não abrir, acesse esse endereço manualmente.

O ponto que as pessoas deixam passar nesse momento de “primeiros passos” é esperar um aplicativo desktop. O Inspector não é isso. É uma aba do navegador disponibilizada por um servidor local. Isso significa que, se você fechar o terminal, a UI desaparece. Mantenha o processo em execução enquanto usa a UI do Inspector.

Ao passar um comando de servidor diretamente pela CLI, o Inspector também pode iniciar o processo do servidor stdio para você em linha — por exemplo:

npx @modelcontextprotocol/inspector node /absolute/path/to/server.js

Esse é um atalho útil ao usar o MCP Inspector com um servidor stdio local. A linha de comando se torna a conexão.

Executando o MCP Inspector a partir de uma IDE ou ambiente integrado

Alguns ambientes, incluindo o VS Code com a extensão MCP instalada, incluem o Inspector e iniciam automaticamente a UI no navegador quando você o aciona pela IDE. O repositório oficial no GitHub é a fonte mais confiável para detalhes de arquitetura e comportamentos específicos por versão.

Essas variantes integradas à IDE lidam mais diretamente com a integração do Claude Desktop, pois a extensão conhece o contexto do seu workspace. Mas a extensão precisa ser instalada primeiro. Tentar invocar o Inspector pelo VS Code sem ela não gera nada — sem erro, sem UI, sem feedback útil. Instale a extensão e então acione-o.

Escolhendo o transporte correto: stdio, SSE e HTTP streamable

É aqui que a maioria dos chamados de suporte se origina. Um tipo de transporte incorreto não produz um erro claro. Ele gera um timeout silencioso ou uma falha no handshake sem mensagem explicando o que deu errado. Você ficará olhando para o indicador de status da conexão e presumirá que o servidor está fora do ar. Provavelmente não está.

O MCP oferece suporte a três modos de transporte distintos, e eles não são intercambiáveis. Selecionar o modo errado no Inspector é exatamente como tentar falar francês com alguém que só fala português — tecnicamente é a mesma conversa, mas nada é comunicado.

Configurando o transporte stdio: comando, argumentos e caminhos absolutos

Use o transporte stdio quando seu servidor MCP for executado como um processo filho local, iniciado diretamente pelo Inspector ou por um cliente. A configuração do servidor no Inspector exige dois campos: Command (o executável) e Arguments (quaisquer flags ou caminhos de arquivos).

O erro de configuração mais comum que vejo com stdio: usar um caminho relativo em vez de um absoluto. Caminhos relativos falham silenciosamente ao iniciar o processo do servidor. O erro retornado não diz "caminho inválido". Ele simplesmente não conecta. Use sempre o caminho absoluto completo.

Uma configuração stdio válida é assim:

Passe variáveis de ambiente pelo campo Environment, não modificando sua sessão de shell. O Inspector precisa enxergá-las no nível do processo.

Configurando o transporte HTTP e SSE: formato da URL e o caminho /mcp

Use o transporte HTTP ou SSE quando seu servidor MCP expuser um endpoint HTTP, local ou remoto. A documentação do Cloudflare Agents recomenda explicitamente esse caminho para testar servidores MCP remotos e gateways antes de conectá-los a um agente.

O campo de URL configurável é direto. A armadilha está no segmento de caminho. Para servidores que implementam o protocolo MCP sobre HTTP, a URL precisa incluir /mcp no final:

https://your-server.example.com/mcp

Omitir /mcp causa falhas de roteamento que parecem erros de conexão mesmo quando o servidor está totalmente acessível. O servidor responde em sua raiz. O endpoint do protocolo MCP não. Você receberá um 404 ou um timeout silencioso, dependendo de como o servidor lida com rotas não reconhecidas. Adicione o segmento de caminho — ele não é opcional.

Se precisar expor cabeçalhos personalizados, como um cabeçalho Authorization para um gateway, a configuração de transporte HTTP do Inspector inclui uma seção Headers. Adicione-os ali antes de se conectar.

Como lidar com autenticação em servidores MCP protegidos por OAuth

As falhas de autenticação no MCP Inspector quase sempre são problemas na sequência de configuração, não problemas do servidor. O servidor está acessível. As credenciais existem. Mas algo não foi informado antes da tentativa de conexão, ou não foi informado na ordem correta, e o token está ausente ou inválido quando o Inspector faz sua primeira solicitação.

Vejo este padrão o tempo todo: alguém passa 45 minutos depurando, supondo que o servidor MCP tem um bug, e então descobre que o campo do token de sessão do proxy ficou vazio o tempo inteiro. As mensagens de erro de autenticação do lado do cliente costumam ser silenciosas ou enganosas, o que significa que o sinal de que você precisa está no Inspector, não nos logs do servidor.

Registrando o cliente MCP Inspector no seu provedor de identidade

Antes de o Inspector poder concluir um fluxo OAuth, seu provedor de identidade precisa saber que o Inspector existe como cliente. Para Auth0 e provedores semelhantes, isso significa criar uma aplicação que represente o cliente Inspector e obter suas credenciais.

Você precisará de um Client ID, um Client Secret e uma URL de redirecionamento registrada. A URL de redirecionamento deve corresponder exatamente ao que o Inspector espera — normalmente algo como http://localhost:6274/oauth/callback. Uma divergência aqui faz com que o fluxo de consentimento falhe na etapa de redirecionamento com um erro genérico que parece um problema de permissão.

Existem dois caminhos de registro:

Se o seu provedor de identidade oferecer suporte a DCR, o Inspector poderá lidar sozinho com o fluxo de registro. Caso contrário, você fará o registro estático. Consulte a documentação do seu provedor — o Auth0 oferece suporte a ambos, mas o DCR exige uma flag de configuração explícita para ser ativado. Errar isso significa que o Inspector chegará com credenciais que o provedor não reconhece, e você receberá um 401 que não tem nada a ver com seu servidor MCP.

Do lado das permissões: não desative escopos tentando simplificar a configuração. O servidor MCP precisa de escopos específicos para expor corretamente suas ferramentas. Permissões excessivamente restritas geram listas parciais de ferramentas e erros 403 no meio da sessão que parecem bugs do Inspector.

Concluindo o fluxo OAuth e inserindo credenciais no Inspector

Na UI do Inspector, informe seu Client ID, Client Secret e o token de sessão do proxy na seção de configuração de autenticação antes de clicar em Connect. Essa sequência é importante. Clicar primeiro em Connect e esperar inserir as credenciais em uma janela pop-up não é como o fluxo funciona.

Depois de clicar em Connect com as credenciais preenchidas, o Inspector aciona a tela de consentimento baseada no navegador. Conclua o login e aceite as permissões. Após esse redirecionamento, o Inspector mantém um token de sessão ativo e você pode seguir para a aba Tools.

O token de sessão do proxy é a peça que a maioria das pessoas deixa passar. Ele é separado das credenciais de cliente OAuth. É ele que permite à camada de proxy do Inspector manter a sessão entre seu navegador e o servidor MCP. Deixe-o em branco e você receberá um erro de "token ausente", mesmo que o endpoint do servidor esteja perfeitamente acessível e as credenciais OAuth estejam corretas.

É aí que o chamado geralmente começa.

Como testar servidores MCP: descoberta de ferramentas e execução de ferramentas

Depois de conectado, o fluxo principal de teste tem três etapas: Connect, List Tools, Run Tool. Essa sequência é tudo. O que a torna útil é analisar cuidadosamente o retorno em cada etapa.

Uma conexão bem-sucedida mostra um indicador de status verde no Inspector, com o nome do servidor e a versão do protocolo visíveis. Se você vê isso, ainda não terminou de testar — você terminou de conectar. O teste começa agora.

Usando a aba Tools para listar e inspecionar schemas de ferramentas

Clique em List Tools na aba Tools. O Inspector envia a solicitação MCP tools/list ao seu servidor e renderiza a resposta — nomes das ferramentas, descrições e o schema JSON completo dos parâmetros de cada ferramenta.

É aqui que você valida várias coisas de uma vez. Os nomes das ferramentas estão corretos? As descrições dos parâmetros são precisas? Os parâmetros obrigatórios aparecem como obrigatórios no schema? O schema de entrada é realmente o que seu servidor espera?

Para servidores que expõem vários namespaces de ferramentas, algo comum em servidores Ontology MCP ou em qualquer servidor que encapsule múltiplas APIs de backend, a lista de ferramentas permite confirmar que os limites entre namespaces estão funcionando. Um schema que mostra o tipo de parâmetro errado para uma ferramenta é um bug do servidor, e é melhor encontrá-lo aqui do que em um agente de produção que passa silenciosamente o tipo errado e recebe resultados inúteis.

Inspecione o schema JSON bruto diretamente no Inspector antes de executar qualquer coisa. Leva 30 segundos e já detectou bugs reais que não apareceriam até a terceira ou quarta invocação de ferramenta.

Executando uma ferramenta e lendo a resposta em tempo real

Selecione uma ferramenta na lista. O Inspector renderiza um formulário com base no schema de entrada da ferramenta — preencha os parâmetros obrigatórios, adicione os opcionais relevantes para seu teste e clique em Run Tool.

O Inspector exibe o payload bruto da solicitação enviada e a resposta bruta recebida. Leia ambos. A solicitação mostra o que o Inspector realmente serializou a partir das entradas dos seus parâmetros, algo útil para detectar coerções de tipo. A resposta mostra a saída completa do servidor, incluindo qualquer payload de erro.

Como critério prático de sucesso: execute a mesma ferramenta duas vezes com entradas idênticas. As respostas devem ser idênticas, ou deterministicamente diferentes se a ferramenta consultar dados em tempo real. Respostas inconsistentes com entradas idênticas normalmente indicam um problema de estado no lado do servidor ou uma condição de corrida na implementação da ferramenta. Execute-a cinco vezes se a ferramenta acessar APIs externas — o comportamento de limite de taxa e o tratamento de timeout aparecem em execuções repetidas de uma forma que não apareceriam em um único teste.

O guia de Chris Ebert sobre o AWS Documentation MCP Server no Inspector é uma boa referência de como é um fluxo limpo de invocação de ferramenta de ponta a ponta — você pode ver os parâmetros da ferramenta search_documentation, o schema e como interpretar a resposta antes de conectar o servidor a um agente.

📊 Na prática:
Um teste bem-sucedido no Inspector confirma um status de conexão limpo, schemas corretos de ferramentas e respostas consistentes para entradas esperadas. Ele não confirma que seu cliente MCP de produção — uma IDE de IA, Claude Desktop ou um framework de agentes — lidará com casos extremos da mesma forma. O Inspector valida o comportamento do protocolo do seu servidor. O cliente introduz sua própria camada de interpretação.

Depurando erros do servidor MCP: logs, solicitações e visualizações no nível do protocolo

Quando algo falha no Inspector, o layout de visualização por abas é onde você deve ir para descobrir em que ponto ocorreu a falha. As abas não são decorativas. Cada uma expõe uma camada diferente da interação com o protocolo.

Os servidores MCP expõem três primitivas principais: recursos para contexto, ferramentas para ações e prompts para interações baseadas em modelos. A discussão da comunidade GitHub sobre a arquitetura MCP descreve isso claramente. O Inspector exibe as três separadamente, o que significa que você pode validar cada uma de forma independente em vez de presumir que uma lista de ferramentas funcionando significa que todo o resto está correto. Não significa.

Lendo o painel de saída de erros e logs de solicitação/resposta

O painel de saída de erros mostra mensagens do lado do servidor, saída stderr e códigos de erro no nível do protocolo. Se uma invocação de ferramenta falhar, olhe aqui primeiro. Um 401 significa um problema de token de autenticação. Um erro de incompatibilidade de schema significa que seu servidor está retornando uma resposta que não está em conformidade com o que o schema da ferramenta declarou. Um timeout sem código de erro normalmente significa que o servidor recebeu a solicitação e parou de responder durante a execução.

Os logs de solicitação/resposta mostram as mensagens brutas do protocolo MCP, incluindo o handshake de inicialização. É aqui que você inspeciona payloads e detalhes no nível do protocolo integralmente. Se o handshake mostrar uma incompatibilidade inesperada de capabilities, essa costuma ser a causa raiz de as ferramentas não serem listadas mesmo quando a conexão parece verde. Verifique o log antes de presumir que o código do servidor está errado. O problema frequentemente está na etapa de negociação.

Use as abas Prompts e Resources da mesma forma: liste-os, inspecione seus schemas e invoque-os com entradas de teste. Um servidor que lista ferramentas corretamente, mas retorna URIs de recursos malformadas falhará em fluxos específicos de agentes que combinam chamadas de ferramentas com recuperação de contexto. Encontre isso agora, não depois de conectar o servidor a um fluxo de IA de produção.

Faça iterações ajustando o código do servidor, reconectando e executando novamente. O Inspector não mantém sessões entre reinicializações do servidor — mas reconectar é rápido, e esse ciclo (alterar código → reiniciar servidor → reconectar o Inspector → executar ferramenta novamente) é o ritmo central de desenvolvimento para qualquer trabalho com servidor MCP.

Solucionando erros de conexão e configurações incorretas comuns

Quando a conexão falhar, siga esta lista antes de presumir que o servidor tem um bug:

• Servidor não iniciado antes de conectar

  O Inspector não consegue iniciar seu servidor na maioria das configurações. Se o processo não estiver em execução, a conexão atingirá o timeout. Inicie o servidor, confirme que ele está aceitando conexões e então abra o Inspector.

• Tipo de transporte incorreto selecionado

  Um servidor stdio configurado como HTTP, ou o contrário, produz um handshake com falha e sem mensagem de diagnóstico útil. Veja como seu servidor é iniciado — se for um processo filho, é stdio. Se ele se vincula a uma porta, é HTTP ou SSE.

• Segmento de caminho /mcp ausente na URL

  Para transportes HTTP/HTTP streamable, a URL deve terminar com /mcp para garantir o roteamento correto do protocolo. Um servidor acessível em sua raiz não significa que o endpoint MCP está acessível.

• Token de autenticação ou token de sessão do proxy não informado antes de conectar

  Informe todas as credenciais antes de clicar em Connect. Inserir esses dados depois de uma tentativa de conexão com falha deixa o Inspector em um estado parcial que às vezes exige um recarregamento completo para ser limpo.

• Caminho relativo na configuração stdio

  Use caminhos absolutos para o comando do servidor. Caminhos relativos falham silenciosamente durante a inicialização do processo, o que parece um erro de conexão.

🤔 Espere.
O Inspector valida que seu servidor se comporta corretamente durante uma sessão do Inspector. Mas seu cliente MCP de produção — seja uma configuração do Claude Desktop, uma IDE de IA ou um agente personalizado — tem sua própria interpretação do protocolo, seu próprio comportamento de repetição e sua própria lógica de timeout. Desenvolvedores frequentemente descobrem discrepâncias apenas depois de trocar o Inspector pelo cliente real. O Inspector é uma etapa necessária, não a final.

Mais um ponto importante sobre o ciclo de depuração: se seu servidor MCP lida com chamadas autenticadas e você está vendo falhas intermitentes de autenticação que não se reproduzem de forma consistente no Inspector, o problema geralmente está no escopo do token, não na validade dele. Na Latenode, quando engenheiros conectam um servidor MCP a um fluxo de automação com várias etapas, eles adicionam um nó JavaScript que registra o token exato, os escopos e o corpo da solicitação em cada chamada — assim, quando um 401 aparece, eles têm o contexto completo em um só lugar em vez de reuni-lo a partir de três logs diferentes. Esse padrão é diretamente útil aqui: inclua o registro em log no fluxo antes de presumir que o servidor está com problema.