Construindo um Servidor MCP Personalizado com Node.js

Um guia prático para construir seu próprio servidor MCP para enriquecer as respostas de ferramentas de IA com contexto adicional

Construindo um servidor MCP personalizado com Node.js, você consegue mudar totalmente o patamar das suas aplicações de IA. Nos últimos meses, o Model Context Protocol (MCP) ganhou muita popularidade no ecossistema de inteligência artificial. Mas afinal, o que é o MCP e por que você precisa dele? Simplificando, ele é um protocolo aberto que padroniza como as aplicações fornecem contexto adicional a LLMs (modelos de linguagem de grande escala), funcionando como um “tradutor universal” que conecta ferramentas de IA a diversas fontes de dados locais e remotas.

Este artigo fornece um exemplo prático de como construir um servidor MCP personalizado usando Node.js, que se conecta a uma API de previsão do tempo e retorna os dados meteorológicos para o modelo de IA. Vamos começar!

Pré-requisitos

Antes de começar, você precisará do seguinte:

• Node.js e npm instalados na sua máquina

• Uma chave de API do OpenWeatherMap — você pode se inscrever em OpenWeatherMap

• Uma ferramenta de IA capaz de se conectar a servidores MCP — eu usei o Claude Desktop para este exemplo, mas há muitas outras ferramentas disponíveis

Passo 1: Configuração do Projeto

Primeiro, crie um novo diretório para o seu projeto e inicialize-o com o npm. Em seguida, crie um arquivo chamado index.js, que conterá a lógica do servidor MCP:

mkdir weather-mcp-server
cd weather-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod axios dotenv
npm install --save-dev typescript @types/node
touch index.js

Passo 2: Construindo o Servidor MCP

Agora que o projeto está configurado, vamos construir o servidor MCP. Esta implementação é um servidor relativamente simples que se conecta a uma API de previsão do tempo e retorna os dados para o modelo de IA. Se você está se perguntando, “o que é o MCP e por que ele precisa de um servidor?”, o próximo trecho de código ajudará a esclarecer.

Comece importando os pacotes necessários no arquivo index.js:

import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import axios from "axios";
import dotenv from "dotenv";

O servidor usa o pacote @modelcontextprotocol/sdk para lidar com o protocolo MCP e se comunicar com a ferramenta de IA. O pacote zod é uma biblioteca de validação de esquemas que será usada para validar os parâmetros de entrada para a chamada da API. O pacote axios é usado para fazer as chamadas à API para o OpenWeatherMap. Por fim, o pacote dotenv é utilizado para carregar a chave de API do OpenWeatherMap a partir de um arquivo .env.

Adicione o seguinte código ao arquivo index.js:

// Criar instância do servidor
const server = new McpServer({
  name: "weather-service",
  version: "1.0.0"
});

// Registrar ferramentas de previsão do tempo
server.registerTool("get-forecast", 
  {
    title: "Previsão do Tempo",
    description: "Obter a previsão do tempo para uma cidade",
    inputSchema: {
      city: z.string(),
      country: z.string()
    },
    outputSchema: {
      weather: z.object({
        description: z.string(),
        temperature: z.number(),
        humidity: z.number(),
        windSpeed: z.number(),
      }),
      location: z.object({
        city: z.string(),
        country: z.string()
      })
    }
  },
  async ({ city, country }) => {
    try {
      // Usar o endpoint de previsão do tempo para obter dados atuais
      const response = await axios.get(
        `https://api.openweathermap.org/data/2.5/weather?q=${city},${country}&appid=${process.env.WEATHER_API_KEY}&units=metric`
      );
      
      const weatherData = {
        weather: {
          description: response.data.weather[0].description,
          temperature: response.data.main.temp,
          humidity: response.data.main.humidity,
          windSpeed: response.data.wind.speed
        },
        location: {
          city: response.data.name,
          country: country
        }
      };
      
      return {
        content: [
          { 
            type: "text", 
            text: JSON.stringify(weatherData) 
          }
        ]
      };
    } catch (error) {
      return {
        content: [
          { 
            type: "text", 
            text: `Erro ao buscar dados do tempo: ${error.message}` 
          }
        ]
      };
    }
  }
);

// Função principal
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Servidor MCP de Meteorologia rodando na stdio");
}

main().catch((error) => {
  console.error("Erro fatal na main():", error);
  process.exit(1);
});

