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

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.

Black Week do Nexus
A formação de IA mais completa do Brasil
- 7 formações · 112 cursos · 26 mil alunos
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.

VPS Hostinger para seu sistema
10% OFF extraVPS com SSD NVMe e backups semanais. O cupom MATHEUSHORADECODAR é aplicado automaticamente pelo link.
Ver planos com 10% OFF →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.

Crie sistemas com IA para vender
Prompts, modelos e checklists para criar e publicar seu sistema com IA e preparar a oferta para o primeiro cliente.
Quero o e-book gratuito Receba o livro e os bônus no seu e-mail.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ída | O que significa | O que fazer |
|---|---|---|
| 0 | Sucesso | Seguir para o próximo teste |
| 1 | Erro de uso ou erro inesperado | Revisar flags e argumentos do comando |
| 3 | Servidor exige autenticação (HTTP 401/403 ou erro de autorização do SDK) | Revisar a autenticação que o servidor espera |
| 4 | Servidor 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 |
| 5 | Erro de tool: tools/call devolveu isError: true ou a tool não existe | Conferir o nome da tool e a lógica dela no servidor |
| 6 | O --strict encontrou problema de portabilidade de schema | Ajustar 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
toolsestá 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 .
- Model Context Protocol: documentação do MCP Inspector
- GitHub modelcontextprotocol/inspector
- npm: @modelcontextprotocol/inspector
- Guia de migração v1 para v2 do Inspector (GitHub)
- Model Context Protocol: Inspector CLI client
- README do Inspector (GitHub)
- Model Context Protocol: Inspector web client
- Model Context Protocol: Debugging
Formações
Formação Vibe Coding
Do Prompt ao Produto: Crie Software Real com IA
- 474 aulas
- 20 projetos
- 39h 30min
Blog | Mais populares

O que é o REA (Reverse Engineer Anything) e por que ele é um MCP, não uma ferramenta solta?
REA Reverse Engineer Anything é o MCP open source que dá engenharia reversa ao seu agente de código. Veja o que é e como configurar.
Supabase MCP no Claude Code: como conectar o agente ao schema do seu banco
Supabase MCP no Claude Code conecta o agente ao schema real do seu banco: veja como instalar, autenticar via OAuth e por que usar só em desenvolvimento.
MCP do Supabase: como limitar o que o agente pode fazer no seu banco
O MCP do Supabase roda com escrita liberada por padrão. Veja como usar read_only, project_ref e features para limitar o que o agente faz no seu banco.
