MCP Inspector

O MCP Inspector é uma ferramenta de desenvolvedor para testar, depurar e inspecionar servidores MCP por meio de uma interface web e fluxo de trabalho de proxy.

GitHubExperimente este MCPPatrocinado

Documentação

MCP Inspector

O MCP Inspector é uma ferramenta de desenvolvimento para testar e depurar servidores MCP.

MCP Inspector Screenshot

Visão Geral da Arquitetura

O MCP Inspector consiste em dois componentes principais que trabalham juntos:

MCP Inspector Client (MCPI): Uma interface web baseada em React que fornece uma interface interativa para testar e depurar servidores MCP
MCP Proxy (MCPP): Um servidor Node.js que atua como uma ponte de protocolo, conectando a interface web aos servidores MCP através de vários métodos de transporte (stdio, SSE, streamable-http)

Observe que o proxy não é um proxy de rede para interceptar tráfego. Em vez disso, ele funciona tanto como um cliente MCP (conectando-se ao seu servidor MCP) quanto como um servidor HTTP (servindo a interface web), permitindo interação baseada em navegador com servidores MCP que usam diferentes protocolos de transporte.

Executando o Inspector

Requisitos

Node.js: ^22.7.5

Início Rápido (modo UI)

Para começar rapidamente com a UI, basta executar o seguinte:

npx @modelcontextprotocol/inspector

O servidor iniciará e a UI estará acessível em http://localhost:6274.

A partir de um repositório de servidor MCP

Para inspecionar uma implementação de servidor MCP, não é necessário clonar este repositório. Em vez disso, use npx. Por exemplo, se o seu servidor estiver construído em build/index.js:

npx @modelcontextprotocol/inspector node build/index.js

Você pode passar argumentos e variáveis de ambiente para o seu servidor MCP. Os argumentos são passados diretamente para o seu servidor, enquanto as variáveis de ambiente podem ser definidas usando a flag -e:

# Pass arguments only
npx @modelcontextprotocol/inspector node build/index.js arg1 arg2

# Pass environment variables only
npx @modelcontextprotocol/inspector -e key=value -e key2=$VALUE2 node build/index.js

# Pass both environment variables and arguments
npx @modelcontextprotocol/inspector -e key=value -e key2=$VALUE2 node build/index.js arg1 arg2

# Use -- to separate inspector flags from server arguments
npx @modelcontextprotocol/inspector -e key=$VALUE -- node build/index.js -e server-flag

O inspector executa tanto um cliente UI MCP Inspector (MCPI) (porta padrão 6274) quanto um servidor MCP Proxy (MCPP) (porta padrão 6277). Abra a UI do cliente MCPI no seu navegador para usar o inspector. (Essas portas são derivadas do mapeamento do teclado T9 de MCPI e MCPP, respectivamente, como um mnemônico). Você pode personalizar as portas se necessário:

CLIENT_PORT=8080 SERVER_PORT=9000 npx @modelcontextprotocol/inspector node build/index.js

Para mais detalhes sobre as formas de usar o inspector, consulte a seção Inspector do site de documentação do MCP. Para ajuda com depuração, consulte o guia de depuração.

Exportação de Arquivo de Servidores

O MCP Inspector fornece botões convenientes para exportar configurações de inicialização de servidores para uso em clientes como Cursor, Claude Code ou o CLI do Inspector. O arquivo geralmente é chamado de mcp.json.

Entrada de Servidor - Copia uma única entrada de configuração de servidor para a sua área de transferência. Isso pode ser adicionado ao seu arquivo mcp.json dentro do objeto mcpServers com o nome de servidor de sua preferência.

Exemplo de transporte STDIO:
```
{
  "command": "node",
  "args": ["build/index.js", "--debug"],
  "env": {
    "API_KEY": "your-api-key",
    "DEBUG": "true"
  }
}
```
Exemplo de transporte SSE:
```
{
  "type": "sse",
  "url": "http://localhost:3000/events",
  "note": "For SSE connections, add this URL directly in Client"
}
```

Arquivo de Servidores - Copia uma estrutura completa de arquivo de configuração MCP para a sua área de transferência, com a sua configuração atual de servidor adicionada como default-server. Isso pode ser salvo diretamente como mcp.json.

Exemplo de transporte STDIO:

{
  "mcpServers": {
    "default-server": {
      "command": "node",
      "args": ["build/index.js", "--debug"],
      "env": {
        "API_KEY": "your-api-key",
        "DEBUG": "true"
      }
    }
  }
}

Exemplo de transporte SSE:

{
  "mcpServers": {
    "default-server": {
      "type": "sse",
      "url": "http://localhost:3000/events",
      "note": "For SSE connections, add this URL directly in Client"
    }
  }
}

