Como Construir Seu Primeiro Servidor MCP: Guia Prático

[Perspectiva do operador] Conecto novas ferramentas aos meus agentes regularmente, e MCP é agora o caminho padrão para fazer isso de forma limpa. Uma vez construído o servidor, qualquer cliente compatível — Claude Desktop, Claude Code, qualquer aplicativo usando o SDK Anthropic — pode usá-lo sem alterações no código chamador. Esse é o valor: construir uma vez, reutilizar em tudo.

Índice

O que o MCP realmente é

O Model Context Protocol é um protocolo aberto que padroniza como modelos de IA se conectam a contexto externo e ferramentas. Pense nisso como um padrão USB-C para integrações de IA: antes dele, cada aplicativo que queria que o Claude lesse um banco de dados ou chamasse uma API precisava inventar sua própria solução. Com ele, você constrói um servidor MCP e qualquer host compatível pode usá-lo.

O MCP define três coisas que um servidor pode oferecer:

• Ferramentas — funções que o Claude pode chamar (ler um arquivo, consultar um BD, enviar mensagem no Slack)
• Recursos — dados que o Claude pode ler (documentos, linhas de banco de dados, árvores de arquivos)
• Prompts — templates de prompts reutilizáveis que o host pode injetar

Para a maioria dos casos de uso de operadores, você está construindo servidores de ferramentas. Recursos e prompts vêm depois, uma vez que o básico esteja funcionando.

A arquitetura é cliente-servidor, com o cliente (Claude Desktop, Claude Code, seu aplicativo personalizado) controlando tudo. O servidor é passivo — ele apenas ouve solicitações de chamada de ferramentas e retorna resultados.

As três peças de todo servidor MCP

Todo servidor MCP que você construir tem a mesma estrutura:

1. O objeto servidor — declara o nome, versão e capacidades do seu servidor (ferramentas, recursos, prompts)
2. Definições de ferramentas — uma lista de ferramentas com nomes, descrições e JSON schemas para suas entradas
3. Handlers de requisições — as funções que executam quando o Claude chama uma ferramenta

É isso. Nenhum banco de dados, nenhum stack HTTP, nenhuma camada de auth necessária para começar. O servidor mínimo tem menos de 30 linhas de TypeScript.

Pré-requisitos (2 minutos)

• Node.js 18+ — verifique com node --version
• TypeScript 5+ (incluído como dependência de desenvolvimento)
• Um cliente MCP para testar — Claude Desktop é gratuito e a forma mais fácil de ver seu servidor funcionando

Nenhuma chave de API Anthropic é necessária para executar um servidor MCP. A chave API vive no cliente (Claude Desktop), não no seu servidor.

Passo 1: Configurar o projeto (3 minutos)

mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk
npm install -D typescript tsx @types/node

Adicione ao package.json:

{
  "type": "module",
  "scripts": {
    "build": "tsc",
    "dev": "tsx src/index.ts"
  }
}

Crie tsconfig.json:

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

Passo 2: Escrever o servidor mínimo (5 minutos)

Crie src/index.ts:

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

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

// Declara quais ferramentas este servidor oferece
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "get_word_count",
      description: "Conta as palavras em um bloco de texto.",
      inputSchema: {
        type: "object",
        properties: {
          text: {
            type: "string",
            description: "O texto para contar palavras",
          },
        },
        required: ["text"],
      },
    },
  ],
}));

// Lida com chamadas de ferramentas do cliente
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "get_word_count") {
    const { text } = args as { text: string };
    const count = text.trim().split(/\s+/).filter(Boolean).length;
    return {
      content: [{ type: "text", text: `Contagem de palavras: ${count}` }],
    };
  }

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

// Conectar via stdio — é assim que o Claude Desktop fala com o servidor
const transport = new StdioServerTransport();
await server.connect(transport);

Este é o servidor completo. Ele registra uma ferramenta (get_word_count) e a implementa. A estrutura é o que importa.

Passo 3: Compilar e registrar no Claude Desktop (5 minutos)

Compile o TypeScript:

npm run build

Agora registre-o no arquivo de configuração do Claude Desktop.

No macOS: ~/Library/Application Support/Claude/claude_desktop_config.json No Windows: %APPDATA%\Claude\claude_desktop_config.json

