Todos os artigos

Back-end12 min de leitura

O que é MCP: o protocolo que liga ferramentas à IA

O que é o Model Context Protocol, explicado com os dois servidores MCP que eu uso todo dia: host, client e server, tools, transportes e um servidor mínimo em TypeScript.

Também em English, Español, Français

Se você usa o Claude Code, o Cursor ou qualquer IA dentro do editor, já esbarrou na sigla MCP. Ela aparece em configuração, em lista de "conectores", em todo post sobre agentes. E quase sempre em inglês.

Eu uso MCP todo dia. Tenho um servidor próprio que desenha personagens pra um app meu, e uso uma versão estendida do Talk to Figma pra desenhar no Figma direto do terminal. As ilustrações desse post saíram de lá.

Então esse é o post que eu queria ter lido quando comecei: o que é MCP, como as peças conversam e como é um servidor de verdade por dentro.

TL;DR#

  • MCP é um padrão aberto pra ligar apps de IA a sistemas externos: arquivos, bancos, APIs, o Figma.
  • Três peças: o host (o app que você usa), um client por conexão e o server (quem oferece as ferramentas).
  • O servidor oferece tools, resources e prompts. Tools são as mais usadas: ações que o modelo decide chamar.
  • Por baixo é JSON-RPC 2.0, por stdio (processo local) ou Streamable HTTP (servidor remoto).
  • A spec mudou em 2026-07-28: ficou sem estado, sem o aperto de mão initialize, e marcou sampling e roots como descontinuados. Tutorial de 2025 já está desatualizado.
  • Tool é código rodando com as suas permissões. Instale servidor MCP com o mesmo cuidado de uma dependência.

O problema que o MCP resolve#

Imagine três apps de IA (o Claude Code, o Cursor e o app que você está construindo) e quatro ferramentas que você quer usar com eles: GitHub, Figma, Postgres e Slack.

Sem um padrão, cada app precisa de uma integração própria com cada ferramenta. São 3 × 4 = 12 integrações, cada uma com seu formato, sua autenticação e seus bugs. Entrou um app novo? Mais quatro. Entrou uma ferramenta nova? Mais três.

Sem padrão, cada par precisa de uma integração. Com MCP, cada lado implementa o protocolo uma vez

Com MCP, a conta vira soma: cada app implementa um client MCP e cada ferramenta ganha um servidor MCP. São 3 + 4 peças, e qualquer app conversa com qualquer ferramenta.

Uma porta USB-C pras IAs#

A documentação oficial define o MCP como um padrão de código aberto pra conectar aplicações de IA a sistemas externos. E usa uma imagem que ajuda muito: pense no MCP como uma porta USB-C pra aplicações de IA.

Antes do USB-C, cada aparelho tinha o seu cabo. Hoje um cabo serve pro carregador, pro monitor e pro HD externo. O MCP faz isso entre a IA e as ferramentas: o app não precisa saber nada do Figma, só precisa falar MCP.

Um pouco de história: a Anthropic lançou o MCP em novembro de 2024 e, em dezembro de 2025, doou o protocolo pra Agentic AI Foundation, ligada à Linux Foundation. No anúncio da doação, a Anthropic falava em mais de 10 mil servidores MCP públicos ativos.

As três peças: host, client e server#

Essa é a parte que mais confunde, então vou usar o meu setup de exemplo.

O host cria um client pra cada servidor. Cada conexão é dedicada
  • Host é o app de IA que você usa. No meu caso, o Claude Code. Ele guarda a conversa, fala com o modelo e pede a sua permissão antes de rodar uma tool (a não ser que você tenha liberado).
  • Client é a peça dentro do host que mantém uma conexão com um servidor. O host cria um client pra cada servidor configurado.
  • Server é o programa que oferece as ferramentas. Pode rodar na sua máquina ou em outro lugar.

Os meus dois servidores locais são bem diferentes por dentro:

  • o servidor de personagens monta personagens em SVG a partir das peças de um brandbook e devolve a imagem pronta;
  • o TalkToFigma não desenha nada sozinho: ele repassa os comandos, por um WebSocket local, pra um plugin aberto no Figma. Quem mexe nas camadas é o plugin.

Pro Claude Code, os dois são iguais: um servidor MCP com uma lista de tools.

O que um servidor oferece#

Um servidor pode oferecer três tipos de coisa, que a spec chama de primitivas. A diferença entre elas é quem decide usar.

Tools, resources e prompts, e o que mudou do lado do client na spec 2026-07-28

Tools: o modelo decide#

Tools são ações. Buscar algo, criar um arquivo, mandar uma mensagem, gerar uma personagem. O servidor lista as tools com nome, descrição e o formato dos parâmetros, e é o modelo que decide quando chamar cada uma. É de longe a primitiva mais usada: os meus dois servidores só têm tools.

