MCP na Prática: Construa Seu Primeiro Servidor em TypeScript em 30 Minutos (2026)

Se você trabalha com desenvolvimento e IA, já ouviu falar do MCP. Mas se ainda não botou a mão no código, está na hora.

Em março de 2026, o SDK do Model Context Protocol atingiu 97 milhões de downloads mensais — um crescimento de 4.750% desde o lançamento em novembro de 2024 (Digital Applied). O registro público de servidores MCP saltou de ~1.200 no Q1 2025 para mais de 9.400 em abril de 2026 (Digital Applied). OpenAI, Google DeepMind, Microsoft, Cohere e Mistral — todos adotaram o protocolo (WorkOS Blog, Março/2026).

"MCP has done in 16 months what took REST APIs several years: become the default infrastructure layer for a new category of computing." — Digital Applied, MCP Hits 97M Downloads: Model Context Protocol Guide (Março/2026)

Este tutorial é prático. Vamos construir um servidor MCP funcional em TypeScript, conectar em três clientes diferentes e entender por que esse protocolo se tornou o padrão de integração de IA em 2026.

1. O que vamos construir

Vamos criar um Task Manager MCP Server — um servidor que expõe ferramentas (tools) para gerenciar tarefas: adicionar, listar e concluir. Parece simples, mas é o suficiente para você entender todo o fluxo:

• Servidor MCP com TypeScript + SDK oficial
• Três tools com validação de schema
• Transporte via stdio (para desktop) e menção ao Streamable HTTP
• Conexão com Claude Desktop, Cursor e Claude Code

No final, você vai ter um servidor funcional que pode estender para qualquer caso real — busca em banco de dados, consulta a APIs externas, manipulação de arquivos.

2. Setup do projeto

Crie uma pasta e inicialize o projeto:

mkdir mcp-task-manager
cd mcp-task-manager
npm init -y

Instale o SDK oficial:

npm install @modelcontextprotocol/sdk zod

O pacote zod é opcional mas recomendado para validação de schemas. O SDK do MCP já usa internamente.

Seu package.json precisa do campo type: "module" para usar ESM:

{
  "name": "mcp-task-manager",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

Crie um tsconfig.json básico:

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

Pronto. A estrutura final vai ser:

mcp-task-manager/
├── package.json
├── tsconfig.json
└── src/
    └── index.ts

3. Criando o servidor — o código

Agora vem a parte boa. Crie src/index.ts com o servidor MCP completo.

O SDK do MCP exporta classes e schemas que seguem o padrão do protocolo. Veja a estrutura:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";

Tipos e estado

interface Task {
  id: string;
  title: string;
  completed: boolean;
  createdAt: string;
}

// Nosso "banco" em memória — substitua por um DB real depois const tasks: Map<string, Task> = new Map(); let nextId = 1;

Instância do servidor

const server = new Server(
  {
    name: "task-manager",
    version: "1.0.0",
  },
  {
    capabilities: {
      tools: {},
    },
  }
);

O segundo parâmetro declara as capacidades do servidor. Aqui dizemos que ele expõe tools. O MCP também suporta resources, prompts e logging.

Listando as ferramentas

O handler de ListToolsRequestSchema informa ao cliente quais ferramentas estão disponíveis e seus schemas de entrada:

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "add_task",
      description: "Adiciona uma nova tarefa à lista",
      inputSchema: {
        type: "object",
        properties: {
          title: {
            type: "string",
            description: "Título da tarefa",
          },
        },
        required: ["title"],
      },
    },
    {
      name: "list_tasks",
      description: "Lista as tarefas cadastradas",
      inputSchema: {
        type: "object",
        properties: {
          filter: {
            type: "string",
            enum: ["all", "pending", "done"],
            description: "Filtro por status",
          },
        },
      },
    },
    {
      name: "complete_task",
      description: "Marca uma tarefa como concluída",
      inputSchema: {
        type: "object",
        properties: {
          id: {
            type: "string",
            description: "ID da tarefa",
          },
        },
        required: ["id"],
      },
    },
  ],
}));

Cada tool segue o padrão JSON Schema para validação — o próprio cliente valida os parâmetros antes de chamar.

Executando as ferramentas

O handler de CallToolRequestSchema recebe o nome da tool e os argumentos:

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

switch (name) { case "add_task": { const id = String(nextId++); const task: Task = { id, title: args?.title as string, completed: false, createdAt: new Date().toISOString(), }; tasks.set(id, task); return { content: [{ type: "text", text: JSON.stringify(task, null, 2) }], }; }

case "list_tasks": {
  const filter = (args?.filter as string) || "all";
  let result = Array.from(tasks.values());
  if (filter === "pending") result = result.filter((t) => !t.completed);
  if (filter === "done") result = result.filter((t) => t.completed);
  return {
    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
  };
}

case "complete_task": {
  const id = args?.id as string;
  const task = tasks.get(id);
  if (!task) {
    throw new Error(`Tarefa ${id} não encontrada`);
  }
  task.completed = true;
  return {
    content: [{ type: "text", text: JSON.stringify(task, null, 2) }],
  };
}

default:
  throw new Error(`Ferramenta desconhecida: ${name}`);

} });

Repare no padrão de resposta: { content: [{ type: "text", text: "..." }] }. O MCP aceita múltiplos tipos de conteúdo — text, image, resource e embedded.

Inicializando o servidor

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("✅ Task Manager MCP Server rodando via stdio");
}

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

⚠️ Use console.error para logs. O console.log é capturado pelo transporte stdio e pode quebrar a comunicação com o cliente.

Compile e teste:

npx tsc
node dist/index.js