Neste código, importamos os pacotes necessários e criamos uma instância da classe McpServer. Então registramos uma tool chamada get-forecast, que aceita os parâmetros city e country. A função tool faz uma chamada à API do OpenWeatherMap e retorna os dados meteorológicos para o modelo de IA. Finalmente, iniciamos o servidor usando a função main(), passando um StdioServerTransport como mecanismo de transporte para enviar e receber mensagens.

Passo 3: Executando o Servidor MCP

Antes de executar o servidor, é necessário adicionar um script start ao arquivo package.json:

"scripts": {
  "start": "node index.js"
},

Para executar o servidor, você precisa fornecer a chave de API do OpenWeatherMap. Você pode usar um arquivo .env para armazenar a chave de API e carregá-la usando o pacote dotenv. Crie um arquivo .env no diretório raiz do seu projeto e adicione a seguinte linha:

WEATHER_API_KEY=sua_chave_de_api_aqui

Agora, para configurar o servidor MCP com uma ferramenta de IA, por exemplo, o Claude Desktop, é preciso editar o arquivo de configuração do Claude Desktop. Você pode encontrá-lo em:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: C:\Users\seu_usuario\AppData\Roaming\Claude\claude_desktop_config.json

Adicione a seguinte configuração ao arquivo claude_desktop_config.json:

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": [
        "caminho/absoluto/para/seu/index.js"
      ],
      "env": {
        "WEATHER_API_KEY": "sua_chave_de_api_aqui"
      }
    }
  }
}

Uma vez configurado, você pode iniciar o Claude Desktop e o servidor MCP será carregado automaticamente.

Passo 4: Testando o Servidor MCP

Agora que seu servidor está configurado, você pode testá-lo fazendo uma pergunta ao modelo de IA que exija dados meteorológicos. Por exemplo, você pode perguntar: “Como está o tempo em Londres, Reino Unido?”. O Claude Desktop usará seu servidor MCP personalizado, que buscará os dados através da sua tool get-forecast registrada, chamará a API do OpenWeatherMap e retornará os resultados ao modelo.

Neste exemplo, o Claude Desktop conecta-se ao servidor MCP personalizado e usa a tool registrada get-forecast para buscar os dados meteorológicos em tempo real e apresentá-los na conversa. Se o servidor não estiver em execução ou houver um erro, o modelo de IA indicará que não pode acessar os dados.

Dicas Extras para Construir Servidores MCP com Node.js

A seguir, um guia complementar com boas práticas, recursos úteis e armadilhas comuns, dividido em básico, intermediário e avançado para ajudar você a evoluir seu servidor MCP. E que você pode usar para melhorar este exemplo ou um projeto próprio como desafio de programação:

🟢 Básico

1. Use ES Modules por padrão
   O código do artigo utiliza import. Para que funcione sem problemas, adicione "type": "module" ao seu package.json ou use a extensão .mjs. Isso evita erros de sintaxe ao rodar com Node.js.

2. Carregue variáveis de ambiente antes de tudo
   Chame dotenv.config() no topo do arquivo, antes de instanciar qualquer coisa. Se a chave da API não estiver definida, emita um aviso claro e encerre o processo.

   import dotenv from "dotenv";
   dotenv.config();
   if (!process.env.WEATHER_API_KEY) {
     console.error("ERRO: WEATHER_API_KEY não definida no arquivo .env");
     process.exit(1);
   }

3. Teste localmente com o MCP Inspector
   Em vez de depender apenas do Claude Desktop, use o MCP Inspector (ferramenta oficial) para simular chamadas ao seu servidor diretamente no terminal. É muito mais rápido para depurar.

   english-interview-debugger.sh

   $ grep -r "senior_dev_communication" ./career

   [CRITICAL_ERROR] Código sênior detectado, mas fluência falhou no runtime.
   Motivo: Travou na hora de explicar a arquitetura (System Design) em inglês para o gringo.

   O mercado internacional não quer um robô de gramática. Quer um dev que saiba defender uma tomada de decisão técnica sob pressão. Destrave sua conversão na Preply com aulas particulares focadas em TI.

   $ ./fix-english.sh --target=remote-job

   Achar Professor Particular ➔

4. Padronize as respostas de erro
   O modelo de IA interpreta a resposta content como texto. Em caso de falha, retorne um JSON com detalhes úteis, incluindo um campo error e uma mensagem amigável. Isso ajuda o modelo a explicar o problema ao usuário final.