Esses botões aparecem na UI do Inspector depois que você configura as configurações do seu servidor, facilitando salvar e reutilizar suas configurações.

Para conexões de transporte SSE, o Inspector fornece funcionalidade semelhante para ambos os botões. O botão "Entrada de Servidor" copia a configuração de URL SSE que pode ser adicionada ao seu arquivo de configuração existente, enquanto o botão "Arquivo de Servidores" cria um arquivo de configuração completo contendo a URL SSE para uso direto em clientes.

Você pode colar a Entrada de Servidor no seu arquivo mcp.json existente sob o nome de servidor escolhido, ou usar o payload completo do Arquivo de Servidores para criar um novo arquivo de configuração.

Autenticação

O inspector suporta autenticação por token bearer para conexões SSE. Insira seu token na UI ao conectar-se a um servidor MCP, e ele será enviado no cabeçalho Authorization. Você pode substituir o nome do cabeçalho usando o campo de entrada na barra lateral.

Considerações de Segurança

O MCP Inspector inclui um servidor proxy que pode executar e se comunicar com processos MCP locais. O servidor proxy não deve ser exposto a redes não confiáveis, pois tem permissões para iniciar processos locais e pode se conectar a qualquer servidor MCP especificado.

Autenticação

O servidor proxy do MCP Inspector requer autenticação por padrão. Ao iniciar o servidor, um token de sessão aleatório é gerado e impresso no console:

🔑 Session token: 3a1c267fad21f7150b7d624c160b7f09b0b8c4f623c7107bbf13378f051538d4

🔗 Open inspector with token pre-filled:
   http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=3a1c267fad21f7150b7d624c160b7f09b0b8c4f623c7107bbf13378f051538d4

Este token deve ser incluído como um token Bearer no cabeçalho Authorization para todas as solicitações ao servidor. O inspector abrirá automaticamente seu navegador com o token pré-preenchido na URL.

Abertura automática do navegador - O inspector agora abre automaticamente seu navegador com o token pré-preenchido na URL quando a autenticação está habilitada.

Alternativa: Configuração manual - Se você já tiver o inspector aberto:

Clique no botão "Configuration" na barra lateral
Encontre "Proxy Session Token" e insira o token exibido no console do proxy
Clique em "Save" para aplicar a configuração

O token será salvo no armazenamento local do seu navegador para uso futuro.

Se você precisar desabilitar a autenticação (NÃO RECOMENDADO), você pode definir a variável de ambiente DANGEROUSLY_OMIT_AUTH:

DANGEROUSLY_OMIT_AUTH=true npm start

Vinculação Apenas Local

Por padrão, tanto o servidor proxy do MCP Inspector quanto o cliente vinculam-se apenas a localhost para prevenir acesso à rede. Isso garante que eles não sejam acessíveis a partir de outros dispositivos na rede. Se você precisar vincular a todas as interfaces para fins de desenvolvimento, você pode substituir isso com a variável de ambiente HOST:

HOST=0.0.0.0 npm start

Aviso: Vincule a todas as interfaces apenas em ambientes de rede confiáveis, pois isso expõe a capacidade do servidor proxy de executar processos locais e ambos os serviços ao acesso à rede.

Proteção contra Rebinding de DNS

Para prevenir ataques de rebinding de DNS, o MCP Inspector valida o cabeçalho Origin nas solicitações recebidas. Por padrão, apenas solicitações da origem do cliente são permitidas (respeita CLIENT_PORT se definido, padrão na porta 6274). Você pode configurar origens adicionais permitidas definindo a variável de ambiente ALLOWED_ORIGINS (lista separada por vírgulas):

ALLOWED_ORIGINS=http://localhost:6274,http://localhost:8000 npm start

Configuração

O MCP Inspector suporta as seguintes configurações. Para alterá-las, clique no botão Configuration na UI do MCP Inspector:

Configuração	Descrição	Padrão
`MCP_SERVER_REQUEST_TIMEOUT`	Tempo limite para solicitações ao servidor MCP (ms)	10000
`MCP_REQUEST_TIMEOUT_RESET_ON_PROGRESS`	Redefinir tempo limite em notificações de progresso	true
`MCP_REQUEST_MAX_TOTAL_TIMEOUT`	Tempo limite total máximo para solicitações enviadas ao servidor MCP (ms) (Use com notificações de progresso)	60000
`MCP_PROXY_FULL_ADDRESS`	Defina isso se você estiver executando o MCP Inspector Proxy em um endereço não padrão. Exemplo: http://10.1.1.22:5577	""
`MCP_AUTO_OPEN_ENABLED`	Habilitar abertura automática do navegador quando o inspector inicia (funciona com autenticação habilitada). Apenas como variável de ambiente, não configurável no navegador.	true

