Executando Model Context Protocol localmente

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

O que você precisa primeiro

Instale o Node 24. MCP Inspector define uma versão mínima de Node (22.19 no momento da escrita); Node 24 está acima desse mínimo, enquanto um release LTS mais antigo pode não iniciar a UI de teste.

Este projeto não requer uma chave de API ou arquivo .env. Clientes MCP iniciam o servidor como um processo filho, então a versão do Node e o ambiente em que ele executa vêm de quem o inicia na sua máquina.

JunoO que você precisa primeiro Instale o Node 24, e essa é toda a lista de requisitos: sem chave de API, sem arquivo .env. A surpresa é que este servidor nunca abre uma página web; fica esperando silenciosamente um cliente, o que me confundiu completamente na primeira vez que rodei um.

JunoO que você precisa primeiro Node 24 satisfaz a versão mínima de Node tanto para o servidor TypeScript quanto para o Inspector, então uma instalação cobre ambos. O projeto se comunica via stdio em vez de uma porta HTTP, então não espere por uma URL que nunca virá.

JunoO que você precisa primeiro O cliente inicia este servidor como um processo filho, então a versão do Node e o ambiente vêm de quem o inicia, não da pasta do servidor. É por isso que a instalação do Node no lado do cliente importa mesmo que o servidor em si não precise de chave nem porta. "O servidor não precisa de nada" permanece verdadeiro apenas enquanto o cliente que o inicia executa uma versão suportada de Node.

Instale e conserte 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 "start": "tsx server.ts" extraído espera.

Você pode iniciar o servidor stdio diretamente:

$ npm start

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

JunoInstale e conserte o servidor Execute npm ci, adicione a ferramenta tsx que falta e que executa arquivos TypeScript, depois tente npm start. Quando o terminal ficar silencioso, nada está errado: o servidor está esperando um cliente para conversar com ele. Reiniciei o meu três vezes antes de alguém me contar isso!

JunoInstale e conserte o servidor O script de início do pacote já espera tsx, então registrá-lo como uma dependência de desenvolvimento é o conserto mais simples e reproduzível. E um processo stdio esperando é um início bem-sucedido, não uma travada; resista à vontade de ficar reiniciando.

JunoInstale e conserte o servidornpm ci instalou apenas o que o lockfile enviado registrou, e tsx não estava nele. Instalar com --save-dev escreve tsx em package.json e no lockfile. Essa dependência registrada é o que permite que um cliente depois inicie o servidor com npm exec de qualquer diretório. Consertos registrados no manifesto sobrevivem; os que existem apenas no histórico do seu shell não.

Teste com MCP Inspector

Na mesma pasta do projeto, execute o MCP Inspector oficial:

$ npx @modelcontextprotocol/inspector npx tsx server.ts

O primeiro npx baixa e inicia o Inspector, e pode pedir permissão para essa instalação de uma única vez; confirme que o pacote é @modelcontextprotocol/inspector antes de aceitar, e para uso repetível em equipe, fixe uma versão revisada em vez de depender indefinidamente do release mais novo. O Inspector então inicia seu servidor com npx tsx server.ts como seu processo filho de stdio. Sua UI web executa em sua própria porta local, separada da conexão stdio com o servidor. Abra a URL local impressa no terminal se não abrir automaticamente.

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 assim oferece a um modelo. Deixe o terminal aberto durante os testes, depois pare o Inspector e o servidor filho com Ctrl+C.

JunoTeste com MCP Inspector Execute o comando do Inspector, abra sua URL local, conecte, depois liste e chame a ferramenta e recurso do curso. Verifique o nome do pacote antes de aceitar o download, da mesma forma que você verifica um endereço web antes de abri-lo.

JunoTeste com MCP Inspector Inspector é o cliente aqui e inicia server.ts como seu filho de stdio. Verifique descoberta antes de invocação: se a lista de ferramentas estiver vazia, chamar qualquer coisa é inútil. Mantenha o terminal aberto e pare ambos os processos com Ctrl+C.

JunoTeste com MCP Inspector O comando interno é o mesmo contrato de processo que a próxima seção oferece aos clientes desktop, então conseguir que funcione aqui significa que a configuração do cliente depois é copiar valores em vez de fazer debug. E a porta de UI web do Inspector é separada do transporte stdio: uma porta ocupada bloqueia a UI web enquanto o servidor em si continua rodando.

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 npm usar a dependência tsx instalada naquele projeto mesmo quando o cliente desktop inicia de outro diretório de trabalho. Um cliente configurado para rodar 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 costuma ser diferente 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 via stdio.

Conectar servidores como este é como clientes desktop oferecem ferramentas aos seus modelos; o capítulo de agentes cobre o loop que usa essas ferramentas.

Os formatos de configuração do 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 após alterar sua configuração. Você não precisa de outro download de projeto: conecte-o ao servidor extraído que já testou.

JunoConecte outro cliente MCP Defina o comando como npm, adicione os argumentos documentados com ambos os caminhos absolutos preenchidos, depois reinicie o cliente. Você está reutilizando o mesmo servidor extraído que o Inspector testou, então se funcionou lá, o lado do servidor já está provado.

JunoConecte outro cliente MCP A sintaxe de configuração do cliente varia, mas o contrato de processo permanece o mesmo: npm --prefix seleciona o projeto, e exec -- tsx inicia seu servidor TypeScript via stdio. Mapeie essas peças para quaisquer nomes de campos que o cliente use.

JunoConecte outro cliente MCP Um cliente configurado para rodar tsx por conta própria funciona apenas em máquinas que já têm uma instalação global, e clientes desktop raramente herdam o PATH do seu terminal. O comando npm --prefix e exec fixa o lançamento à dependência registrada do projeto em vez disso. Configurações que dependem do ambiente de lançamento são as que falham na segunda máquina.

Resolução de problemas

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

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

npm start parece travar: Isso é esperado para um servidor stdio esperando um cliente. Use 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.

JunoResolução de problemas Instale tsx se estiver faltando, passe para Node 24 se o Inspector se recusar a iniciar, e lembre que um servidor silencioso é um servidor esperando, não um quebrado. Quase todo problema nesta página é um desses três.

JunoResolução de problemas Separe as três camadas de falha: a instalação de tsx, a versão mínima de Node do Inspector, e a conexão stdio em si. Verifique a saída do terminal antes de assumir que o registro de ferramentas falhou; o erro real geralmente já está impresso lá.

JunoResolução de problemas Rastreie a cadeia em ordem: processo Inspector externo, comando de lançamento filho, execução TypeScript, inicialização MCP. Qualquer etapa dessa cadeia pode deixar a lista de ferramentas vazia, e o terminal diz qual quebrou se você ler antes de reiniciar as coisas. Reiniciar primeiro é o instinto comum, e raramente diz algo.