MCP Inspector: como testar e depurar servidores MCP localmente

O que é o MCP Inspector

O MCP Inspector é a ferramenta de desenvolvimento de referência para testar e depurar servidores MCP. Ele permite listar ferramentas, chamar funções, ler recursos, inspecionar prompts e acompanhar o tráfego JSON-RPC entre cliente e servidor.

A ferramenta vem em um único pacote, @modelcontextprotocol/inspector, que instala um binário chamado mcp-inspector. Três clientes compartilham o mesmo núcleo: web (interface gráfica no navegador), CLI (scriptável, para automação) e TUI (interface de terminal). Todos usam os mesmos transportes, arquivos de configuração e negociação de protocolo.

O pacote também instala o mcpdo, um cliente experimental que mantém uma conexão aberta entre vários comandos.

Pré-requisitos

O MCP Inspector exige Node.js 22.19.0 ou mais recente. Não é preciso instalar nada globalmente: tudo roda via npx.

Se você for depurar um servidor Python, instale o uv ou o pipx para rodar o servidor com uvx ou python. Se for depurar um servidor Node, tenha o node e o npm disponíveis.

Como rodar no modo web

O modo web é o padrão. Ele abre uma interface gráfica no navegador e é o modo mais rico.

Para inspecionar um servidor local, passe o comando que o inicia como argumento:

$ npx @modelcontextprotocol/inspector node build/index.js

Para abrir a interface sem alvo e adicionar servidores pela própria UI:

$ npx @modelcontextprotocol/inspector

O comando imprime uma URL com um token de API por lançamento e abre o navegador. O token protege as rotas /api, porque o servidor pode executar processos na sua máquina. Não digite localhost:6274 de memória: use a URL impressa.

Para desativar a abertura automática do navegador, defina MCP_AUTO_OPEN_ENABLED=false.

Como rodar no modo CLI

O modo CLI é scriptável e retorna resultados em texto ou JSON. É o modo ideal para CI, pipelines de shell e agentes de código que precisam verificar uma mudança rapidamente.

Para listar as ferramentas de um servidor:

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

Para chamar uma ferramenta e extrair o resultado com jq:

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

Cada execução conecta, faz uma requisição e encerra. Para fluxos que exigem uma sessão aberta (tasks, subscriptions, elicitation), use o mcpdo.

Como rodar no modo TUI

O modo TUI é uma interface de terminal interativa, útil quando não há navegador disponível.

$ npx @modelcontextprotocol/inspector --tui node build/index.js

A navegação e os atalhos de teclado estão documentados na página de referência do TUI.

Inspecionando servidores locais e remotos

Para um servidor stdio, passe o comando de inicialização como argumento posicional. Use -- para separar argumentos do servidor dos argumentos do Inspector:

$ npx @modelcontextprotocol/inspector node build/index.js -- --verbose --config /etc/myserver.conf

Para passar variáveis de ambiente e diretório de trabalho:

$ npx @modelcontextprotocol/inspector -e API_KEY=abc123 -e REGION=us-east-1 --cwd ~/projects/my-server \
  node build/index.js

Para um servidor HTTP ou SSE remoto:

$ npx @modelcontextprotocol/inspector --server-url https://api.example.com/mcp --transport http

O Inspector suporta os transportes http (Streamable HTTP) e sse. Se o servidor responder 401, o Inspector executa o fluxo OAuth descrito na documentação de autorização e tenta de novo.

Sempre leia o README do servidor antes de inspecionar. Cada servidor exige comandos e argumentos diferentes.

Usando em CI e em fluxos automatizados

O modo CLI retorna códigos de saída distintos para cada situação, o que facilita a integração em pipelines. Use --format json para obter saída estruturada e --strict para transformar a verificação de portabilidade de schema em gate.

Um fluxo típico de smoke test:

1. Conecte com initialize para confirmar que o servidor responde.
2. Liste ferramentas com tools/list.
3. Chame uma ferramenta com tools/call e verifique o resultado.
4. Faça assertions com jq ou com o código do pipeline.

O Inspector também importa configurações de clientes MCP existentes, o que facilita reutilizar a mesma lista de servidores em desenvolvimento e em CI.

Segurança e segredos

O Inspector armazena segredos (tokens OAuth, client secrets e valores de env de servidores stdio) no keychain do sistema operacional quando disponível. Em máquinas sem keychain, como Linux sem libsecret, sessões SSH, Termux e containers, os segredos vão para ~/.mcp-inspector/secrets.json, sem criptografia, a menos que você forneça uma chave.

O token de API por lançamento protege as rotas /api, mas não é um mecanismo de autenticação forte. Em máquinas onde outros processos podem alcançar a porta, configure DANGEROUSLY_OMIT_AUTH com cuidado.

Para servidores stdio, o stderr do processo aparece na aba Console, que é onde a maioria dos servidores coloca seus diagnósticos. Verifique essa aba primeiro quando uma conexão falhar sem motivo aparente.

Eras de protocolo

O Inspector suporta duas eras de protocolo: legacy e modern (2026-07-28). O padrão é legacy. Para testar comportamento moderno, defina a era no Server Settings ou passe --protocol-era legacy|auto|modern na linha de comando.

A documentação detalha como cada aba muda entre as eras, incluindo headers Mcp-* padronizados e tarefas.