Um MCP server é um programa que conecta o Claude Code a uma ferramenta externa. Em outras palavras, o MCP server vale pra qualquer cliente de IA compatível. A ferramenta pode ser banco, repositório no GitHub, sistema de arquivos ou navegador. Dessa forma, tudo passa por um único protocolo aberto chamado Model Context Protocol. Em vez de cada IDE inventar sua integração, o protocolo padroniza a conversa via JSON-RPC 2.0. De fato, a Anthropic publicou a especificação em novembro de 2024 e o ecossistema cresceu rápido. Segundo a Linux Foundation, em um ano o MCP já passava de 10 mil servidores publicados. Entre eles, implementações oficiais do GitHub, Microsoft, Notion, Cloudflare e Stripe.

Neste guia mostramos como funciona o handshake JSON-RPC na prática e como configurar os 2 primeiros servidores no Claude Code em 10 minutos. Em seguida, listamos as 8 implementações que vale instalar hoje. Também cobrimos os riscos reais. Entre janeiro e abril de 2026, pesquisadores divulgaram mais de 40 CVEs em SDKs de MCP. Parte deles vem da reference implementation da própria Anthropic. Por isso, ignorar isso em produção é convite pra RCE via prompt injection. Se você ainda quer a base conceitual, entenda a fundo o que é MCP neste guia antes de seguir.

Por que o MCP server importa no fluxo de quem programa

Em termos práticos, o servidor MCP é a peça que expõe capacidades para um modelo de IA consumir, dentro do Model Context Protocol. A analogia que a Anthropic usa é a porta USB-C: assim como o conector padronizou periféricos, o MCP padroniza como Claude, ChatGPT, Cursor, VS Code e outros hosts conversam com ferramentas externas. Antes, cada combinação IDE × ferramenta exigia integração própria. Agora, um único servidor atende qualquer cliente compatível. Se você quer a definição completa, a arquitetura e o histórico do protocolo, entenda a fundo o que é MCP neste guia conceitual. Aqui o foco é a prática: configurar, escolher servidores e blindar o setup.

Por que isso importa para quem programa? Primeiro, porque o modelo passa a ter acesso contextual real ao seu ambiente: arquivos, repositórios, banco. Tudo isso sem você precisar copiar e colar trechos no chat. Segundo, porque desbloqueia automações de produção. O Claude Code pode rodar uma query no PostgreSQL e gerar a migration. Em seguida, ele abre o pull request no GitHub e atualiza a página correspondente no Notion, tudo numa conversa. Em outras palavras, é a base operacional do que chamamos de agentic engineering, o paradigma sucessor do vibe coding.

Além disso, vale notar a velocidade de adoção. O protocolo foi anunciado pela Anthropic em novembro de 2024 e ganhou tração rápida. Em 9 de dezembro de 2025, a Anthropic doou o MCP para a Agentic AI Foundation, sob a Linux Foundation, fundação co-fundada com Block e OpenAI e com apoio de Google, Microsoft, AWS, Cloudflare e Bloomberg. Recomendamos pensar no MCP como o equivalente da camada HTTP para agentes de IA: chato no início, indispensável depois.

Como funciona: host, client, server e o handshake JSON-RPC

Cabo USB-C cujas pontas se transformam em logos de Notion, GitHub, Playwright e outros — diagrama editorial mostrando MCP como conector universal
MCP funciona como um cabo USB-C: um único protocolo conecta o Claude a qualquer ferramenta — Filesystem, GitHub, Playwright, Notion, banco de dados.

Em primeiro lugar, a arquitetura tem três papéis bem definidos. O Host é a aplicação de IA que você usa: Claude Code, Claude Desktop, VS Code com Copilot, Cursor. O Client é um objeto interno do host que mantém uma conexão dedicada com cada servidor. E o Server é o programa que expõe as capacidades. Da mesma forma, cada par client-server tem conexão própria, sem multiplexação. Quando você conecta Claude Code ao filesystem e ao GitHub ao mesmo tempo, o host instancia dois clients diferentes, um por servidor.

Arquitetura MCP em uma frase

Servidores locais usam transport stdio. Servidores remotos usam Streamable HTTP com OAuth.

Protocolo JSON-RPC 2.0 no MCP server: initialize, tools/list e tools/call

Por sua vez, a camada de dados roda sobre JSON-RPC 2.0. Toda interação começa com um initialize que negocia protocolVersion e capabilities, quais primitivas cada lado suporta. Em seguida, o client envia tools/list pra descobrir as ações disponíveis e tools/call pra executar. Veja a seguir um trecho real do handshake, simplificado:

Code
// Cliente envia
{ "jsonrpc": "2.0", "id": 1, "method": "initialize",
  "params": { "protocolVersion": "2025-06-18",
              "capabilities": { "elicitation": {} },
              "clientInfo": { "name": "claude-code", "version": "1.0" } } }