🟡 Intermediário

1. Adicione múltiplas ferramentas e recursos
   Além de get-forecast, você pode registrar outras tools (ex.: get-alerts, get-history) e até resources (como weather://current/{city}) usando server.registerResource(). Isso enriquece o contexto disponível para o modelo.

2. Validação robusta com Zod
   Amplie os esquemas para incluir validações mais finas (ex.: código do país com duas letras, nome da cidade sem números). Use .refine() ou .regex() para garantir dados limpos antes de chamar a API externa.

3. Implemente um sistema de logging
   Substitua console.error por uma biblioteca como pino ou winston. Registre cada chamada de ferramenta com timestamps, parâmetros e status. Isso facilita depuração e auditoria em produção.

4. Cache inteligente
   Para evitar estourar limites de cota da API, armazene respostas em cache por alguns minutos (ex.: usando node-cache). Respeite os cabeçalhos de Cache-Control se a API os fornecer.

5. Segurança além do .env
   Nunca hardcodeie chaves. Em ambientes de produção, use cofres de segredos (ex.: AWS Secrets Manager, Vault) ou injete a chave via variável de ambiente do sistema, sem depender do dotenv.

🔴 Avançado

1. Transporte HTTP/SSE para servidores remotos
   Embora o artigo use StdioServerTransport (comunicação local via entrada/saída padrão), você pode expor seu servidor MCP via HTTP com Server-Sent Events (SSE). Isso permite que múltiplos clientes remotos se conectem. O SDK do MCP oferece HTTPSServerTransport para esse fim.

2. Migre para TypeScript
   Adicione tipos estáticos ao projeto. O @modelcontextprotocol/sdk já é escrito em TypeScript, então você ganha autocompletar e verificação de tipos. Crie interfaces para os esquemas de entrada/saída e compartilhe-as entre ferramentas.

3. Autenticação e autorização por ferramenta
   Em cenários multi-inquilino, você pode exigir que cada chamada de ferramenta inclua um token de acesso. Implemente um middleware de autorização que valide o token antes de executar a lógica da ferramenta, retornando 401 se inválido (via content com mensagem de erro).

4. Streaming de respostas progressivas
   Para operações demoradas (ex.: consultas a bases de dados grandes), utilize o recurso de streaming do protocolo MCP, devolvendo resultados parciais ao modelo enquanto o processamento continua. Consulte a documentação do SDK sobre server.sendResourceUpdated() e notificações.

5. Crie uma camada de abstração para múltiplos backends
   Desacople a lógica da ferramenta do acesso a dados. Por exemplo, crie uma classe WeatherProvider com métodos como getCurrent(city, country). Assim você pode trocar a API do OpenWeatherMap por outra sem alterar a definição da ferramenta MCP.

6. Testes automatizados
   Use vitest ou jest para escrever testes unitários para cada ferramenta. Simule o transporte com StdioServerTransport em modo de teste e valide as respostas. Exemplo:

   javascript

   import { expect, test } from "vitest";
   test("get-forecast retorna dados válidos", async () => {
     const result = await callTool("get-forecast", { city: "London", country: "UK" });
     expect(result.content[0].text).toContain("weather");
   });

7. Empacotamento e distribuição
   Se você deseja compartilhar seu servidor MCP como um pacote npm, crie um binário executável usando "bin" no package.json. Assim, outros desenvolvedores podem instalá-lo globalmente (npm i -g meu-servidor-mcp) e configurá-lo no Claude Desktop com apenas o nome do comando.

Essas dicas visam transformar seu protótipo em um servidor MCP maduro, pronto para uso real. O ecossistema MCP está evoluindo rapidamente, e dominar esses níveis permitirá que você extraia o máximo do protocolo, independentemente da ferramenta de IA que estiver consumindo seus dados.

Resumo

Neste artigo, você acompanhou o guia prático focado em construindo um servidor MCP personalizado com Node.js para conectar uma API de previsão do tempo diretamente a uma ferramenta de IA. O MCP é um protocolo poderoso que abre as portas para os modelos consumirem dados dinâmicos e serviços locais ou remotos de forma padronizada.

Espero que este artigo tenha lhe proporcionado um bom entendimento sobre como construir um servidor MCP personalizado com Node.js. Boas criações!