Se o arquivo não existir, crie-o:

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "node",
      "args": ["/caminho/absoluto/para/my-mcp-server/build/index.js"]
    }
  }
}

Use o caminho absoluto. Reinicie o Claude Desktop após salvar. Você verá um ícone de martelo (🔨) na entrada de mensagens — isso significa que o Claude descobriu suas ferramentas.

Passo 4: Construir uma ferramenta útil

A contagem de palavras é ilustrativa. Aqui está uma ferramenta mais útil: ler arquivos de um diretório de projeto, que é o que uso para agentes de injeção de contexto que resumem bases de código, changelogs ou arquivos de configuração.

import { readFileSync, readdirSync } from "fs";
import { join, extname } from "path";

const ALLOWED_EXTENSIONS = [".md", ".txt", ".ts", ".json", ".yaml"];
const PROJECT_DIR = process.env.PROJECT_DIR ?? process.cwd();

A lógica é a mesma: defina ferramentas com JSON schemas precisos, implemente os handlers, valide entradas para prevenir path traversal e retorne texto ao cliente.

Os erros que cometi (para que você não os cometa)

O caminho deve ser absoluto. Caminhos relativos na config do Claude Desktop não se resolvem como esperado. Sempre use o caminho completo /home/usuario/....

Stdio significa nenhum console.log no seu servidor. O Claude Desktop se comunica com seu servidor via stdin/stdout. Um console.log de depuração corrompe o stream JSON-RPC. Use stderr:

process.stderr.write(`Debug: ${message}\n`);

Reinicie o Claude Desktop após cada mudança de config. Os servidores MCP são carregados na inicialização. Um arquivo de config editado não faz nada até você fechar e reabrir o aplicativo.

Descrições de ferramentas são o produto. O Claude decide se chama sua ferramenta com base no campo description. Uma descrição vaga significa que o Claude não saberá quando usá-la. Uma precisa significa que o Claude a usa no momento certo. Invista mais tempo nas descrições do que na implementação.

Como uso servidores MCP em produção

O padrão stdio funciona ótimo para Claude Desktop e Claude Code (local). Para agentes em produção — os 30+ que executo no Cloudflare Workers — uso a API tool-use do SDK Anthropic diretamente, pois preciso da flexibilidade para rotear para Haiku vs Sonnet por etapa.

Os padrões que realmente uso em produção:

1. Ferramentas de dev local — servidores MCP para Claude Code que expõem ferramentas específicas do projeto
2. Injeção de contexto — servidores MCP que pré-carregam docs relevantes sem copiar manualmente
3. Ponte protótipo-para-API — construo MCP primeiro (mais rápido para iterar), depois migro a lógica para SDK tool-use para produção

O que construir depois

Uma vez que a estrutura do servidor faça sentido, as ferramentas úteis são as que acessam o contexto externo do Claude:

• Leitor de banco de dados — executa uma consulta SQL somente leitura e retorna resultados como JSON
• Leitor Slack — busca as últimas N mensagens de um canal
• Leitor GitHub — lista PRs abertas, lê um arquivo em um commit específico
• Wrapper de API interna — chama sua própria API REST com headers de auth integrados

Para um exemplo completo com uma API real, como criar um servidor MCP do Google Analytics conecta uma ferramenta de relatórios do GA4 ao Claude Code e explica o que muda quando outras pessoas precisam fazer login.

Perguntas frequentes

Preciso de uma chave API Anthropic para construir um servidor MCP?

Não. Seu servidor MCP não chama a API Anthropic. Ele apenas responde a solicitações de chamada de ferramentas do cliente. A chave API vive no cliente, não no servidor.

Meu servidor MCP pode chamar APIs externas?

Sim — o handler é apenas código TypeScript assíncrono. Busque uma API do tempo, consulte um banco de dados, escreva em um arquivo. O servidor não se importa com o que o handler faz internamente.

Qual é a diferença entre os transportes stdio e HTTP?

Stdio é para servidores locais — mesma máquina que Claude Desktop ou Claude Code. HTTP com SSE é para servidores remotos que você pode implantar como serviço web. Comece com stdio; é mais simples de depurar.

Como o Claude sabe quando chamar minha ferramenta?

O Claude decide com base no campo description da ferramenta e no contexto da conversa. Se o Claude continua ignorando sua ferramenta, refine a descrição.