// Servidor responde
{ "jsonrpc": "2.0", "id": 1, "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": { "tools": { "listChanged": true }, "resources": {} },
    "serverInfo": { "name": "filesystem", "version": "0.6.0" } } }

Depois do handshake, servidores expõem três primitivas. Tools são funções executáveis (ler arquivo, rodar query, criar issue). Resources são fontes de contexto que o modelo lê (arquivos, registros de banco). E Prompts são templates reutilizáveis. Além disso, clients podem expor sampling e elicitation. Esses dois métodos permitem ao servidor pedir uma completion do modelo ou input adicional do usuário, sem precisar embutir SDK de LLM. Dessa forma, o servidor permanece neutro em relação ao provider.

Transports: stdio local versus Streamable HTTP remoto

Sobre transport, há duas opções. Stdio usa input/output padrão pra comunicação local entre processos, com overhead zero de rede, ideal pra desenvolvimento. Streamable HTTP usa POST com Server-Sent Events opcional pra streaming, suporta bearer token, API key e OAuth. Para uso pessoal e CI, defendemos stdio sempre que possível. HTTP entra quando o servidor precisa rodar fora da sua máquina (Sentry, Linear, qualquer SaaS). Por isso, primeiro entenda quem hospeda o estado antes de escolher o transport.

Quer entender o porquê de protocolos como JSON-RPC e MCP existirem, não só como configurar? Arquitetura de software: as partes difíceis, de Mark Richards e Neal Ford (Alta Books), é leitura essencial. O livro disseca trade-offs reais de arquiteturas distribuídas, comunicação entre serviços e contratos de protocolo. É exatamente o tipo de decisão que você toma ao escolher entre stdio local e Streamable HTTP, ou ao desenhar o seu próprio MCP server.

Arquitetura de software: as partes difíceis: análises modernas de...

Arquitetura de software: as partes difíceis: análises modernas de…

R$70,87
Comprar na Amazon

Configurando seu primeiro MCP server no Claude Code

Por exemplo, a melhor forma de aprender é colocar dois servidores pra rodar em 10 minutos. Vamos com Filesystem (oficial Anthropic, stdio) e GitHub (oficial Anthropic, stdio com token). Antes de mais nada, os pré-requisitos: Claude Code 1.0+, Node.js 18+ e uma conta no GitHub. Primeiro, abra o terminal na pasta do seu projeto. Em seguida, registre o servidor de arquivos:

Code
# Filesystem: limita acesso a /Users/seuusuario/Projects
claude mcp add filesystem npx @modelcontextprotocol/server-filesystem /Users/seuusuario/Projects

# GitHub: precisa de personal access token com escopos repo, read:org
export GITHUB_TOKEN="ghp_xxx..."
claude mcp add github npx @modelcontextprotocol/server-github

Por fim, valide se os servidores estão respondendo. O comando claude mcp list mostra o status de cada um. Em seguida, caso apareça connected, abra uma sessão nova com claude. Em seguida, peça: “liste os 5 arquivos modificados mais recentes do meu projeto e crie uma issue resumindo eles no repo X”. Você vai notar que o modelo chama tools/list internamente, descobre o que existe nos servidores Filesystem e GitHub, e depois executa tools/call pra cada ação. Esse é o ciclo inteiro de MCP em produção, sem mock.

Além disso, vale uma dica. O Claude Code persiste a config em ~/.config/claude/claude_desktop_config.json (Mac/Linux) ou no equivalente Windows. Por outro lado, caso prefira editar à mão pra versionar a config em dotfiles, o formato é simples. Cada servidor vira uma entrada com command, args e env. Em time, recomendamos commitar o config sem tokens (usar variáveis de ambiente) pra que cada dev pegue as mesmas integrações ao clonar o setup.

8 MCP servers que valem a pena instalar hoje

Em segundo lugar, o ecossistema explodiu rápido. A lista curada awesome-mcp-servers reúne centenas de implementações e já passa de 89 mil stars no GitHub. Por sua vez, filtramos os 8 que entregam valor imediato pra dev BR. O foco foi estabilidade da implementação oficial e cobertura de casos reais:

  • Filesystem (oficial Anthropic): leitura, escrita, busca em diretórios autorizados. É o primeiro servidor que todo mundo instala.
  • GitHub (oficial Anthropic): issues, PRs, commits, code search. Substitui boa parte da gh CLI no fluxo de IA.
  • Playwright (oficial Microsoft): automação de browser. Com mais de 34 mil stars, é um dos servidores mais populares do ecossistema. Permite ao Claude navegar, preencher form, fazer screenshot.
  • PostgreSQL (oficial Anthropic): query SQL read-only por padrão. Excelente pra exploração e geração de relatório, sem risco de DML acidental.
  • Notion (oficial Notion): leitura e escrita de páginas e databases. Combinado com o GitHub, fecha o loop de documentação técnica.
  • Context7 (Upstash): injeta documentação atualizada de bibliotecas no contexto. Resolve o problema da knowledge cutoff do modelo pra frameworks novos.
  • Brave Search: busca web sem precisar de SerpAPI. Privacy-friendly e com tier gratuito decente.
  • Obsidian: leitura e edição do seu vault Markdown. Ideal pra quem mantém second brain e quer que o Claude trabalhe junto da base de notas.