Se tudo deu certo, você vê a mensagem verde no terminal. O servidor está rodando e esperando conexões.

4. Transportes: stdio vs Streamable HTTP

O MCP suporta dois transportes principais. Cada um tem seu caso de uso:

No exemplo acima usamos stdio, o transporte mais simples. Para usar Streamable HTTP, instale o pacote adicional e troque o transport:

import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";

// Em vez de StdioServerTransport: const transport = new StreamableHTTPServerTransport({ port: 3100, endpoint: "/mcp", });

O Streamable HTTP permite que qualquer cliente HTTP consuma seu servidor — inclusive de outras máquinas. Perfeito para times e integrações enterprise.

Empresas que usam MCP em produção convertem pilotos a uma taxa de 38%, contra apenas 22% sem o protocolo — diferença de 16 pontos percentuais (Digital Applied, The MCP Adoption Wave, Abril/2026).

5. Conectando ao Claude Desktop

O Claude Desktop foi o primeiro cliente MCP e continua sendo o mais usado. Para conectar seu servidor:

1. Abra as configurações do Claude Desktop
2. Vá em Settings > Developer > Edit Config
3. Adicione no claude_desktop_config.json:

{
  "mcpServers": {
    "task-manager": {
      "command": "node",
      "args": ["C:/caminho/absoluto/mcp-task-manager/dist/index.js"]
    }
  }
}

No macOS / Linux:

{
  "mcpServers": {
    "task-manager": {
      "command": "node",
      "args": ["/caminho/absoluto/mcp-task-manager/dist/index.js"]
    }
  }
}

4. Reinicie o Claude Desktop
5. Olhe no canto inferior direito — aparece o ícone de ferramenta 🔧 indicando que o servidor está ativo

Agora você pode pedir: "Adicione uma tarefa para revisar o relatório mensal" e o Claude vai chamar sua tool add_task automaticamente.

6. Conectando ao Cursor e Claude Code

Cursor

No Cursor, vá em Settings > Features > MCP e adicione:

Depois de adicionado, o Cursor detecta automaticamente as tools do seu servidor e as disponibiliza para o agente de IA durante o desenvolvimento.

Dica: No Cursor, use Cmd+I para abrir o Composer e peça algo como "Use a tool list_tasks para ver o que está pendente". A IA vai chamar seu servidor MCP em tempo real.

Claude Code

Com o Claude Code (CLI), a configuração é por projeto. Crie ou edite o arquivo ~/.claude/claude.json:

{
  "mcpServers": {
    "task-manager": {
      "command": "node",
      "args": ["/caminho/mcp-task-manager/dist/index.js"]
    }
  }
}

Depois, dentro do seu projeto, basta rodar claude e começar a usar as tools.

Mais de 300 clientes já suportam o protocolo MCP — incluindo VS Code / GitHub Copilot, Windsurf, e dezenas de IDEs e ferramentas no-code (Digital Applied).

7. Checklist de verificação

Antes de sair construindo o próximo grande servidor MCP, confira se tudo está funcionando:

• O servidor compila sem erros com npx tsc
• O servidor inicia e mostra a mensagem de log no terminal
• O Claude Desktop reconhece o servidor (ícone 🔧 aparece)
• O Cursor lista as tools do servidor na configuração MCP
• add_task retorna uma tarefa com ID único
• list_tasks retorna a lista correta com filtros
• complete_task marca a tarefa como concluída e retorna erro para IDs inexistentes
• As respostas são sempre no formato { content: [{ type: "text", text: ... }] }

Se algum item falhar, o problema mais comum é o caminho absoluto no JSON de configuração — use o caminho completo até o dist/index.js.

8. E agora?

Seu primeiro servidor MCP está no ar. O repositório oficial modelcontextprotocol/servers já passou de 85.600 stars no GitHub, com o SDK TypeScript em 12.300+ stars e 94 releases (GitHub — modelcontextprotocol/servers, GitHub — typescript-sdk). A comunidade cresce rápido.

Para evoluir seu servidor:

• Adicione resources para expor dados que o cliente pode ler (ex: estatísticas das tarefas)
• Implemente prompts para templates reutilizáveis
• Troque o banco em memória por SQLite ou PostgreSQL
• Publique no registry do MCP — a previsão para Q3 2026 é de 18.400 servidores publicados e 38-46% das Fortune 1000 com ao menos uma integração MCP em produção (Digital Applied, MCP Adoption Q3 2026 Projection)

"When Anthropic quietly shipped the Model Context Protocol in November 2024, it looked like any other internal tool that got open-sourced on a slow news day. Eighteen months later, MCP has 97 million monthly SDK downloads, over 9,400 servers, 300-plus clients, and a Linux Foundation home co-founded by Anthropic, OpenAI, and Block." — Digital Applied, MCP Adoption Statistics 2026 (Abril/2026)

O MCP é hoje o que o REST foi para os anos 2000 — a camada de integração padrão para uma nova categoria de computação. Ter seu próprio servidor rodando não é só um exercício técnico. É preparação para o que vem pela frente.

Acesse o modelcontextprotocol.io/docs para a documentação oficial, e o repositório modelcontextprotocol/typescript-sdk para o código fonte.

Bora codar. 🚀

Artigos Relacionados

Confira também: Como Usar IA para Criar Conteudo de Alta Qualidade em 2026 Confira também: Guia Prático: Como Criar Seu Primeiro Assistente de IA com R$ 0 em 30 Minutos Confira também: APIs de IA Gratis em 2026: Google Caiu 80%, OpenAI Exige Cartao — O Mapa do que Ainda Funciona