MCP Inspector npx e CLI: como testar um servidor MCP

Um servidor MCP pode iniciar sem nenhum erro e mesmo assim ser inútil. O processo está rodando, o log está silencioso e o cliente que você conecta mostra uma lista de ferramentas vazia ou a mensagem vaga "failed to connect". Antes de culpar o cliente, teste o servidor sozinho. MCP Inspector é a ferramenta do próprio projeto Model Context Protocol para essa tarefa: ele faz o papel do cliente, executa o handshake e permite listar e chamar tudo o que seu servidor expõe. Este artigo mostra como iniciá-lo com npx, como controlá-lo pela CLI, como ler seus códigos de saída e como corrigir os erros que mais consomem tempo.

💡 Verificação de versão: a maioria dos tutoriais online descreve o Inspector v1. A versão mais recente no npm no momento em que este texto foi escrito é a 2.9.0, e a v2 mudou portas, variáveis de ambiente, flags e códigos de saída. Todos os comandos abaixo seguem a documentação da v2.

O que o MCP Inspector faz

O Inspector é um cliente MCP criado para depuração. Ele inicia seu servidor (stdio) ou se conecta a ele (HTTP ou SSE), executa o handshake initialize e mostra exatamente o que volta. Não há um modelo de linguagem no meio, então, quando algo falha, você sabe que o problema está no servidor ou na conexão, e não no comportamento do prompt.

O handshake que ele verifica

A primeira chamada, initialize, prova que o servidor fala MCP. A resposta traz quatro coisas que vale a pena ler linha por linha:

• serverInfo: o nome e a versão que seu servidor informa.
• protocolVersion: a revisão do protocolo que os dois lados acordaram.
• capabilities: quais recursos existem, como ferramentas, resources e prompts.
• instructions: texto opcional que o servidor entrega aos clientes.

Se capabilities não tiver uma entrada tools, nenhum cliente jamais mostrará uma ferramenta, por mais que você tenha registrado no código. Essa única verificação explica boa parte dos relatos de "minhas ferramentas não aparecem".

Interface web, CLI e TUI

Um só pacote, três interfaces. A flag de modo deve vir primeiro, logo depois do nome do pacote.

Use a interface web enquanto você constrói e a CLI quando precisar de uma resposta que possa repetir.

Inicie com npx

Não há nada para instalar. npx baixa o pacote, executa e repassa tudo o que vier depois do nome do pacote ao servidor que você quer testar. Uma primeira execução sensata leva uma linha e um minuto.

Versão do Node e portas

A v2 precisa do Node.js 22.19.0 ou mais recente. Rode node --version antes de tudo, porque um runtime antigo é a primeira coisa a descartar.

Mudanças de porta e de variável pegam quem segue posts antigos, então aqui vai a comparação rápida:

Altere a porta da interface web com CLIENT_PORT, um inteiro fixo entre 1 e 65535. A v2 também reserva a 6275 para o sandbox do MCP Apps e a 6278 para o servidor de origem do app, então mantenha as duas livres.

CLIENT_PORT=6280 npx @modelcontextprotocol/inspector node build/index.js

Copiar prompt

No Windows PowerShell, defina a variável primeiro com $env:CLIENT_PORT = "6280" e depois rode a mesma linha npx.

Passe argumentos e variáveis de ambiente

Para um servidor Node já compilado, coloque o comando logo depois do nome do pacote:

npx @modelcontextprotocol/inspector node build/index.js

Copiar prompt

Variáveis de ambiente entram com -e:

npx @modelcontextprotocol/inspector -e API_TOKEN=your-token -- node build/index.js

Copiar prompt

Um servidor TypeScript sem etapa de build funciona do mesmo jeito, por exemplo npx @modelcontextprotocol/inspector tsx src/index.ts. A maioria dos projetos envolve a linha em um script npm para que toda a equipe rode o mesmo comando:

