Como Construir Seu Primeiro Servidor MCP: Guia Prático

Índice

Atualizado junho 2026.

TL;DR: MCP (Model Context Protocol) é como dar ao Claude acesso estruturado a ferramentas e dados externos — bancos de dados, arquivos, APIs — sem sobrecarregar a janela de contexto. O servidor é mais simples do que parece: instale o SDK, defina suas ferramentas como JSON schema, implemente os handlers, conecte via stdio. Você pode ter o Claude chamando suas ferramentas personalizadas em menos de 30 minutos.

[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.

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

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.