Como criar um MCP server em TypeScript do zero

Neste tutorial, vamos criar um servidor pequeno em TypeScript, anunciar uma ferramenta chamada somar e testá-la com um cliente MCP local. O exemplo não acessa arquivos, rede nem contas externas, então é um começo seguro para entender o ciclo completo.

O que é um MCP server e onde ele se encaixa

MCP significa Model Context Protocol, um protocolo aberto para conectar aplicações de IA a ferramentas e fontes de contexto. O host é o aplicativo que a pessoa usa, como um assistente ou editor. Ele cria um cliente MCP, que conversa com o servidor responsável por expor recursos e ferramentas.

O diagrama oficial da arquitetura MCP mostra essa separação. Seu servidor não é, por si só, um agente que decide o que fazer. Ele publica capacidades descritas para que um host compatível possa descobri-las e chamá-las.

Isso ajuda a manter a integração organizada. Um serviço pode expor uma busca, outro pode consultar tarefas e outro pode ler dados autorizados. O host decide quando chamar cada ferramenta de acordo com a conversa e as permissões disponíveis.

Antes de criar um MCP server em TypeScript

Você precisa de Node.js 20 ou superior e de um projeto TypeScript executado com tsx. Em 27 de outubro de 2026, as versões atuais do SDK MCP para servidor e cliente eram 2.4.0, e o pacote declara compatibilidade com Node.js a partir da versão 20.

O exemplo usa Zod para validar os argumentos recebidos. Essa validação evita aceitar valores fora do contrato esperado e deixa a descrição dos parâmetros disponível ao cliente MCP.

Crie um diretório e inicialize o pacote. Em seguida, use este package.json como base e rode npm install:

{
  "name": "mcp-server-demo",
  "private": true,
  "type": "module",
  "scripts": {
    "start": "tsx src/server.ts",
    "test": "tsx src/client.ts"
  },
  "dependencies": {
    "@modelcontextprotocol/client": "2.4.0",
    "@modelcontextprotocol/server": "2.4.0",
    "zod": "4.2.0"
  },
  "devDependencies": {
    "tsx": "4.23.15"
  }
}

O type ativa módulos ES no Node.js. Os scripts chamam o servidor e o cliente sem exigir uma etapa separada de compilação. A documentação atual do SDK TypeScript do Model Context Protocol reúne exemplos e notas de migração da versão 2.

Passo 1: prepare o projeto do MCP server

Crie src/server.ts e registre uma ferramenta com dois números de entrada. O servidor usa transporte STDIO, no qual as mensagens do protocolo passam pelo fluxo padrão do processo local.

import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import { z } from "zod/v4";

serveStdio(() => {
  const server = new McpServer({ name: "servidor-mcp-demo", version: "1.0.0" });

  server.registerTool(
    "somar",
    {
      description: "Soma dois números e devolve o resultado.",
      inputSchema: z.object({
        a: z.number().describe("Primeiro número"),
        b: z.number().describe("Segundo número")
      })
    },
    async ({ a, b }) => ({
      content: [{ type: "text", text: String(a + b) }]
    })
  );

  return server;
});

McpServer organiza as capacidades publicadas pelo processo. registerTool define o nome, a descrição, o esquema de entrada e a função que será executada. A função devolve um bloco de texto no formato esperado pelo protocolo.

A ferramenta de exemplo só calcula a soma. Em uma aplicação real, substitua essa lógica por uma tarefa delimitada, como consultar um pedido ou buscar uma informação interna. Comece com leitura e mantenha operações que alteram dados fora do primeiro protótipo.

Passo 2: registre a ferramenta somar

Para confirmar que o servidor responde, crie src/client.ts. Esse cliente inicia o processo pelo transporte STDIO, lista as ferramentas publicadas e chama somar com os valores 2 e 3.

import { Client } from "@modelcontextprotocol/client";
import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";

const client = new Client({ name: "mcp-server-test", version: "1.0.0" });
const transport = new StdioClientTransport({
  command: process.execPath,
  args: ["--import", "tsx", "src/server.ts"]
});

try {
  await client.connect(transport);
  const { tools } = await client.listTools();
  console.log(`tools=${tools.map((tool) => tool.name).join(",")}`);
  const result = await client.callTool({ name: "somar", arguments: { a: 2, b: 3 } });
  console.log(`result=${result.content.map((part) => part.type === "text" ? part.text : "").join("")}`);
} finally {
  await client.close();
}

Rode npm test. O resultado esperado neste exemplo é tools=somar e result=5. A listagem confirma que o cliente descobriu a ferramenta; a segunda linha confirma que o servidor processou a chamada e devolveu o conteúdo.

Se o processo fechar sem resposta, confira primeiro se o diretório contém src/server.ts e src/client.ts, se os pacotes foram instalados e se o Node.js atende ao requisito mínimo. Mensagens de diagnóstico devem ir para stderr, não para stdout, porque o transporte STDIO reserva o fluxo padrão para o protocolo.

Como conectar o MCP server a um host

Depois do teste local, registre o processo em um host compatível com MCP. Cada aplicativo tem seu próprio formato de configuração e política de aprovação, então siga a documentação específica do host em vez de copiar um exemplo de outro editor.

No guia para configurar MCP no VS Code, veja como adicionar um servidor ao cliente. Para entender um caso de ferramenta MCP voltada a agentes, leia também sobre o Retrieve do Work IQ.

Antes de compartilhar o servidor, defina quais dados ele pode ler, quem pode chamá-lo e quais ações exigem confirmação. Não coloque tokens ou senhas no código, nos argumentos da ferramenta nem em mensagens de log. Se uma ferramenta alterar arquivos, enviar mensagens ou acionar pagamentos, limite o escopo e teste a confirmação humana.

Mantenha as descrições curtas e específicas. Uma ferramenta chamada somar com entradas a e b comunica melhor sua intenção do que uma ferramenta genérica chamada executar. Para cada ferramenta, diga o que ela faz, quais argumentos aceita e o que acontece em caso de erro.