Executando Model Context Protocol localmente

Use esta página para executar o servidor MCP TypeScript extraído e experimentar sua ferramenta de clima e recurso no MCP Inspector. O servidor se comunica com seu cliente por meio de entrada e saída padrão, então fica aguardando um cliente em vez de abrir uma página de projeto ou porta de aplicação.

O que você precisa primeiro

Instale Node 24. O MCP Inspector requer Node 22.19 ou mais recente, então Node 24 atende esse requisito mínimo, enquanto uma release LTS mais antiga pode não iniciar a interface de teste.

Este projeto não exige uma chave de API ou arquivo .env. Clientes MCP iniciam o servidor como um processo filho, então a versão de Node com a qual ele executa vem de quem o inicia na sua máquina: seu terminal, Inspector ou um cliente desktop.

JunoO que você precisa primeiro Instale Node 24, e pronto: sem chave de API, sem arquivo .env.

Espere uma surpresa: este servidor nunca abre uma página web. Ele fica quieto aguardando um cliente conversar com ele.

JunoO que você precisa primeiro Node 24 atende tanto o servidor TypeScript quanto a versão mínima de Node do Inspector, então uma instalação é suficiente.

O projeto se comunica por stdio em vez de uma porta HTTP, então não espere por uma URL de servidor. A única URL que você abrirá é a do Inspector.

JunoO que você precisa primeiro O cliente inicia este servidor como um processo filho, então a versão de Node e o ambiente vêm de quem o inicia, não da pasta do servidor.

Por isso a instalação de Node no lado que inicia o servidor importa, mesmo que o servidor não precise de chave e não abra nenhuma porta.

Instalar e consertar o servidor

Abra um terminal na pasta do servidor extraído contendo package.json:

$ cd path-to-your-downloaded-project
$ npm ci
$ npm install --save-dev tsx

O comando final registra tsx, a ferramenta que executa arquivos TypeScript, que o script extraído "start": "tsx server.ts" espera.

Você pode iniciar o servidor stdio diretamente:

$ npm start

Ele fica aguardando um cliente MCP em vez de imprimir uma URL de navegador. Pare com Ctrl+C antes de iniciar o Inspector.

JunoInstalar e consertar o servidor Execute npm ci, adicione a ferramenta tsx que falta e que executa arquivos TypeScript, depois tente npm start.

Quando o terminal fica quieto, nada está errado: o servidor está aguardando um cliente. Pare com Ctrl+C antes de abrir o Inspector.

JunoInstalar e consertar o servidor O script de start já chama tsx, então registrá-lo como dependência de desenvolvimento é o menor conserto que funciona.

Um processo stdio aguardando é um início bem-sucedido, não um travamento, então não há necessidade de reiniciá-lo.

JunoInstalar e consertar o servidornpm ci instala apenas o que o arquivo de lockfile enviado registra, e tsx não está nele. Instalar com --save-dev escreve tsx em package.json e no lockfile.

Essa dependência registrada é o que permite um cliente desktop iniciar o servidor depois com npm exec de qualquer diretório, sem tocar em server.ts.

Teste com MCP Inspector

A partir da mesma pasta do projeto, execute o MCP Inspector oficial:

$ npx @modelcontextprotocol/inspector npx tsx server.ts

O primeiro npx baixa e inicia o Inspector. O Inspector então inicia seu servidor com npx tsx server.ts como seu processo filho stdio. A interface web do Inspector executa em sua própria porta local, separada da conexão stdio para o servidor. Abra a URL local impressa no terminal se ela não abrir automaticamente.

Aprove deliberadamente o download de pacote único

npx pode pedir permissão para instalar o MCP Inspector. Confirme que o pacote é @modelcontextprotocol/inspector antes de aceitar. Para uso repetível em equipe, fixe uma versão revisada em vez de depender indefinidamente da release mais recente.

No Inspector, conecte ao servidor, liste suas ferramentas e recursos, e chame a ferramenta de clima com uma das entradas usadas no curso. O capítulo de uso de ferramentas explica o que uma definição de ferramenta como esta oferece a um modelo. Deixe o terminal aberto durante o teste, depois pare o Inspector e o servidor filho com Ctrl+C.

JunoTeste com MCP Inspector Execute o comando do Inspector, abra a URL local que ele imprime e conecte. Depois liste as ferramentas e recursos e chame a ferramenta de clima.

Se npx pedir para instalar um pacote, verifique que o nome é @modelcontextprotocol/inspector antes de aceitar.

