Crie Seu Próprio Servidor MCP: Dê um Novo Superpoder à IA

Imagine se o seu assistente de IA pudesse consultar um pequeno “calculador de tempo de leitura” feito por você. Você pergunta “Quanto tempo levo para ler este artigo?” e ele analisa o texto de verdade, em vez de chutar. Essa pequena ponte entre um app de IA e o seu código é um servidor MCP.

MCP (Model Context Protocol, ou Protocolo de Contexto de Modelo) é um padrão aberto para conectar apps de IA a ferramentas e dados. Pense nele como um adaptador bem identificado: o app fala MCP, o seu servidor traduz uma capacidade útil para essa linguagem compartilhada, e o modelo pode decidir quando pedi-la. Vamos criar um servidor real em TypeScript, conectá-lo a um app local de IA e acompanhar a conversa inteira.

Primeiro, um mapa do MCP em 30 segundos

Um host MCP é o app de IA que você usa. Dentro dele, um cliente MCP gerencia uma conexão com cada servidor. O seu servidor anuncia capacidades, como ferramentas, recursos e prompts. Quando o modelo escolhe uma ferramenta, o cliente do host envia um pedido estruturado para o servidor, que executa o seu código e devolve um resultado estruturado.

O MCP não torna o modelo magicamente confiável e, por si só, não dá acesso aos seus arquivos ou contas. O código do servidor e as permissões do host determinam o que pode ser acessado. No nosso primeiro projeto, vamos oferecer uma ferramenta somente de leitura, sem contas externas e sem segredos.

Crie um pequeno servidor de tempo de leitura

O SDK oficial de TypeScript está na linha v2. Sua entrada moderna para stdio, serveStdio, cuida da negociação do protocolo; uma fábrica cria um novo servidor para cada conexão. O guia oficial do SDK usa Node.js 20 ou mais recente.

Crie um projeto e instale o SDK, um validador de esquemas e um executor de TypeScript:

1mkdir reading-time-mcp
2cd reading-time-mcp
3npm init -y
4npm install @modelcontextprotocol/server zod
5npm install -D typescript tsx @types/node

No arquivo package.json, adicione "type": "module". Depois, crie src/index.ts:

1import { McpServer } from "@modelcontextprotocol/server";
2import { serveStdio } from "@modelcontextprotocol/server/stdio";
3import { z } from "zod";
4
5function createServer() {
6  const server = new McpServer({
7    name: "reading-time",
8    version: "1.0.0",
9  });
10
11  server.registerTool(
12    "estimate_reading_time",
13    {
14      description:
15        "Estimate how many minutes it takes to read a piece of text. Use this when someone asks for an approximate reading time.",
16      inputSchema: z.object({
17        text: z.string().min(1).max(20_000)
18          .describe("The text to estimate; maximum 20,000 characters"),
19        wordsPerMinute: z.number().int().min(100).max(1_000).default(220)
20          .describe("Reading speed; defaults to 220 words per minute"),
21      }),
22    },
23    async ({ text, wordsPerMinute }) => {
24      const wordCount = text.trim().split(/\s+/).filter(Boolean).length;
25      const minutes = Math.max(1, Math.ceil(wordCount / wordsPerMinute));
26
27      return {
28        content: [{
29          type: "text",
30          text: `${wordCount} words; about ${minutes} minute(s) at ${wordsPerMinute} words per minute.`,
31        }],
32      };
33    },
34  );
35
36  return server;
37}
38
39serveStdio(createServer, {
40  onerror: (error) => console.error("MCP server error:", error),
41});
42console.error("Reading-time MCP server ready");

Essa é a ferramenta inteira. O nome e a descrição ajudam o modelo a saber quando usá-la. O esquema Zod documenta as entradas e rejeita valores inadequados antes de chamar o seu código. O manipulador faz uma tarefa pequena e devolve um bloco de texto que o host pode apresentar ao modelo.

O limite de 20 mil caracteres é uma proteção básica, não uma defesa completa contra todo tipo de esgotamento de recursos. Serviços reais também devem adicionar limites de tempo, cotas e tratamento de erros adequados.

Teste a conexão e depois ligue um host

Inicie o servidor na pasta do projeto:

npx tsx src/index.ts

Um servidor MCP via stdio espera mensagens JSON-RPC na entrada padrão e envia mensagens do protocolo pela saída padrão. Por isso, nunca use console.log() para depurar nesse modo: uma linha perdida pode interromper a conversa. Use console.error() ou um logger configurado para stderr, como no exemplo.

