🛠️ Criando seu Proprio MCP Server

Um MCP server e um processo que fala JSON-RPC via stdio (ou HTTP). No minimo, ele precisa responder a dois metodos: initialize (handshake) e tools/list (listar tools). Quando o client chama uma tool, o server recebe via tools/call e retorna o resultado.

Na pratica, o SDK abstrai tudo isso. Voce so define as tools e seus handlers. Mas entender a anatomia ajuda a debugar quando algo da errado.

O pacote @modelcontextprotocol/sdk e o caminho mais rapido para criar um MCP server. Com 30 linhas voce tem um server funcional. A classe principal e McpServer, que voce instancia, registra tools, e conecta a um transport.

Instalacao: npm init -y && npm install @modelcontextprotocol/sdk zod. O Zod e usado para validar os inputs das tools de forma type-safe.

mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
touch index.ts

Cada tool tem: nome (string unica), descricao (o que faz, em linguagem natural), e inputSchema (parametros via Zod ou JSON Schema). Um schema claro e descritivo e a diferenca entre o agente acertar de primeira ou chutar.

Dica: escreva a descricao como se explicasse para um junior. O agente usa esse texto para decidir quando e como chamar a tool.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "my-server", version: "1.0.0" });

server.tool("greet", "Say hello to someone by name", {
  name: z.string().describe("The person's name")
}, async ({ name }) => ({
  content: [{ type: "text", text: `Hello, ${name}!` }]
}));

const transport = new StdioServerTransport();
await server.connect(transport);

O handler e a funcao async que recebe os argumentos validados e retorna um CallToolResult. O resultado e um array de content items, que podem ser texto, imagens, ou recursos embedded. Erros sao retornados com isError: true.

Pattern basico: receber args -> executar logica -> retornar {{ content: [{{ type: 'text', text: resultado }}] }}. Para erros, retorne a mensagem de erro no content com isError: true.

O MCP Inspector e a ferramenta oficial para testar MCP servers. Rode npx @modelcontextprotocol/inspector node index.js e ele abre uma UI web onde voce pode listar tools, chamar com parametros, e ver as respostas.

Alem do Inspector, teste integrando direto no Claude Code: adicione ao settings.json local e peca ao agente para usar. Se ele consegue chamar a tool e receber resultado, esta funcionando.

# Testar com o MCP Inspector
npx @modelcontextprotocol/inspector node index.js

Para compartilhar seu server: (1) publique no npm com npm publish, (2) certifique-se de que funciona via npx (configure o campo bin no package.json), (3) opcionalmente, liste no Smithery.ai para visibilidade.

Se o server tem dependencias pesadas, considere um Docker image. Isso garante que funciona em qualquer maquina sem conflitos de dependencia.