Executando Model Context Protocol localmente

Use esta página para executar o servidor MCP de previsão do tempo extraído no seu computador e chamar sua ferramenta de previsão a partir do MCP Inspector. Duas coisas diferem do que você pode esperar: o script de inicialização precisa de uma ferramenta que o projeto esqueceu de listar, e o servidor nunca abre uma página própria. Ele se comunica com o programa que o inicia, através da entrada e saída do terminal, para que você o teste com o Inspector, que o inicia para você e oferece uma página interativa.

O que você precisa primeiro

Instale Node.js 24, que inclui npm. O MCP Inspector precisa do Node 22.19 ou mais recente, e o Node 24 está bem além disso.

Verifique a versão. A sua pode ser mais recente:

$ node --version
v24.18.0

Você não precisa de chave de API nem de arquivo .env: os dados de previsão estão escritos no próprio código do servidor.

JunoO que você precisa primeiro Instale o Node 24 e verifique que node --version mostra uma versão começando com 24 ou superior. Essa é a lista completa: nenhuma chave, nenhum arquivo .env.

JunoO que você precisa primeiro O servidor em si rodaria em versões mais antigas do Node. A versão importa porque o mesmo Node também executa o Inspector, a ferramenta que você usa para testar, e a versão atual do Inspector precisa do 22.19 ou mais recente.

JunoO que você precisa primeiro No Node 22 anterior à versão 22.19, npx não rejeita o Inspector: ele silenciosamente escolhe a versão mais recente que aceita aquele Node, a versão 1 descontinuada. Então o problema aparece como um Inspector diferente, não como um erro.

Instale os pacotes e adicione tsx

Abra um terminal na pasta do projeto extraído. É aquela que contém package.json e server.ts:

$ cd path-to-your-extracted-project

O script de inicialização do projeto executa tsx server.ts. tsx é a ferramenta que executa um arquivo TypeScript diretamente, mas package.json não a lista, então uma instalação comum a omite e npm start para com sh: tsx: command not found. Instale os pacotes listados e depois adicione tsx:

$ npm ci
added 91 packages, and audited 92 packages in 3s
…
$ npm install --save-dev tsx
added 3 packages, and audited 95 packages in 7s
…

O npm pode também reportar vulnerabilidades e sugerir npm audit fix. Deixe para depois. Pode também exibir um aviso começando com npm warn allow-scripts e mencionando esbuild; isso não impede tsx de funcionar.

JunoInstale os pacotes e adicione tsx Na pasta com package.json, execute npm ci e depois npm install --save-dev tsx. Cada um relata quantos pacotes adicionou.

Se o npm disser que não consegue encontrar package.json, você está na pasta errada.

JunoInstale os pacotes e adicione tsxnpm ci instala exatamente o que o arquivo de lock enviado registra, e tsx não está nele. --save-dev o adiciona a package.json e ao arquivo de lock, então o script de inicialização o encontra em node_modules a partir de agora.

JunoInstale os pacotes e adicione tsx Registrar tsx no projeto, em vez de instalá-lo globalmente, é o que permite que um cliente desktop inicie este servidor depois com npm exec de qualquer pasta: a ferramenta viaja com o projeto em vez de depender do PATH de alguém.

Verifique se o servidor inicia

Inicie o servidor uma vez por conta própria:

$ npm start

> [email protected] start
> tsx server.ts

🌤️  Weather MCP Server Started!
🛠️  Tool: getWeatherDataByCityName
📚 Resource: weather://cities
🏙️  Supported Cities: São Paulo, Rio de Janeiro
✅ Server ready!

Depois de Server ready! o terminal fica silencioso. Esse é um servidor funcionando: ele está esperando que um programa lhe envie uma mensagem, e nunca imprime um endereço para abrir. Interrompa com Ctrl+C antes de iniciar o Inspector.

JunoVerifique se o servidor inicia Execute npm start e espere por Server ready!. Nada mais acontecerá, e nada deve: pressione Ctrl+C e passe para o Inspector.

JunoVerifique se o servidor inicia Um servidor MCP sobre entrada e saída padrão não tem porta. Ele lê requisições de qualquer programa que o iniciou, então seu terminal pode iniciá-lo mas não pode conversar com ele. Esse é o trabalho do Inspector.

JunoVerifique se o servidor inicia As cinco linhas de status vão para o erro padrão de propósito: a saída padrão é reservada para mensagens do protocolo, e um console.log extraviado ali quebraria a conexão com qualquer cliente.

Chame a ferramenta de previsão no MCP Inspector

Da mesma pasta do projeto, execute o MCP Inspector oficial, seguido pelo comando que inicia seu servidor:

$ npx @modelcontextprotocol/inspector npx tsx server.ts

Na primeira vez, npx pergunta antes de fazer o download do Inspector. Verifique que o pacote é @modelcontextprotocol/inspector e digite y:

Need to install the following packages:
@modelcontextprotocol/[email protected]
Ok to proceed? (y)

O Inspector imprime seu endereço e o abre no seu navegador:

Starting MCP inspector...
…
MCP Inspector Web is up and running at:
   http://127.0.0.1:6274?MCP_INSPECTOR_API_TOKEN=…
…
Opening browser...

Se nenhum navegador abrir, copie o endereço completo, token incluído, em um.