Essas configurações podem ser ajustadas em tempo real através da UI e persistirão entre sessões.

O inspector também suporta arquivos de configuração para armazenar configurações para diferentes servidores MCP. Isso é útil ao trabalhar com vários servidores ou configurações complexas:

npx @modelcontextprotocol/inspector --config path/to/config.json --server everything

Exemplo de arquivo de configuração de servidor:

{
  "mcpServers": {
    "everything": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-everything"],
      "env": {
        "hello": "Hello MCP!"
      }
    },
    "my-server": {
      "command": "node",
      "args": ["build/index.js", "arg1", "arg2"],
      "env": {
        "key": "value",
        "key2": "value2"
      }
    }
  }
}

Dica: Você pode facilmente gerar este formato de configuração usando os botões Server Entry e Servers File na UI do Inspector, conforme descrito na seção Exportação de Arquivo de Servidores acima.

Você também pode definir o tipo inicial de transport, serverUrl, serverCommand e serverArgs via parâmetros de consulta, por exemplo:

http://localhost:6274/?transport=sse&serverUrl=http://localhost:8787/sse
http://localhost:6274/?transport=streamable-http&serverUrl=http://localhost:8787/mcp
http://localhost:6274/?transport=stdio&serverCommand=npx&serverArgs=arg1%20arg2

Você também pode definir configurações iniciais via parâmetros de consulta, por exemplo:

http://localhost:6274/?MCP_SERVER_REQUEST_TIMEOUT=10000&MCP_REQUEST_TIMEOUT_RESET_ON_PROGRESS=false&MCP_PROXY_FULL_ADDRESS=http://10.1.1.22:5577

Observe que se tanto o parâmetro de consulta quanto o item correspondente no localStorage estiverem definidos, o parâmetro de consulta terá precedência.

A partir deste repositório

Se você está trabalhando no próprio inspector:

Modo de desenvolvimento:

npm run dev

Nota para usuários Windows: No Windows, use o seguinte comando em vez disso:
npm run dev:windows

Modo de produção:

npm run build
npm start

Modo CLI

O modo CLI permite interação programática com servidores MCP a partir da linha de comando, ideal para scripts, automação e integração com assistentes de codificação. Isso cria um ciclo de feedback eficiente para o desenvolvimento de servidores MCP.

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

O modo CLI suporta a maioria das operações em ferramentas, recursos e prompts. Alguns exemplos:

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

# With config file
npx @modelcontextprotocol/inspector --cli --config path/to/config.json --server myserver

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

# Call a specific tool
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/call --tool-name mytool --tool-arg key=value --tool-arg another=value2

# List available resources
npx @modelcontextprotocol/inspector --cli node build/index.js --method resources/list

# List available prompts
npx @modelcontextprotocol/inspector --cli node build/index.js --method prompts/list

# Connect to a remote MCP server (default is SSE transport)
npx @modelcontextprotocol/inspector --cli https://my-mcp-server.example.com

# Connect to a remote MCP server (with Streamable HTTP transport)
npx @modelcontextprotocol/inspector --cli https://my-mcp-server.example.com --transport http

# Call a tool on a remote server
npx @modelcontextprotocol/inspector --cli https://my-mcp-server.example.com --method tools/call --tool-name remotetool --tool-arg param=value

# List resources from a remote server
npx @modelcontextprotocol/inspector --cli https://my-mcp-server.example.com --method resources/list

Modo UI vs Modo CLI: Quando Usar Cada Um

Caso de Uso	Modo UI	Modo CLI
Desenvolvimento de Servidor	Interface visual para teste interativo e depuração durante o desenvolvimento	Comandos scriptáveis para testes rápidos e integração contínua; cria ciclos de feedback com assistentes de codificação de IA como Cursor para desenvolvimento rápido
Exploração de Recursos	Navegador interativo com navegação hierárquica e visualização JSON	Listagem e leitura programática para automação e scripts
Teste de Ferramentas	Entrada de parâmetros baseada em formulário com visualização de resposta em tempo real	Execução de ferramentas via linha de comando com saída JSON para scripts
Engenharia de Prompts	Amostragem interativa com respostas em streaming e comparação visual	Processamento em lote de prompts com saída legível por máquina
Depuração	Histórico de solicitações, erros visualizados e notificações em tempo real	Saída JSON direta para análise de logs e integração com outras ferramentas
Automação	N/A	Ideal para pipelines de CI/CD, processamento em lote e integração com assistentes de codificação
Aprendendo MCP	Interface visual rica ajuda novos usuários a entender as capacidades do servidor	Comandos simplificados para aprendizado focado de endpoints específicos

Licença

Este projeto é licenciado sob a Licença MIT—veja o arquivo LICENSE para detalhes.