De maneira concreta, recomendamos começar com Filesystem e GitHub, validar o fluxo por dois ou três dias, e só então adicionar os próximos. Por outro lado, mais integrações conectadas significa mais tools disponíveis pro modelo escolher, e mais ruído no tools/list. Dessa forma, ative só o que você usa de verdade. Para projetos diferentes, vale ter configs separadas em specs distintas, em vez de um config monolítico.

Publicidade

Riscos de segurança do MCP server e como mitigar

No entanto, aqui mora a parte que ninguém comenta nas threads animadas sobre MCP. De janeiro a abril de 2026, pesquisadores divulgaram mais de 40 CVEs em implementações MCP. Segundo a Practical DevSecOps, os bugs cobrem os SDKs Python, TypeScript, Java e Rust. Mais especificamente, uma análise paralela escaneou 2.614 implementações e encontrou 82% vulneráveis a path traversal e cerca de 40% sem nenhuma autenticação. O caso emblemático: CVE-2025-68143, 68144 e 68145, três falhas no próprio servidor de referência mcp-server-git da Anthropic, encadeáveis para RCE via prompt injection.

Os pesquisadores da OX Security agrupam os ataques em cinco famílias. Primeiro, tool poisoning, quando um servidor malicioso polui resultados. Em seguida, prompt injection via dado externo, em que texto vindo de um arquivo ou issue manipula o modelo. Depois vêm trust bypass, supply chain attack (pacote npm/pypi comprometido vira integração maliciosa) e cross-tenant exposure. Para ilustrar o tamanho do problema: o pacote mcp-remote (CVE-2025-6514, CVSS 9.6) afetou 437 mil downloads antes da correção.

Cinco mitigações práticas para rodar MCP server com segurança

O que fazer na prática? Apontamos cinco mitigações que reduzem drasticamente o blast radius:

  • Princípio do menor privilégio no Filesystem: passe paths explícitos, nunca / ou $HOME. Cada path adicional aumenta a superfície de path traversal.
  • Tokens com escopo mínimo: para o servidor GitHub, use fine-grained PAT limitado aos repos que importam. Evite tokens clássicos com repo global.
  • Audite a fonte antes de instalar: prefira implementações da org modelcontextprotocol/servers ou da própria empresa dona da API (Microsoft, Notion, Stripe). Para third-party, leia o código antes; são tipicamente menos de 300 linhas.
  • Stdio > HTTP em ambiente sensível: servidores remotos sem auth são exatamente o problema dos 40%. Quando precisar HTTP, exija OAuth, não API key estática.
  • Trate output como input não confiável: o resultado de um tools/call entra no contexto do modelo. Se o servidor é comprometido, ele consegue injetar instruções. Logue e monitore as chamadas em produção.

Por enquanto, defendemos uma postura conservadora: stdio local com fontes verificadas, tokens estreitos e revisão manual de implementações third-party. À medida que OAuth e o ecossistema de auditoria amadurecem, dá pra abrir mais. Por ora, tratar MCP como “API externa não auditada” é o framing certo.

Construindo seu próprio servidor MCP em TypeScript

Em terceiro lugar, servir uma API interna da empresa como servidor MCP é o caso de uso mais comum depois das integrações prontas. Para dimensionar a tração: segundo a DigitalApplied, os SDKs oficiais somavam cerca de 97 milhões de downloads por mês em março de 2026. É uma curva de adoção rara num protocolo tão novo. O SDK oficial em TypeScript expõe uma tool em poucas dezenas de linhas. Primeiro, inicialize o projeto e instale o pacote:

Bash
mkdir meu-mcp-server && cd meu-mcp-server
npm init -y
npm i @modelcontextprotocol/sdk zod
npm i -D typescript @types/node tsx

Registrando uma tool com Zod schema e StdioServerTransport

Em seguida, crie um src/index.ts com uma única tool de exemplo: consultar o saldo de pontos de um cliente em uma API interna fictícia. Dito isso, o SDK abstrai todo o handshake JSON-RPC; você só registra a tool e o handler:

CSS
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: "pontos-fidelidade",
  version: "0.1.0",
});