A página lista um servidor, npx, marcado como Disconnected. Ignore a nota Read-only session acima dele. Ative a chave ao lado do servidor: o Inspector inicia seu servidor e o rótulo muda para Connected. Depois:

1. Abra Tools no topo e selecione getWeatherDataByCityName.
2. Digite São Paulo no campo city e clique em Execute Tool.
3. O resultado aparece embaixo de Results:

{
  "temp": "22°C",
  "forecast": "Parcialmente nublado com uma brisa"
}

Rio de Janeiro também funciona. Qualquer outra cidade retorna a mensagem Weather data not available for this city do curso, o que significa que a ferramenta está funcionando como esperado. O capítulo sobre uso de ferramentas explica o que uma ferramenta assim oferece a um modelo.

Resources lista weather://cities, mas selecioná-lo mostra Read Error e Invalid URL. Isso vem de como o código da lição registra o recurso, não da sua configuração; a ferramenta é o que você deve testar.

Quando terminar, pressione Ctrl+C no terminal. Isso interrompe o Inspector e o servidor que ele iniciou.

JunoChame a ferramenta de previsão no MCP Inspector Execute o comando do Inspector, digite y se o npx perguntar, e ative o servidor na página que abre. Depois vá para Tools, escolha a ferramenta de previsão, digite São Paulo e clique em Execute Tool.

Se o rótulo disser Failed em vez de Connected, abra a aba Console do Inspector à direita e procure pela linha começando com Error.

JunoChame a ferramenta de previsão no MCP Inspector Aqui o Inspector é o cliente. Tudo depois do nome do seu pacote é o comando que ele executa para iniciar seu servidor, então ele inicia tsx server.ts por conta própria e conversa com ele através da entrada e saída daquele processo. A página é do próprio Inspector; seu servidor ainda não tem uma.

JunoChame a ferramenta de previsão no MCP Inspector O recurso falha porque o SDK lê os argumentos de server.resource como nome, endereço e depois opções. A lição passa o endereço primeiro e uma descrição segundo, então o recurso é listado sob o nome weather://cities com List of supported cities como seu endereço, o que não é uma URL, e a função de leitura nunca é registrada.

Conecte outro cliente MCP

Um cliente MCP desktop também inicia o servidor, mas a partir de sua própria pasta de trabalho, então precisa de caminhos absolutos. Copie o caminho absoluto da pasta do projeto extraído e então dê ao cliente este comando e estes argumentos, com ambos os caminhos de exemplo substituídos:

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

--prefix diz ao npm qual tsx do projeto usar, de onde quer que o cliente inicie. Mantenha cada argumento como um item separado, para que um caminho contendo espaços permaneça um valor, e não adicione URL ou porta.

Cada cliente nomeia esses campos de forma diferente, então coloque o comando e os argumentos onde suas instruções de configuração MCP dizem, e reinicie o cliente. Você não precisa de outro download: este é o servidor que você já testou. O capítulo sobre agentes cobre o loop que um cliente executa quando seu modelo usa uma ferramenta como esta.

JunoConecte outro cliente MCP Defina o comando como npm, adicione os seis argumentos com o caminho do seu projeto nos dois lugares, e reinicie o cliente.

O servidor já funcionava no Inspector, então se o cliente não conseguir alcançá-lo, verifique os caminhos nas suas configurações primeiro.

JunoConecte outro cliente MCP O cliente executa o mesmo servidor, mas através de npm --prefix, então o lançamento funciona a partir da pasta do próprio cliente: --prefix escolhe o projeto, e exec -- tsx executa seu arquivo de servidor.

JunoConecte outro cliente MCP Clientes desktop raramente herdam o PATH do seu terminal, então um comando bare tsx funciona apenas onde uma instalação global acontece estar visível. Passar por npm --prefix vincula o lançamento ao tsx registrado neste projeto. Se o cliente disser que não consegue encontrar npm, use o caminho completo que which npm imprime como o comando.

Resolução de problemas

npm start diz sh: tsx: command not found: tsx ainda não está instalado no projeto. Execute npm install --save-dev tsx na pasta do projeto. Para um cliente desktop, também verifique se seu comando é npm e se seus argumentos começam com --prefix e o caminho absoluto do projeto.

O Inspector diz @modelcontextprotocol/inspector v1 is deprecated: Seu Node é mais antigo que 22.19, então o npx baixou o Inspector antigo. Instale o Node 24, abra um novo terminal, verifique node --version e execute o comando do Inspector novamente.

O servidor mostra Failed e a aba Console do Inspector diz Cannot find module terminando em server.ts: O Inspector foi iniciado fora da pasta do projeto. Interrompa com Ctrl+C, cd para a pasta que contém server.ts e execute o comando novamente.

JunoResolução de problemas Combine o que você vê com um título em negrito acima. Quando o Inspector mostra Failed, o motivo está na aba Console dele, não no seu terminal.

JunoResolução de problemas Mantenha três etapas separadas: npm encontrando tsx, npx escolhendo um Inspector que seu Node pode executar, e o Inspector iniciando seu servidor. Cada uma falha em um lugar diferente: o terminal, o terminal, depois a aba Console do Inspector.

JunoResolução de problemas O Inspector coleta o erro padrão do servidor em sua aba Console, por isso um arquivo faltante ou uma falha na inicialização aparece lá enquanto o terminal executando o Inspector permanece silencioso.