Resources: o app decide#

Resources são dados pra dar contexto: o conteúdo de um arquivo, o esquema de um banco, o histórico do git. Cada um tem uma URI, e é o app que decide o que anexar à conversa.

Prompts: você decide#

Prompts são modelos de mensagem prontos que você escolhe na hora, tipo um comando com barra. O Talk to Figma traz alguns, como o design_strategy, com boas práticas pra trabalhar no Figma.

E do lado do client?#

O caminho contrário também existe: o servidor pode pedir coisas ao client. Aqui a spec de 2026-07-28 mudou bastante:

  • Elicitation continua: o servidor pede uma informação pra você no meio da tarefa (um login, uma confirmação).
  • Sampling (o servidor pedir uma resposta ao modelo do host) e Roots (o client dizer quais pastas o servidor pode ver) foram marcados como descontinuados. Ainda funcionam, mas implementação nova não deve usar.

Se você está lendo um tutorial de 2025, é aqui que ele mais vai te enganar.

Por baixo: JSON-RPC#

Toda conversa entre client e server é JSON-RPC 2.0: mensagens JSON com method, params e um id pra casar a pergunta com a resposta. Pra chamar uma tool, o client manda um tools/call:

{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "greet", "arguments": { "name": "Yasmin" } } }

E o servidor responde com o resultado. Essa resposta é real: saiu do servidor mínimo que eu mostro mais abaixo.

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{ "type": "text", "text": "Hello, Yasmin!" }],
    "resultType": "complete"
  }
}

Na versão atual, toda requisição também leva a versão do protocolo e as capacidades do client num campo _meta. A spec omite esse campo nos exemplos pra encurtar, e eu fiz o mesmo.

Os transportes#

O JSON precisa viajar de algum jeito, e a spec define dois transportes:

  • stdio: o host abre o servidor como um processo filho e conversa pela entrada e saída padrão, uma mensagem por linha. É o que os meus dois servidores usam.
  • Streamable HTTP: cada mensagem é um POST num endpoint só, e a resposta volta como JSON ou como um stream SSE. É o jeito de rodar um servidor remoto, que atende vários clients.

O antigo transporte HTTP+SSE, que aparece em muito tutorial, está descontinuado desde a versão 2025-03-26.

Uma chamada de tool, passo a passo#

Juntando tudo, é isso que acontece quando eu peço uma personagem pro Claude Code:

Ida e volta de uma chamada de tool: pedido, trabalho do servidor e resultado
Os nove passos, da descoberta do servidor até a imagem na conversa
  1. O client descobre o servidor. Na spec atual, com server/discover, que devolve as versões e capacidades. Nas versões de 2025, era o aperto de mão initialize.
  2. O client pede a lista de tools (tools/list). O meu servidor devolve 11, cada uma com nome, descrição e o schema dos parâmetros.
  3. Você pede, em linguagem natural: "desenha uma pessoa de 70 anos".
  4. O modelo escolhe a tool lendo as descrições, e monta os argumentos: { anos: 70 }.
  5. O host pede a sua permissão. Você pode negar.
  6. O modelo passa a chamada pro client.
  7. O client manda o tools/call e o servidor roda o código.
  8. O resultado volta: no meu caso, uma imagem em PNG e um JSON com a seed e os traços.
  9. O modelo responde com a personagem.

Repare que o modelo nunca fala com o servidor. Ele só escolhe a tool e os argumentos. Quem conversa com o servidor é o client, dentro do host, e só depois do seu ok.

Um servidor mínimo em TypeScript#

O jeito mais rápido de entender é escrever um. O SDK oficial de TypeScript está na versão 2, com pacotes separados pro servidor e pro client:

npm install @modelcontextprotocol/server zod

E esse é um servidor inteiro, com uma tool:

src/index.ts
import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import { z } from "zod";
 
// serveStdio calls this for every instance it needs
function createServer() {
  const server = new McpServer({ name: "hello-mcp", version: "1.0.0" });
 
  server.registerTool(
    "greet",
    {
      description: "Greets someone by name. Use it when the user asks to say hi to someone.",
      inputSchema: z.object({ name: z.string().describe("Who to greet") }),
    },
    async ({ name }) => ({
      content: [{ type: "text", text: `Hello, ${name}!` }],
    }),
  );
 
  return server;
}
 
serveStdio(createServer, {
  onerror: (error) => console.error("hello-mcp error:", error),
});
console.error("hello-mcp running on stdio"); // stderr: stdout belongs to the protocol

Três detalhes que importam:

  • A descrição é o que o modelo lê pra decidir se chama a tool. Escreva como se fosse pra uma pessoa do time.
  • O schema em zod vira JSON Schema no tools/list. É assim que o modelo sabe quais argumentos mandar.
  • Nada de console.log. No stdio, a saída padrão é do protocolo: qualquer texto solto ali quebra as mensagens. Log vai pro console.error.

