MCP Inspector: como testar seu servidor MCP antes de conectar a um cliente

ilustração representando o teste de um servidor MCP com o Inspector antes da conexão a um cliente de IA
Resposta rápida

Rode npx @modelcontextprotocol/inspector (Node 22.19.0 ou mais novo), abra a URL com token que ele imprime e conecte seu servidor por stdio (processo local) ou Streamable HTTP (URL remota). Nas abas Tools, Resources e Prompts você confere o que o servidor expõe e chama cada tool com argumentos. Para automatizar, o modo --cli devolve códigos de saída estáveis: 0 é sucesso, 3 é autenticação, 4 é servidor inacessível e 5 é erro de tool.

Você terminou um servidor MCP e quer saber se ele funciona. O caminho mais comum é plugar direto no cliente e torcer. Se algo falhar, você não sabe se o problema está no servidor ou no cliente.

Este guia cobre a etapa anterior: testar o servidor isolado, antes de conectar no ChatGPT, no Claude Code ou no Cursor. Você vai precisar de Node.js e de um servidor MCP próprio, local ou remoto.

O que você precisa antes de rodar o MCP Inspector

São três coisas: Node.js atualizado, a versão certa do Inspector e um servidor para testar.

O Inspector é a ferramenta oficial de referência para testar e depurar servidores MCP, segundo a documentação do Model Context Protocol. Ele vem num pacote único, @modelcontextprotocol/inspector, que traz três clientes no mesmo binário: interface web, CLI e TUI.

O código fica no repositório modelcontextprotocol/inspector, mantido pela organização Model Context Protocol.

Requisitos:

  • Node.js 22.19.0 ou mais novo. Na v1 o mínimo era 22.7.5, mas a v2 subiu a exigência, segundo o guia de migração v1 para v2.
  • Inspector da linha v2, que é a linha com suporte ativo de acordo com a página do pacote no npm.
  • Versão 2.12.0 ou mais nova. Ela corrigiu três vulnerabilidades que afetavam as versões 2.0.0 a 2.11.0, conforme a página de segurança do repositório.
  • Um servidor MCP para testar. Se for local, você precisa do comando que inicia o processo, como node build/index.js. Se for remoto, você precisa da URL do endpoint Streamable HTTP.

Não precisa instalar nada globalmente: o Inspector roda direto pelo npx.

Como testar um servidor MCP com o Inspector, passo a passo

O fluxo tem seis passos: abrir o Inspector, conectar o servidor (por stdio ou HTTP), listar o que ele expõe, chamar uma tool e acompanhar os logs. Cada passo traz o erro mais comum daquele ponto.

1. Abra o Inspector e use a URL com token

Rode o comando que abre a interface web:

npx @modelcontextprotocol/inspector

Resultado esperado: o Inspector imprime no terminal uma URL com um token de sessão de uso único. É essa URL que você abre no navegador. Na v2, a interface web usa por padrão a porta 6274. A porta de proxy separada (6277) da v1 deixou de existir, conforme o guia de migração.