Você pode inspecionar a ferramenta anunciada e fazer uma chamada de exemplo com o Inspector oficial. Instale ou execute a versão atual da CLI do Inspector conforme a documentação e informe o comando que inicia o servidor; o guia de MCP mostra o fluxo pela CLI e como testar as versões moderna e legada do protocolo. Experimente um texto como “MCP torna as conexões reutilizáveis.” O servidor conta cinco palavras e retorna uma estimativa.

Para conectar a um host que aceite servidores MCP locais via stdio, adicione uma entrada como esta à configuração MCP do host (o arquivo exato depende do app):

1{
2  "mcpServers": {
3    "reading-time": {
4      "command": "npx",
5      "args": ["tsx", "/CAMINHO/ABSOLUTO/PARA/reading-time-mcp/src/index.ts"]
6    }
7  }
8}

Use o caminho absoluto do projeto, salve a configuração e reinicie ou recarregue o host. Agora pergunte: “Estime o tempo de leitura deste texto: [cole um parágrafo].” Veja o host listar a ferramenta, o modelo escolhê-la, o cliente enviar tools/call e o servidor devolver o resultado.

Acompanhe essa pequena ida e volta

1Você faz uma pergunta
2        ↓
3O host envia ao modelo a pergunta e as descrições das ferramentas disponíveis
4        ↓
5O modelo escolhe estimate_reading_time(text, wordsPerMinute)
6        ↓
7O cliente MCP envia um pedido tools/call estruturado via stdio
8        ↓
9O servidor valida as entradas → executa o código → devolve conteúdo
10        ↓
11O modelo explica o resultado numa resposta em linguagem natural

O modelo propõe a chamada; o host e o servidor a executam. Essa diferença importa. Uma ferramenta bem projetada oferece uma opção clara ao modelo, enquanto a validação e o controle de acesso continuam no código comum.

Torne seu servidor seguro e útil

Pequenas escolhas fazem diferença para que uma ferramenta MCP seja agradável de usar:

• Escreva uma descrição para uma pessoa e para um modelo. Diga o que a ferramenta faz, quando deve ser usada e o que não faz. “Estima minutos a partir de um texto; não resume nem armazena” é melhor que “processa texto”.
• Valide cada argumento. Trate entradas geradas pelo modelo como qualquer outro pedido não confiável. Defina limites e tamanhos máximos e retorne erros úteis.
• Comece com pouco acesso e somente leitura. Dê à ferramenta apenas os dados e operações necessários. Peça confirmação antes de ações importantes, como enviar, apagar, comprar ou publicar.
• Não coloque segredos em prompts e logs. Use um gerenciador de segredos e credenciais com permissões limitadas. Evite repetir dados privados nas mensagens de diagnóstico.
• Para servidores remotos, proteja o caminho HTTP. Use o transporte Streamable HTTP atual e implemente os requisitos de autorização da especificação. Valide se os tokens são destinados ao serviço; não aceite tokens encaminhados sem verificação. Proteja pedidos externos contra SSRF e aplique limites por usuário.
• Teste os limites, não apenas o caso feliz. Experimente entradas vazias, grandes demais, malformadas e sem autorização, além de falhas e tempos limite dos serviços externos.

O guia de segurança do MCP destaca problemas como falhas de autorização por confused deputy, encaminhamento indevido de tokens, sequestro de sessão e falsificação de pedidos do lado do servidor (SSRF). “Fala MCP” não significa que passou por uma análise de segurança: privilégio mínimo, consentimento e autorização cuidadosa continuam essenciais.

Agora vem a parte divertida: personalize

Você já tem um padrão de trabalho: escolha uma tarefa útil, descreva-a claramente, defina um esquema, implemente um manipulador pequeno e conecte tudo por um transporte. Transforme o exemplo em uma calculadora para ajustar ingredientes de uma receita, um leitor de um arquivo de status local ou uma consulta de transporte público. Adicione um recurso quando o host precisar buscar dados ou um prompt para empacotar um fluxo de trabalho repetível.

Comece com uma ferramenta que seja útil mesmo num dia normal da IA. Depois, deixe o protocolo fazer o que um bom protocolo faz: tornar essa capacidade útil disponível para mais de um host compatível.

Fontes e próximos passos

• Documentação MCP: crie um servidor — instalação oficial de TypeScript, serveStdio, Inspector e conexão a um host.
• SDK MCP para TypeScript — pacotes oficiais e orientação sobre versões.
• Boas práticas de segurança do MCP — ameaças e mitigações para quem implementa e opera servidores.
• Visão geral da arquitetura MCP — hosts, clientes, servidores e transportes.