O serveStdio atende tanto client novo quanto client que ainda abre com o initialize de 2025. Eu testei os dois mandando as mensagens na mão, e o servidor respondeu certo em cada versão.

Pra plugar no Claude Code, depois de compilar:

claude mcp add hello-mcp -- node build/index.js

E pra testar sem IA nenhuma, o Inspector lista as tools pela linha de comando:

npx @modelcontextprotocol/inspector --cli node build/index.js --protocol-era modern --method tools/list

Como é no meu servidor de verdade#

O servidor de personagens tem 11 tools. Essa é a principal, com os nomes traduzidos pro inglês (no servidor ela se chama gerar_personagem, que é o nome que aparece nos diagramas):

mcp/server.ts
server.registerTool(
  "generate_character",
  {
    title: "Generate character",
    description:
      "Generates a character from a seed (the same seed always gives the same character). " +
      "Without a seed, draws a new one. Traits in 'locked' are kept. 'age' shows the same person in another phase of life. " +
      "Returns the image and the traits.",
    inputSchema: { seed: z.string().optional(), locked: partialTraits.optional(), ...visual },
    annotations: { readOnlyHint: true },
  },
  async ({ seed, locked, ...v }) => {
    const s = seed ?? newSeed();
    return respond(draw(s, locked), s, v);
  },
);

E a resposta devolve duas coisas: a imagem, pra você ver, e um JSON, pro modelo poder continuar o trabalho:

return {
  content: [
    { type: "image", data: png.toString("base64"), mimeType: "image/png" },
    { type: "text", text: JSON.stringify(info, null, 2) }, // seed, age and traits
  ],
};

Foi assim que saiu a personagem da animação: pedi uma pessoa de 70 anos, feliz, e o servidor devolveu a imagem com a seed 0d2kajwu. Com a mesma seed, outra tool mostra a mesma pessoa em outra fase da vida.

Esse servidor ainda está no SDK v1 (@modelcontextprotocol/sdk), ligado com server.connect(new StdioServerTransport()). Funciona com o Claude Code que eu uso hoje, mas a documentação nova avisa que esse jeito só atende clients da era 2025. Servidor novo eu já começaria no v2, com o serveStdio.

O que aprendi#

A descrição é o prompt. O modelo não lê o seu código, lê a descrição da tool e dos parâmetros. No meu servidor, cada um dos estilos de desenho tem uma frase explicando o que muda, porque é só isso que o modelo enxerga na hora de escolher.

Dê um jeito do modelo descobrir os valores válidos. Eu criei uma tool listar_opcoes que só lista os ids das peças e das cores. A descrição da tool de montar personagem manda consultar ela, e o erro de traço inválido também aponta pra ela. Assim o modelo tem onde buscar, em vez de inventar um id que não existe.

Devolva o que o modelo vai precisar no próximo passo. A seed no JSON parece detalhe, mas é ela que permite pedir "agora essa mesma pessoa com 10 anos".

Nem tudo precisa passar pelo MCP. As ilustrações desse post foram desenhadas no Figma pelo terminal, mas os comandos que eu acrescentei ao plugin do Talk to Figma eu chamo por um script que fala direto com o relay, num lote de mais de 200 passos. MCP é a porta pra IA conversar com a ferramenta. Quando quem dirige é um script, um cliente simples resolve.

Cuidados de segurança#

A própria spec é direta: tools representam execução arbitrária de código. Então:

  • Saiba quem roda o quê. Um servidor por stdio é um processo na sua máquina, com as suas permissões: ele lê os seus arquivos e acessa a sua rede. Um servidor remoto roda na máquina de outra pessoa, e tudo que você manda pra ele sai do seu computador.
  • Instale servidor MCP como instala dependência. Leia o código, fixe a versão, desconfie de servidor sem dono claro. No Talk to Figma, eu fiz o relay aceitar só conexões de 127.0.0.1 e tirei o Google Analytics do plugin antes de usar.
  • Não aprove tudo no automático. A spec pede que o host tenha o seu consentimento antes de chamar qualquer tool, e que você sempre possa negar. Liberar geral é abrir mão disso.
  • Anotações são dica, não garantia. O readOnlyHint: true diz que a tool só lê, mas a spec manda tratar anotação como não confiável, a menos que o servidor seja de confiança.
  • Cuidado com o que volta. O resultado de uma tool entra no contexto do modelo. Uma página da web ou uma issue podem trazer instruções escondidas, e o modelo pode tentar segui-las.

Referências#

Escrito por

Engenheira de software e designer. Escrevo sobre o que encontro construindo apps, APIs e produtos.