O erro comum deste passo: digitar só localhost:6274 no navegador e ignorar o token. As rotas /api/* são protegidas por esse token (variável MCP_INSPECTOR_API_TOKEN), e ele muda a cada execução, segundo a documentação do Inspector. Por isso, copie sempre a URL completa que aparece no terminal.

Se você vem da v1, se liga nisso: tutoriais antigos mencionam a porta 6277, que não vale mais.

2. Conecte um servidor local via stdio

Stdio é o transporte padrão. Nele, o Inspector inicia o seu servidor como um processo filho e conversa com ele pela entrada e pela saída padrão.

Na interface web, abra o painel de conexão e escolha o transporte stdio. Ali você informa o comando, personaliza os argumentos de linha de comando e define variáveis de ambiente, segundo a documentação do Inspector.

Você também pode passar o comando do servidor direto ao abrir o Inspector:

npx @modelcontextprotocol/inspector node build/index.js

Pelo CLI, a forma documentada no README do Inspector é esta:

npx @modelcontextprotocol/inspector --cli node build/index.js

Resultado esperado: o servidor sobe e o Inspector mostra a conexão estabelecida.

O erro comum deste passo: o servidor não inicia. A página de debugging do MCP aponta três causas frequentes: caminho errado do executável, arquivos obrigatórios ausentes e problemas de permissão. Usar caminho absoluto no comando resolve boa parte dos casos.

3. Conecte um servidor remoto via Streamable HTTP

Se o servidor está publicado numa URL, escolha Streamable HTTP no painel de conexão da interface web. No CLI, o alvo passa a ser a URL, e você indica o transporte com --transport http:

npx @modelcontextprotocol/inspector --cli https://my-mcp-server.example.com --transport http --method tools/list

A flag --transport aceita http (Streamable HTTP) e sse. O sse é o transporte legado, conforme a documentação do CLI.

Resultado esperado: o comando retorna a lista de tools do servidor remoto.

O erro comum deste passo: usar sse num servidor novo, que fala Streamable HTTP. Outro tropeço frequente é o servidor exigir autenticação. Nesse caso, o CLI sai com código 3. A tabela de erros mais abaixo mostra como interpretar cada código.

4. Liste tools, resources e prompts

Com a conexão de pé, a interface web organiza o que o servidor expõe em abas, segundo a documentação do cliente web:

  • Tools: lista as tools e mostra o schema e a descrição de cada uma.
  • Resources: permite navegar, ler e assinar os resources.
  • Prompts: lista os prompts e aceita argumentos para pré-visualizar as mensagens geradas.

Pelo CLI, a listagem de tools é o --method tools/list do passo anterior.

O erro comum deste passo: a aba Tools não aparece. E por que isso acontece? A aba só aparece quando o servidor declara a capability tools. Capability é a lista de recursos que o servidor anuncia ao cliente ao conectar. Se a sua não inclui tools, o problema está no código do servidor, não no Inspector.

Vale ler as descrições com calma, porque é ali que você confere se cada tool está explicada do jeito que você queria.

5. Chame uma tool com argumentos

Na aba Tools da interface web, escolha a tool, preencha os argumentos no formulário gerado a partir do schema e execute. O resultado aparece logo abaixo.

No CLI, use --method tools/call com --tool-name, que é obrigatório. Para passar os argumentos, use --tool-arg chave=valor (repetível) ou --tool-args-json. Este é o exemplo da documentação do CLI com uma tool remota:

npx @modelcontextprotocol/inspector --cli https://api.example.com/mcp --transport http --method tools/call --tool-name get_weather --tool-arg city=Boston --format json

E este mostra vários argumentos de uma vez, incluindo um objeto:

--method tools/call --tool-name mytool --tool-arg key=value --tool-arg count=1 --tool-arg 'options={"format":"json"}'

Resultado esperado: a tool devolve a resposta sem erro. No CLI, o processo termina com código 0.

O erro comum deste passo: esquecer que o --tool-arg tenta interpretar cada valor como JSON. Assim, count=1 e zip=10001 chegam ao servidor como números, não como texto. Se o schema da sua tool espera string num campo como CEP, a chamada pode falhar ou se comportar diferente do esperado.

6. Acompanhe logs e notificações

O painel Notifications da interface web mostra ao vivo os logs do servidor e as notificações do protocolo, conforme chegam. É ali que você vê o que acontece enquanto chama as tools.

O erro comum deste passo: o servidor stdio escrever log no stdout. Em stdio, o stdout é o canal do protocolo, então qualquer print ou console.log perdido ali corrompe a conversa entre cliente e servidor. A página de debugging orienta logar em stderr, que o host captura. Em Streamable HTTP, o stderr não chega ao cliente, então você precisa de outra estratégia de log.

Como ler os erros de conexão no MCP Inspector

O jeito mais confiável de diagnosticar é o código de saída do CLI. Em qualquer saída diferente de zero, o CLI também grava no stderr uma linha JSON com um código estável, como auth_required, unreachable, tool_not_found, tool_is_error, schema_unportable, rate_limited ou error, segundo a documentação do CLI.

Código de saídaO que significaO que fazer
0SucessoSeguir para o próximo teste
1Erro de uso ou erro inesperadoRevisar flags e argumentos do comando
3Servidor exige autenticação (HTTP 401/403 ou erro de autorização do SDK)Revisar a autenticação que o servidor espera
4Servidor inacessível (DNS, conexão recusada, timeout ou fetch que falhou)Conferir a URL, se o servidor está no ar e se a rede alcança o endpoint
5Erro de tool: tools/call devolveu isError: true ou a tool não existeConferir o nome da tool e a lógica dela no servidor
6O --strict encontrou problema de portabilidade de schemaAjustar o schema da tool para ficar portável

Há ainda dois códigos ligados a flags específicas: o 2 indica que a tool não tem MCP App (--app-info), e o 7 indica que o --verify encontrou uma skill que viola o SEP-2640.

Dois problemas comuns não aparecem como código de saída específico, então vale checar primeiro:

  • Servidor stdio que não inicia: caminho errado, arquivo ausente ou permissão. Use caminho absoluto no comando.
  • Stdout poluído: log escrito no stdout de um servidor stdio quebra o protocolo. Mova todo log para stderr.

Como prevenir esses erros

A documentação de debugging recomenda um ciclo: usar o Inspector para os testes básicos, implementar a funcionalidade, adicionar pontos de log e voltar ao Inspector para iterar.

Na prática, isso significa testar cada tool nova assim que ela existe, em vez de acumular dez tools e descobrir no cliente que três estão quebradas.

Quando usar o CLI do Inspector em vez da interface web

Use a interface web para explorar e o CLI para automatizar.

A interface web é melhor quando você quer ver os schemas, ler descrições, preencher argumentos à mão e acompanhar notificações ao vivo. É o modo exploratório, ideal enquanto o servidor ainda está tomando forma.

O CLI foi pensado para CI, pipelines de shell e agentes de código, porque a saída é legível por máquina, segundo a documentação do CLI. Como os códigos de saída são estáveis, um tools/call que devolve 5 pode quebrar o pipeline automaticamente. É uma forma massa de garantir que nenhum deploy saia com tool quebrada.

A terceira opção é a TUI, aberta com npx @modelcontextprotocol/inspector --tui, para quem prefere ficar no terminal.

Na v2 também mudaram duas flags: --config passou a ser um arquivo de sessão somente leitura, e --catalog é a lista de servidores editável. Os segredos ficam no keychain do sistema operacional e, quando não há keychain, em ~/.mcp-inspector/secrets.json, conforme a documentação do Inspector.

Checklist antes de conectar o servidor no Claude Code, Cursor ou ChatGPT

Antes de plugar o servidor em qualquer cliente, confira:

  • O Inspector está na versão 2.12.0 ou mais nova e roda com Node 22.19.0 ou superior.
  • O servidor conecta pelo mesmo transporte que o cliente vai usar: stdio para processo local, Streamable HTTP para URL remota.
  • As abas Tools, Resources e Prompts mostram o que você espera, e a capability tools está declarada.
  • Cada tool foi chamada com argumentos reais e devolveu resultado sem isError.
  • Os argumentos numéricos e de texto chegam com o tipo que o schema espera.
  • O CLI termina com código 0 nas chamadas principais.
  • Nenhum log sai no stdout do servidor stdio.
  • O comando do servidor usa caminho absoluto.

Se tudo passou, o servidor está validado de forma isolada. Se ele falhar depois, dentro do cliente, o problema provavelmente está na configuração do cliente, e não no servidor.

Agora é conectar o servidor no cliente que você escolheu, já sabendo que o lado do servidor está validado.

Fontes consultadas

Consulta em .

Explore os vídeos do canal Hora de Codar.

Escrito por | Matheus Battisti

Matheus Battisti
Fundador da Hora de Codar

Programador apaixonado pelo mundo das tecnologias, sempre buscando em aprender e se aprofundar em linguagens, frameworks e o que mais for necessário para executar um bom trabalho. Agora tem uma nova missão que é de passar seu conhecimento adiante para formar novos programadores e especializar mais os que já são.

Formações

Formação Vibe Coding

Formação Vibe Coding

Do Prompt ao Produto: Crie Software Real com IA

  • 474 aulas
  • 20 projetos
  • 39h 30min

Blog | Mais populares