server.tool(
  "consultar_saldo",
  "Retorna o saldo de pontos de fidelidade de um cliente",
  { clienteId: z.string().describe("ID do cliente no CRM") },
  async ({ clienteId }) => {
    const res = await fetch(`https://api.interna/clientes/${clienteId}/pontos`);
    const data = await res.json();
    return { content: [{ type: "text", text: `Saldo: ${data.pontos} pontos` }] };
  }
);

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

Em seguida, para registrar no Claude Code, basta apontar o comando que executa esse script. Por fim, teste com o MCP Inspector, que é a ferramenta oficial de debug, equivalente ao Postman do JSON-RPC. Ele mostra a sequência de mensagens, inspeciona schemas e simula chamadas. Em time grande, considere padronizar a estrutura de tools: nome com namespace tipo pontos_consultar, descrição clara, schema Zod completo. Isso melhora a taxa de sucesso do modelo escolhendo a tool certa.

Por outro lado, para casos avançados, como exposição de resources, suporte a prompts reutilizáveis e sampling, a spec oficial tem walkthroughs detalhados. Para ir mais fundo em agentes que orquestram múltiplos servidores, vamos cobrir o tema em outro artigo do cluster, sobre o Claude Agent SDK. Em resumo, o ponto é: a partir do momento que você consegue escrever uma implementação própria, qualquer API interna vira contexto pro modelo, sem hack.

Conclusão: o que fazer com seu primeiro servidor MCP

O servidor MCP é a camada que transforma o Claude Code de chat técnico em ferramenta operacional de verdade. Em primeiro lugar, instale Filesystem e GitHub, ative em projetos reais e observe o ganho de contexto. Em seguida, adicione 1 ou 2 integrações da lista: Playwright se você faz teste E2E, Notion se mantém docs, PostgreSQL se analisa dados. Por fim, audite cada servidor antes de aplicar em produção. No fim das contas, a história dos 40+ CVEs mostra que adoção rápida sem revisão custa caro.

Próximos passos no cluster Claude/IA

Em conclusão, lembre-se de que MCP é base, não fim. Em cima dele, você compõe subagents especializados, hooks que disparam ações em eventos do Claude Code e pipelines completas via Agent SDK. Esses temas aparecem em outros posts deste cluster. Para entender o paradigma completo, comece pela nossa visão de agentic engineering. Em seguida, descubra as skills mais populares do Claude Code e veja como o spec-driven development ancora todo o fluxo. Se quiser estender o Claude pra fora do terminal, vale também testar a extensão do Claude no Chrome.

Publicidade

Em resumo: respostas rápidas sobre MCP server

O que é um MCP server?
Um MCP server é um programa que expõe ferramentas, dados e prompts para modelos de IA usando o Model Context Protocol. Em outras palavras, é o componente que faz a ponte entre o Claude Code (ou outro cliente) e uma API, banco de dados ou sistema de arquivos. A comunicação acontece via JSON-RPC 2.0 sobre stdio (local) ou Streamable HTTP (remoto).
Como instalar o primeiro servidor MCP no Claude Code?
O comando é claude mcp add . Por exemplo, para o Filesystem oficial: claude mcp add filesystem npx @modelcontextprotocol/server-filesystem /caminho/autorizado. Em seguida, rode claude mcp list para confirmar que o status apareceu como connected. Dessa forma, o servidor fica disponível para qualquer sessão Claude Code aberta a partir desse diretório.
Quais são os melhores MCP servers para o Claude Code?
Para a maioria dos devs, a combinação inicial é Filesystem, GitHub e Playwright (Microsoft, com mais de 34 mil stars). Em seguida vale adicionar PostgreSQL para dados, Notion para documentação, Context7 para docs atualizadas de bibliotecas, Brave Search para web e Obsidian para second brain. Por fim, prefira sempre as implementações oficiais, que são auditadas com mais frequência.
O MCP é seguro para usar em produção?
Depende da implementação e da configuração. Entre janeiro e abril de 2026 foram divulgados mais de 40 CVEs em SDKs MCP, incluindo no servidor de referência mcp-server-git da Anthropic. Por isso, recomenda-se usar stdio local com fontes verificadas, tokens com escopo mínimo, paths explícitos no Filesystem e auditoria de código de qualquer servidor third-party. Tratar o output como input não confiável também é boa prática.
Qual a diferença entre MCP server e plugin tradicional?
O MCP é independente de cliente: a mesma implementação funciona em Claude Code, Claude Desktop, VS Code com Copilot, Cursor e qualquer outro host compatível. Plugins tradicionais ficam acoplados a uma IDE específica. Além disso, o protocolo padroniza descoberta (tools/list), execução (tools/call) e notificações em tempo real via JSON-RPC, enquanto plugins normalmente têm APIs proprietárias incompatíveis entre si.