JunoTeste com MCP Inspector O Inspector é o cliente aqui, e inicia server.ts como seu filho stdio.

Verifique a descoberta antes da invocação: se a lista de ferramentas está vazia, chamar qualquer coisa não funcionará, então procure no terminal primeiro. Deixe o terminal aberto e pare ambos os processos com Ctrl+C.

JunoTeste com MCP Inspector O npx externo executa o Inspector e o comando interno define o transporte do servidor filho. A porta da interface web do Inspector é separada daquele pipe stdio.

Quando o comando interno funciona aqui, a configuração do cliente desktop na próxima seção é o mesmo lançamento escrito como comando e argumentos. Fixe uma versão revisada do Inspector para uso repetível em equipe.

Conecte outro cliente MCP

Um cliente desktop precisa de um comando executável e argumentos para iniciar o mesmo servidor stdio. Primeiro, copie os caminhos absolutos para a pasta do projeto extraído e seu arquivo server.ts. Configure o cliente com este contrato de processo, substituindo ambos os caminhos de exemplo:

command: npm
arguments:
  - --prefix
  - /absolute/path/to/project
  - exec
  - --
  - tsx
  - /absolute/path/to/project/server.ts

O valor --prefix faz o npm usar a dependência tsx instalada naquele projeto mesmo quando o cliente desktop é iniciado de outro diretório de trabalho. Um cliente configurado para executar tsx por conta própria, sem npm --prefix na frente, depende em vez disso de uma instalação global e do PATH do cliente, que frequentemente difere do seu terminal. Mantenha cada argumento como um item separado para que caminhos contendo espaços permaneçam um valor. Não adicione uma URL ou porta: este servidor se comunica por stdio.

Formatos de configuração de cliente diferem, então mapeie esse comando e esses argumentos para os campos nas instruções de configuração MCP atuais do cliente. Reinicie o cliente depois de alterar sua configuração. Você não precisa de outro download de projeto: conecte-o ao servidor extraído que você já testou. O capítulo de agentes cobre o loop que um cliente executa quando seu modelo usa ferramentas como esta.

JunoConecte outro cliente MCP Defina o comando como npm, adicione os argumentos acima com ambos os caminhos absolutos preenchidos, depois reinicie o cliente.

Você está reutilizando o servidor que o Inspector já testou, então se funcionou lá, o lado do servidor está bem e qualquer problema está nas configurações do cliente.

JunoConecte outro cliente MCP A sintaxe de configuração varia entre clientes, mas o contrato de processo permanece o mesmo: npm --prefix seleciona o projeto, e exec -- tsx inicia seu servidor TypeScript por stdio.

Mapeie essas peças para qualquer que seja o nome de campo que seu cliente use.

JunoConecte outro cliente MCP Clientes desktop raramente herdam seu PATH de terminal, então um comando tsx simples funciona apenas onde uma instalação global acontece estar visível.

Passar npm com o prefixo, o separador exec, o executor e o caminho absoluto do servidor como argumentos separados vincula o lançamento à dependência registrada do próprio projeto em vez disso.

Solução de problemas

tsx: command not found: Execute npm install --save-dev tsx na pasta do projeto. Para um cliente desktop, também confirme que seu comando é npm e seus argumentos começam com --prefix seguido pelo caminho absoluto do projeto.

Inspector rejeita a versão de Node: Instale Node 24, verifique com node --version e reabra o terminal.

npm start parece travar: Isso é esperado para um servidor stdio aguardando um cliente. Use o Inspector para interagir com ele.

Inspector não mostra ferramentas: Verifique o terminal para erros de TypeScript ou conexão e confirme que o comando final termina com npx tsx server.ts.

JunoSolução de problemas Instale tsx se estiver faltando, mude para Node 24 se o Inspector recusar iniciar, e lembre que um servidor silencioso está aguardando, não quebrado.

A maioria dos problemas nesta página é um desses três.

JunoSolução de problemas Mantenha três camadas de falha separadas: a instalação tsx, a versão mínima de Node do Inspector e a própria conexão stdio.

Leia o terminal antes de assumir que o registro de ferramentas falhou; o erro real geralmente já está impresso lá.

JunoSolução de problemas Rastreie a cadeia em ordem: o processo externo do Inspector, o comando de lançamento filho, execução de TypeScript, depois inicialização de MCP.

Qualquer elo pode deixar a lista de ferramentas vazia, e a saída do terminal nomeia o que quebrou, então leia-a antes de reiniciar qualquer coisa.