{
  "scripts": {
    "inspect": "npx @modelcontextprotocol/inspector node dist/index.js"
  }
}

Copiar prompt

💡 O duplo hífen inverte o sentido. No modo web e TUI, tudo o que vem depois de -- vai para o seu servidor. No modo CLI, tudo o que vem antes de -- é o alvo, e tudo o que vem depois é uma opção do Inspector. No modo CLI, o comando do servidor também precisa vir primeiro: --cli --method tools/list node build/index.js descarta o alvo silenciosamente.

O token por trás da interface

A v2 cria um token de API aleatório a cada inicialização e o exige em toda rota /api/*. Uma página aberta sem ele é rejeitada. Defina MCP_INSPECTOR_API_TOKEN você mesmo se quiser um valor fixo, e reinicie se alguma aba reclamar, porque o token antigo morreu com o processo antigo.

O servidor web se vincula a 127.0.0.1 por padrão por meio de HOST. Expô-lo a outras interfaces exige um DANGEROUSLY_BIND_ALL_INTERFACES explícito, e DANGEROUSLY_OMIT_AUTH=true desativa totalmente a verificação do token. O Inspector inicia processos locais em seu nome, então trate o token como uma senha e mantenha as duas substituições fora de máquinas compartilhadas.

Use um arquivo de configuração

Digitar o comando cansa quando um servidor precisa de três argumentos e duas variáveis de ambiente. Coloque-os em um arquivo e selecione o servidor pelo nome. Existem duas flags, e elas são mutuamente exclusivas:

O catálogo padrão fica em ~/.mcp-inspector/mcp.json. Nenhuma das flags pode ser combinada com um alvo ad hoc na mesma linha de comando.

Entradas stdio

{
  "mcpServers": {
    "my-server": {
      "type": "stdio",
      "command": "node",
      "args": ["build/index.js"],
      "env": { "API_TOKEN": "your-token" },
      "cwd": "/path/to/server"
    }
  }
}

Copiar prompt

Mantenha command e cada item de args como entradas separadas. O Inspector executa esses itens diretamente, em vez de uni-los em uma única string, o que preserva os limites dos argumentos quando um caminho contém espaços.

Entradas HTTP e SSE

{
  "mcpServers": {
    "remote-server": {
      "type": "http",
      "url": "https://mcp.internal.example/mcp",
      "headers": { "X-Tenant": "acme" }
    }
  }
}

Copiar prompt

O campo type aceita stdio, http (Streamable HTTP) ou sse. Na CLI, você escolhe uma entrada com --server:

npx @modelcontextprotocol/inspector --cli --config ./mcp.json --server my-server --method tools/list

Copiar prompt

--server só seleciona um servidor no modo CLI. O cliente web avisa e ignora a opção quando você carrega um arquivo, e a TUI a rejeita como opção desconhecida.

Teste um servidor MCP pela CLI

O modo CLI dispensa o navegador e imprime a resposta no stdout, o que o torna a ferramenta certa para verificações rápidas e para tudo o que você quiser automatizar. Todo comando tem a mesma forma: primeiro o alvo, depois --method, e depois o que aquele método precisar.

Liste as ferramentas primeiro

Comece sempre perguntando o que o servidor acha que oferece:

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

Copiar prompt

Troque o método por resources/list ou prompts/list para verificar os outros dois recursos. Um servidor remoto precisa de um endereço e um transporte, e de um token bearer se estiver protegido:

npx @modelcontextprotocol/inspector --cli \
  --transport http --server-url https://example.com/mcp \
  --header 'Authorization: Bearer <token>' \
  --method tools/list

Copiar prompt

Compare os nomes na saída com o que seu cliente espera. Uma ferramenta registrada como generateImage mas solicitada como generate_image é um caso clássico, e basta um comando para identificá-lo.

Chame uma ferramenta com argumentos JSON

npx @modelcontextprotocol/inspector --cli node build/index.js \
  --method tools/call \
  --tool-name generate_image \
  --tool-args-json '{"prompt":"a ceramic mug on an oak desk, soft window light","aspect_ratio":"16:9"}'

Copiar prompt

--tool-args-json recebe um objeto JSON e não faz nenhuma coerção, então números continuam números e booleanos continuam booleanos. Para um teste rápido, --tool-arg prompt="a red door" é mais curto, mas seus valores são interpretados como JSON quando são válidos, então uma string que parece um número vira número. Quando os tipos importam, use a forma JSON.

💡 Observação sobre Windows: o Windows PowerShell 5.1 remove as aspas duplas internas do JSON passado a programas nativos. Escape cada uma com uma barra invertida, ou use --tool-arg para valores curtos.

Leia os códigos de saída

A CLI informa o resultado no código de saída, então um script nunca precisa extrair texto para saber o que aconteceu.

O código 5 é o mais importante para testes. Uma ferramenta que falha de forma limpa agora faz o comando falhar, então inspector --cli ... && next-step para onde a v1 seguiria em frente. As conexões desistem após 15 segundos por padrão nas execuções ad hoc, e --connect-timeout <ms> eleva esse limite quando seu servidor carrega um banco de dados ou um modelo na inicialização.

Rode verificações do Inspector no CI

Um smoke test útil confirma quatro coisas: o servidor conecta, a ferramenta existe, uma chamada válida tem sucesso e uma chamada inválida falha. Quatro comandos, sem navegador, e uma versão quebrada nunca chega aos usuários.

Fixe a versão

Fixe uma versão exata no CI, nunca um intervalo como @2.x, porque flags e códigos de saída mudaram entre versões principais:

npx --yes @modelcontextprotocol/inspector@2.9.0 --cli node build/index.js --method initialize

Copiar prompt

Dê a cada job seu próprio armazenamento de token, para que uma execução nunca reutilize o estado de login de outra:

export MCP_STORAGE_DIR="$(mktemp -d)"
export MCP_INSPECTOR_OAUTH_STATE_PATH="$MCP_STORAGE_DIR/oauth.json"

Copiar prompt

Verifique com jq

Adicione --format json e a CLI imprime um objeto JSON com um campo result, pronto para jq. Vale conhecer duas armadilhas. Nunca junte o stderr ao stdout com 2>&1 durante a análise, porque os diagnósticos caem dentro do JSON. E capture o status de saída antes de encadear, porque um pipeline reporta o status do último comando, o que esconde uma CLI com falha atrás de um jq de sucesso.

#!/usr/bin/env bash
set -u
INSPECT="npx --yes @modelcontextprotocol/inspector@2.9.0 --cli node build/index.js"

# 1. The handshake works
$INSPECT --method initialize --format json > init.json || exit 1

# 2. The tool exists (status captured before the pipe)
tools=$($INSPECT --method tools/list --format json); code=$?
[ "$code" -eq 0 ] || { echo "tools/list failed with $code"; exit "$code"; }
echo "$tools" | jq -e '.result.tools | map(.name) | index("generate_image")' > /dev/null || exit 1

# 3. A valid call succeeds
$INSPECT --method tools/call --tool-name list_models --tool-args-json '{}' \
  --format json > call.json || exit 1

# 4. An invalid call fails
if $INSPECT --method tools/call --tool-name generate_image --tool-args-json '{}' \
  > /dev/null 2>&1; then
  echo "tool accepted empty input"; exit 1
fi

Copiar prompt

O quarto teste é aquele que as pessoas pulam. Um servidor que aceita um prompt ausente e devolve uma imagem em branco vai passar em todo teste positivo que você escrever.

Corrija os erros que você vai encontrar

A maioria das falhas se encaixa em alguns padrões. Identifique primeiro o sintoma e depois leia a seção que o explica.

Poluição do stdout no stdio

O transporte stdio carrega suas mensagens JSON-RPC no stdout, e o protocolo diz que um servidor não pode escrever ali nada que não seja uma mensagem MCP válida. Um único console.log perdido, um banner de inicialização ou uma dependência imprimindo um aviso corrompe o fluxo. O handshake então falha com erros de parse ou simplesmente trava.

Corrija enviando cada linha de log para o stderr (console.error no Node, sys.stderr no Python). Para encontrar o culpado, rode o comando do servidor sozinho: um servidor stdio saudável não imprime nada até que um cliente fale com ele.

Transporte não detectado

A v2 não adivinha mais. Ela só infere o transporte quando o caminho da URL termina em /mcp ou /sse, e qualquer outro caso exige a flag escrita explicitamente:

npx @modelcontextprotocol/inspector --cli --server-url https://example.com/api \
  --transport http --method tools/list

Copiar prompt

Quando uma mensagem de erro não faz sentido para você, cole a saída do stderr e o schema da sua ferramenta em Claude Sonnet 5 ou GPT 5.6 Sol e peça as três causas mais prováveis. Os dois leem bem stack traces, e você ainda confirma a resposta com o Inspector.

Testando um servidor de geração de imagens

Servidores que geram mídia se comportam de forma diferente em teste. As chamadas são lentas, podem custar dinheiro e o trabalho geralmente roda em segundo plano. A API de desenvolvedor do PicassoIA mostra o padrão com clareza. Ela segue o estilo Replicate: você cria uma previsão com POST /v1/models/{owner}/{name}/predictions em https://api.picassoia.com/v1, autentica com um token bearer, consulta GET /v1/predictions/{id} repetidamente e lê o resultado quando ele termina.

No momento em que este texto foi escrito, a API e a conexão MCP expõem os mesmos quatro modelos: PicassoIA Image, PicassoIA Image Editor Pro, PicassoIA Video e Seedance 2.5 Lite. Uma conta permite 5 previsões simultâneas, compartilhadas entre todos os tokens e conexões MCP, com prompts de até 4.000 caracteres.

💡 Teste em série. Um loop de chamadas de ferramenta em uma mesma sessão do Inspector pode ocupar todas as cinco vagas e deixar seu cliente real sem vagas. Rode os testes de imagem uma chamada por vez.

Ferramentas assíncronas precisam de uma ferramenta de status

Uma ferramenta que inicia um job deve devolver um ID em poucos segundos, e uma segunda ferramenta deve informar o progresso. Teste as duas partes isoladamente:

• A chamada de início retorna rapidamente com um ID, em vez de manter a conexão aberta por minutos.
• A chamada de status aceita esse ID e informa um estado de progresso e um estado final.
• Um job com falha volta como resultado com isError: true, e não como uma chamada que trava.
• Um ID inválido produz o código de saída 5, e não uma queda do processo do servidor.
• A URL de saída responde com status 200 e um tipo de conteúdo de imagem quando você a busca.

Essa última verificação é a mais barata, e pega a falha que os leitores notam primeiro: uma imagem quebrada em uma página publicada.

Crie sua primeira imagem a seguir

Agora você tem uma forma de provar que um servidor funciona antes que alguém dependa dele. O mesmo hábito compensa no lado criativo: rode um teste pequeno, leia o resultado e mude uma coisa de cada vez.

Abra o PicassoIA e experimente o ciclo você mesmo. Escreva um prompt de uma frase em PicassoIA Image, refine o resultado com o PicassoIA Image Editor Pro e depois dê vida à imagem fixa com o PicassoIA Video. Mude a lente, a luz ou o assunto entre as execuções e compare as saídas lado a lado. Cinco comandos deste artigo valem a pena ficar ao lado do seu terminal:

• --method initialize para confirmar o handshake.
• --method tools/list para confirmar os nomes das ferramentas.
• --method tools/call --tool-args-json para confirmar o comportamento.
• --format json mais jq para verificar a resposta.
• O código de saída, sempre lido antes da saída.