Crie um MCP Server usando o SDK oficial em TypeScript — a alternativa para desenvolvedores JavaScript.
O MCP possui dois SDKs oficiais mantidos pela Anthropic: o @modelcontextprotocol/sdk para TypeScript e o fastmcp para Python. Ambos implementam a mesma especificação e produzem servers totalmente compatíveis entre si. A escolha entre eles depende da sua stack e preferência pessoal — o resultado final é idêntico para o client.
O SDK TypeScript (@modelcontextprotocol/sdk) é mais verboso que o Python, mas oferece tipagem forte com interfaces e tipos definidos para cada request e response. O SDK Python (fastmcp) usa decorators e é mais conciso, ideal para prototipagem rápida. Ambos comunicam via JSON-RPC sobre stdio ou SSE, produzindo servers 100% compatíveis com qualquer client MCP. A escolha é puramente de preferência — o protocolo é o mesmo.
O ecossistema MCP está dividido entre os dois SDKs: aproximadamente 55% dos servers da comunidade são escritos em Python (pela simplicidade) e 45% em TypeScript (pela robustez de tipos). Servers oficiais como filesystem, fetch e memory são escritos em TypeScript. Ambos os SDKs recebem atualizações simultâneas quando a spec evolui.
Criar um MCP Server em TypeScript segue o fluxo padrão de qualquer projeto Node.js/TS: inicializar com npm, configurar o TypeScript, instalar o SDK e escrever o código no diretório src/. A estrutura é simples e familiar para quem já trabalha com TypeScript.
A estrutura mínima de um MCP Server TypeScript consiste em: package.json com a dependência @modelcontextprotocol/sdk, tsconfig.json configurado para ESModules e target ES2020+, e src/index.ts com o código do server. O entry point cria uma instância de Server, registra os handlers e conecta ao transporte stdio com StdioServerTransport.
mkdir meu-mcp-server && cd meu-mcp-server && npm init -y — Cria o diretório do projeto e inicializa o package.json.
npm install @modelcontextprotocol/sdk — Instala o SDK oficial do MCP para TypeScript.
npx tsc --init — Gera o tsconfig.json. Configurar "module": "ESNext", "target": "ES2020" e "outDir": "./dist".
mkdir src && touch src/index.ts — Cria o arquivo principal onde o server será implementado.
Adicione "type": "module" no seu package.json para usar ESModules nativamente. No tsconfig.json, defina "moduleResolution": "node16" para compatibilidade. Adicione também um script "build": "tsc" e "start": "node dist/index.js" no package.json para facilitar o workflow.
No SDK TypeScript, tools são registradas usando request handlers. Diferente do Python onde decorators simplificam a sintaxe, no TS você define explicitamente o handler para CallToolRequestSchema e declara os inputs usando JSON Schema. É mais verboso, mas cada tipo é explícito e validado em tempo de compilação.
Para implementar tools em TypeScript, você usa server.setRequestHandler(ListToolsRequestSchema, ...) para listar as tools disponíveis (retornando name, description e inputSchema) e server.setRequestHandler(CallToolRequestSchema, ...) para executá-las. O inputSchema é definido como JSON Schema padrão com type, properties e required. Dentro do handler de CallTool, você faz um switch no request.params.name para despachar a lógica correta.
O padrão em TS é retornar { content: [{ type: "text", text: resultado }] } do handler de CallTool. Para erros, adicione isError: true ao response. Crie uma função auxiliar makeTextResponse(text: string) para evitar repetição — padrão comum em servers TS bem estruturados.
Além de Tools, o SDK TypeScript suporta Resources e Prompts usando o mesmo padrão de request handlers. Resources expõem dados para o modelo ler, enquanto Prompts fornecem templates reutilizáveis. A API segue a mesma filosofia: registrar um handler para o schema correspondente.
Para Resources, use server.setRequestHandler(ListResourcesRequestSchema, ...) para listar resources e server.setRequestHandler(ReadResourceRequestSchema, ...) para servir o conteúdo. Cada resource tem uma URI única (ex: file:///config.json) e retorna conteúdo como text ou blob. Para Prompts, o padrão é idêntico: ListPromptsRequestSchema e GetPromptRequestSchema. Mesma arquitetura, diferentes schemas.
Registrar o handler de ListResources retornando a lista de resources com uri, name e description.
Registrar o handler de ReadResource que recebe a URI e retorna o conteúdo com mimeType apropriado.
Verificar no MCP Inspector se os resources aparecem e retornam conteúdo corretamente.
Na prática, Tools são a feature mais usada (presente em ~95% dos servers), seguidas por Resources (~40%) e Prompts (~15%). No entanto, Resources são especialmente valiosos em cenários enterprise onde o modelo precisa acessar documentação, configs ou dados sem executar ações. Prompts são ideais para padronizar interações recorrentes com o modelo.
Diferente do Python onde você roda o arquivo diretamente, em TypeScript é necessário compilar antes de rodar. O comando tsc compila o TypeScript para JavaScript no diretório dist/, e depois você executa com node dist/index.js. A configuração no Claude Desktop aponta para o arquivo JavaScript compilado.
O workflow de build é: npm run build (que executa tsc) para compilar, depois node dist/index.js para rodar. No Claude Desktop, a configuração fica assim: "command": "node", "args": ["/caminho/absoluto/dist/index.js"]. Use sempre caminhos absolutos no config para evitar problemas. Alternativamente, use npx ts-node src/index.ts durante desenvolvimento para pular o build.
Adicione "build": "tsc" e "watch": "tsc --watch" nos scripts do package.json. Durante o desenvolvimento, use npm run watch em um terminal para recompilar automaticamente a cada mudança. Para produção, sempre rode npm run build e teste com node dist/index.js antes de configurar no Claude Desktop.
Sempre compile antes de rodar! Um erro comum é editar o arquivo .ts e esquecer de recompilar, rodando a versão antiga do .js. Se suas mudanças não parecem ter efeito, verifique se rodou tsc antes de reiniciar o server. Dica: configure um script "dev": "tsc && node dist/index.js" que compila e roda em sequência.
Testar um MCP Server TypeScript segue o mesmo fluxo que o Python: use o MCP Inspector para debug interativo e o Claude Desktop para teste de uso real. O resultado deve ser idêntico ao de um server Python equivalente — se ambos implementam a mesma tool, o output para o client é o mesmo.
O MCP Inspector (npx @modelcontextprotocol/inspector node dist/index.js) conecta ao seu server e permite testar cada tool, resource e prompt individualmente. Você vê os requests JSON-RPC enviados e as responses recebidas em tempo real. Para teste de produção, configure o server no Claude Desktop e use-o em conversas reais. Compare o resultado com um server Python equivalente para garantir compatibilidade.
Rodar npm run build e verificar que não há erros de compilação TypeScript.
Testar no MCP Inspector — verificar que tools, resources e prompts aparecem e respondem corretamente.
Configurar no Claude Desktop e fazer testes em conversas reais para validar a experiência do usuário.
Se tiver um server Python equivalente, comparar os outputs para garantir comportamento idêntico.
Próximo Módulo: 5.5 — Explorando Servers da Comunidade