Construa um Servidor MCP com TypeScript: Tutorial 2026

O Protocolo de Contexto de Modelo ultrapassou 97 milhões de downloads mensais de SDK e mais de 10.000 implementações de servidores públicos. Todas as principais plataformas de IA — Claude, Cursor, Windsurf, OpenAI — agora falam isso nativamente. Se você construir um servidor MCP em TypeScript hoje, suas ferramentas funcionarão em todos os lugares onde esses clientes operam.

Este tutorial orienta sobre como construir um servidor MCP funcional do zero, cobrindo ferramentas, recursos, o transporte stdio e como conectá-lo ao Claude Desktop. O Effloow Lab executou essa construção exata em um sandbox local usando @modelcontextprotocol/sdk@1.29.0 e Node.js v25.9.0 — todo o código aqui é dessa execução.

O que você irá construir

Ao final deste tutorial, você terá:

• Um servidor MCP em TypeScript com duas ferramentas personalizadas e um recurso
• Um binário compilado pronto para clientes baseados em stdio
• Uma configuração do Claude Desktop que carrega seu servidor na inicialização
• Uma base que você pode expandir com APIs reais, bancos de dados ou arquivos locais

O servidor expõe uma ferramenta word_count e uma ferramenta to_slug — exemplos deliberadamente simples escolhidos para demonstrar validação de entrada com Zod, formatação de resposta e todo o ciclo de vida do JSON-RPC sem distraí-lo com lógica de negócios.

Pré-requisitos

• Node.js v18 ou superior (o tutorial usa v25.9.0)
• npm v8 ou superior
• TypeScript 5.x instalado ou disponível via npx
• Claude Desktop (opcional, para testes ao vivo)

Passo 1 — Inicializar o Projeto

Crie um diretório novo e crie o package.json:

mkdir my-mcp-server && cd my-mcp-server

Escreva o package.json manualmente em vez de usar npm init, porque você precisa que "type": "module" esteja definido desde o início:

{
  "name": "my-mcp-server",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.11.0"
  },
  "devDependencies": {
    "typescript": "^5.8.3",
    "@types/node": "^22.0.0"
  }
}

O campo "type": "module" não é opcional. O SDK MCP é apenas ESM — se você deixar isso de fora, o Node.js tratará sua saída compilada como CommonJS e as importações falharão em tempo de execução.

Instale as dependências:

npm install

Saída esperada:

added 95 packages in 438ms
found 0 vulnerabilities

Verifique a versão do SDK instalada:

cat node_modules/@modelcontextprotocol/sdk/package.json | node -e "process.stdin.resume();let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>console.log(JSON.parse(d).version))"
# 1.29.0

Passo 2 — Configurar o TypeScript

Crie tsconfig.json na raiz do projeto. As configurações do módulo aqui são precisas — "Node16" tanto para module quanto para moduleResolution são necessárias para resolver corretamente as importações de extensão .js que o SDK usa internamente:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"]
}

Se você usar "moduleResolution": "node" (o antigo padrão), o TypeScript não conseguirá resolver as importações de extensão .js do SDK e a compilação falhará com erros de Cannot find module.

Crie o diretório de origem:

mkdir src

Passo 3 — Escrever o Servidor MCP

Crie src/index.ts:

import { McpServer } from "@modelcontextprotocol/sdk";

const server = new McpServer();

server.addTool("word_count", async (input) => {
  return {
    "count": input.split(" ").length,
  "input": input
};
});

server.addTool("to_slug", async (input) => {
  return {
    "slug": input.toLowerCase().replace(/[^a-z0-9]+/g, "-"),
    "input": input
};
});

server.start();