MCP Inspector - Debug de Servidores Model Context Protocol - Guia de Referência
MCP Inspector é a ferramenta oficial de teste visual e debug para servidores Model Context Protocol. Quando você está construindo um servidor MCP, você precisa ver o que ele realmente expõe e como responde — Inspector conecta ao seu servidor, lista suas ferramentas, recursos e prompts, deixa você invocar cada um com argumentos arbitrários, e mostra as mensagens JSON-RPC brutas fluindo em ambas as direções. É a maneira mais rápida de verificar se um servidor funciona antes de conectá-lo ao Claude, Cursor ou outro cliente.
Executando-o
| Método | Comando |
|---|
| npx (sem instalação) | npx @modelcontextprotocol/inspector |
| Com seu servidor | npx @modelcontextprotocol/inspector node build/index.js |
| Servidor Python | npx @modelcontextprotocol/inspector uv run server.py |
| Servidor remoto/SSE | iniciar, depois inserir a URL na UI |
| UI | abre no navegador (padrão http://localhost:6274) |
Tipos de Conexão
| Transporte | Use |
|---|
| STDIO | Servidor local executado como subprocess (mais comum) |
| SSE | Servidor remoto sobre Server-Sent Events |
| HTTP Streamable | Transporte remoto moderno |
# Inspecionar um servidor stdio local, passando args e env
npx @modelcontextprotocol/inspector \
-e API_KEY=abc123 \
node build/index.js --verbose
A Interface
| Aba | Mostra |
|---|
| Ferramentas | Todas as ferramentas, seu schema JSON e um formulário para chamá-las |
| Recursos | Recursos expostos e seu conteúdo |
| Prompts | Templates de prompt e seus argumentos |
| Notificações | Mensagens/logs iniciados pelo servidor |
| Histórico | Cada par solicitação/resposta |
Testando Ferramentas
| Passo | Ação |
|---|
| 1 | Abrir a aba Ferramentas; confirmar que sua ferramenta está listada |
| 2 | Verificar que o schema de entrada renderiza corretamente (tipos, campos necessários) |
| 3 | Preencher o formulário gerado e clicar para invocar |
| 4 | Inspecionar o conteúdo retornado e qualquer flag isError |
| 5 | Ler o JSON-RPC bruto no Histórico para debug de problemas de forma |
Esse loop pega os bugs MCP mais comuns: um schema malformado, uma ferramenta que retorna a forma de conteúdo errada, ou um erro não tratado.
O Que Verificar Antes de Enviar
| Verificação | Por quê |
|---|
| Nomes de ferramenta são únicos/descritivos | Clientes os expõem ao modelo |
| Descrições explicam quando usar a ferramenta | Dirige seleção correta de modelo |
| Schema de entrada é preciso | Previne chamadas malformadas |
Erros retornam isError com mensagem | Modelo pode se recuperar |
| Saídas grandes são paginadas/truncadas | Evita explodir a janela de contexto |
| Recursos têm URIs estáveis | Clientes os cacheiam/referenciam |
Dicas de Debug
| Sintoma | Olhar para |
|---|
| Servidor não se conecta | Comando/args; stderr no terminal de lançamento |
| Ferramenta faltando | Código de registro; reiniciar servidor |
| Schema renderiza estranhamente | Tipos JSON Schema na definição de ferramenta |
| Cliente se comporta diferentemente | Comparar JSON-RPC bruto no Histórico |
| Bug dependente de env | Re-lançar Inspector com -e KEY=value |
Fluxos de Trabalho Comuns
# Ciclo de desenvolvimento e teste para servidor MCP TypeScript
npm run build && npx @modelcontextprotocol/inspector node build/index.js
# Testar um servidor Python com uv
npx @modelcontextprotocol/inspector uv run my_server.py
# Verificar um servidor SSE remoto antes de adicioná-lo a um cliente
npx @modelcontextprotocol/inspector # escolher SSE, colar a URL
MCP Inspector vs Alternativas
| Abordagem | Trade-off |
|---|
| MCP Inspector | Propósito específico, visual, mostra protocolo bruto |
| Fio em cliente real | Realista mas ciclo de feedback lento |
| JSON-RPC escrito à mão | Controle total, tedioso |
| Testes unitários | Rápido e repetível; combinar com Inspector para exploração |
Use Inspector durante construção, depois adicione testes automatizados; veja Servidores MCP para padrões de implementação de servidor.
Recursos
