Como criar um servidor MCP em TypeScript (SDK v2) | We.Inc
Crie um servidor MCP funcional com o SDK oficial de TypeScript v2: instale, registre uma tool com um schema Zod, conecte por stdio e teste no MCP Inspector.
Instale o pacote oficial @modelcontextprotocol/server e o Zod, crie um McpServer com nome e versão, registre cada tool com registerTool, uma descrição e um schema de entrada Zod, e depois conecte um StdioServerTransport. Rode npx @modelcontextprotocol/inspector para chamar as suas tools manualmente antes que qualquer aplicação de IA mexa nelas.
As peças de que você precisa
Peça
De onde vem
O que faz
McpServer
@modelcontextprotocol/server
Guarda as suas tools e responde às requisições do protocolo
registerTool
Método do McpServer
Adiciona uma tool: nome, descrição, schema de entrada, handler
StdioServerTransport
@modelcontextprotocol/server/stdio
Conversa com o host pela entrada e saída padrão
z.object(...)
zod/v4
Descreve e valida os argumentos da tool
Inspector
npx @modelcontextprotocol/inspector
Permite listar e chamar tools manualmente
Marque cada passo conforme avança. O checklist guarda onde você parou, e cada passo tem o comando ou arquivo exato de que você precisa. O servidor final busca em uma pequena lista de notas, o que basta para ver todas as peças em funcionamento sem um banco de dados.
Crie uma pasta, adicione o package.json mostrado abaixo e instale as duas dependências.
Cole o server.ts e troque o array de notas pelos seus próprios dados ou por uma chamada de API.
Inicie o Inspector e aponte-o para o comando que roda o seu servidor.
Liste as tools, chame notes_search com uma palavra e confira o texto que volta.
Nunca escreva no stdout em um servidor stdio. Esse fluxo carrega as mensagens do protocolo, então um console.log perdido as corrompe. Use console.error, que vai para o stderr.
Mantenha cada tool pequena e específica. Duas tools chamadas notes_search e notes_create são mais fáceis para um modelo escolher do que uma única tool de notas com um seletor de modo.
Valide dentro do handler, além do schema, quando uma tool mexe com dinheiro, arquivos ou dados de outras pessoas. O schema verifica o formato, não a permissão.
Fixe a versão major do SDK no package.json. A versão 1 ficava em outro pacote, @modelcontextprotocol/sdk, então tutoriais mais antigos não vão bater com estes imports.
Perguntas frequentes
Qual pacote npm eu instalo?
Para a versão 2 do SDK, instale @modelcontextprotocol/server para servidores e @modelcontextprotocol/client para clientes. O pacote v1 mais antigo, @modelcontextprotocol/sdk, fica em um branch v1.x e recebe correções de bugs e de segurança por pelo menos seis meses depois do lançamento da v2.
Preciso do Zod?
O README da v2 usa o Zod v4 para os schemas de entrada e o importa de zod/v4, e diz que outras bibliotecas Standard Schema, como Valibot e ArkType, também funcionam. Instale a que você escolher junto com o SDK.
O servidor roda no Bun ou no Deno?
O README do SDK diz que ele roda no Node.js, no Bun e no Deno. O Inspector é uma ferramenta Node separada e o README dele pede o Node 22.19.0 ou mais recente.
Como deixo o servidor disponível remotamente?
Troque o transporte stdio pelo Streamable HTTP e hospede o processo em algum lugar acessível. Adicione autenticação antes de expor qualquer tool que altere dados, já que qualquer pessoa que alcance a URL pode enviar requisições.
Como sei que uma aplicação de IA vai entender a minha tool?
Leia a sua descrição e o seu schema como se você não soubesse mais nada sobre o projeto. Se um estranho não conseguir dizer quando chamar a tool e o que passar, um modelo também vai chutar. O Inspector mostra exatamente o que um host vai ver.
Por que começar com stdio
Um servidor stdio é só um programa que o host inicia. Não há porta, nem hospedagem, nem login, o que o torna o caminho mais rápido para uma tool funcionando que você pode testar na sua própria máquina.
Quando as tools estiverem se comportando bem, passar para o Streamable HTTP muda a linha do transporte e a hospedagem, não o código das tools. Essa separação é o principal motivo para manter a lógica de negócio em funções simples que os handlers chamam.
Desenhando a resposta do handler
Um handler retorna um objeto com um array content. Itens de texto são o caso comum, e texto curto e específico funciona melhor: diga o que correspondeu e quantos, em vez de despejar um conjunto inteiro de registros.
Quando nada corresponder, retorne uma frase dizendo isso. Uma string vazia deixa o modelo sem saber se a chamada falhou ou se a busca simplesmente não encontrou nada.
O servidor completo
Dois arquivos. Troque o array de notas pelo que o seu servidor deve buscar.
type module permite que a sintaxe de import ES rode diretamente; o script start usa tsx para você pular uma etapa de build.
Uma tool com schema Zod, uma função de busca simples e uma conexão stdio. Os logs vão para o stderr para nunca se misturarem com as mensagens do protocolo.
Teste com o Inspector
O Inspector tem três modos. A interface web é o lugar mais fácil para começar; o modo CLI serve para scripts e CI.
Modos do Inspector
Na interface web, conecte com o comando que inicia o seu servidor (npx tsx server.ts) e depois abra a lista de tools.
Instale o SDK, o Zod e um executor de TypeScript
Escreva o server.ts com uma tool
Inicie o servidor uma vez para conferir que ele não cai