O que é MCP (Model Context Protocol): o guia em português

MCP (Model Context Protocol) é um padrão aberto que define como aplicativos de IA, como Claude, ChatGPT, Cursor e Codex, se conectam a sistemas externos para ler dados e executar ações. Um MCP server é o programa que fica do outro lado dessa conexão: ele declara, num formato padrão, as ferramentas e os dados que oferece, e qualquer aplicativo compatível passa a usá-los sem integração sob medida. Criado pela Anthropic em novembro de 2024 e doado à Linux Foundation em dezembro de 2025, o MCP virou a forma padrão de dar "mãos" a uma IA. Este guia explica o protocolo do conceito ao código: a arquitetura, a diferença para function calling e RAG, como instalar nas ferramentas mais usadas, os riscos de segurança e como criar o seu próprio servidor.

Parte 1: Fundamentos

O que é MCP, em duas frases?

MCP é um protocolo aberto que padroniza como um aplicativo de IA descobre e usa ferramentas e dados de sistemas externos. Em vez de cada aplicativo escrever uma integração para cada serviço, o serviço publica um MCP server uma vez e todo aplicativo compatível passa a enxergar as mesmas capacidades.

No nome, "model" é o modelo de linguagem, "context" é tudo o que ele não sabe sozinho (seus arquivos, seu banco, sua conta no gateway) e "protocol" é o acordo de formato entre as partes (definição oficial).

Que problema o MCP resolve?

O problema é aritmético. Com M aplicativos de IA e N serviços, alguém precisava escrever até M × N integrações: o conector do Notion para o Claude, outro para o Cursor, outro para o ChatGPT. O anúncio da Anthropic descreve sistemas em que "cada nova fonte de dados exige sua própria implementação" (anthropic.com, nov/2024). Com um protocolo comum, a conta vira M + N: cada lado implementa uma vez e as combinações saem de graça. Um ano depois do lançamento, a Anthropic contabilizava mais de 97 milhões de downloads mensais dos SDKs e mais de 10 mil servidores ativos (anthropic.com, dez/2025).

MCP é o "USB-C das IAs"? Qual a melhor analogia?

A documentação oficial compara o MCP a uma porta USB-C: um conector padrão para muitos aparelhos. Acerta no principal e erra num detalhe que importa: o cabo USB-C é passivo, não decide nada.

Para o leitor brasileiro, uma analogia mais fiel é o Pix das integrações de IA: qualquer instituição participante fala com qualquer outra por um padrão único, sem acordo bilateral. O MCP faz o mesmo entre aplicativos de IA e serviços.

Mas nenhuma das duas captura o que explica tanto o poder quanto o risco do protocolo: no MCP, o servidor se descreve e quem lê a descrição é o modelo. Cada ferramenta chega com nome, descrição em linguagem natural e formato dos parâmetros; o modelo lê esse "cardápio" e decide sozinho o que chamar. Um Pix nunca decide para quem mandar dinheiro lendo um texto; uma IA com MCP decide lendo textos. Essa diferença volta na seção de segurança.

Quem criou o MCP e quem mantém o padrão hoje?

A Anthropic publicou o MCP como padrão aberto em 25 de novembro de 2024. Em 9 de dezembro de 2025, doou o protocolo à Agentic AI Foundation (AAIF), um fundo da Linux Foundation cofundado com Block e OpenAI e apoiado por Google, Microsoft, AWS, Cloudflare e Bloomberg (Linux Foundation). A especificação, os SDKs e o registro seguem em aberto no GitHub modelcontextprotocol. Com suporte em Claude, ChatGPT, Cursor, VS Code, Codex, Gemini e Copilot, o MCP deixou de ser "o protocolo da Anthropic" e virou infraestrutura comum do setor.

Qual a versão atual do protocolo?

A versão vigente da especificação é a 2026-07-28 (as versões são identificadas por data). Ela tornou o protocolo sem estado (stateless): cada requisição carrega a versão e as capacidades do client no campo _meta, e a descoberta é feita pela requisição server/discover. Tutoriais que descrevem um aperto de mão com sessão fixa falam das versões até a 2025-11-25. A mesma versão marcou como obsoletos o sampling e o logging do lado do client. Se você está começando agora, os SDKs oficiais cuidam da negociação de versão.

Parte 2: Como o MCP funciona por dentro?

A arquitetura oficial (modelcontextprotocol.io/docs/learn/architecture) tem três participantes, duas camadas e três primitivas principais do lado do servidor.

Host, client e server: quem é quem?

• Host é o aplicativo de IA onde você trabalha (Claude Code, Claude Desktop, Cursor, Codex). Ele coordena tudo e pede a sua autorização.
• Client é a conexão dedicada que o host abre para cada servidor: três servidores, três clients.
• Server é o programa que oferece as capacidades, na sua máquina (local) ou na infraestrutura de uma empresa (remoto).

┌──────────── Host (Claude Code, Cursor, Codex) ────────────┐
│  Client 1 ───────── stdio ─────────▶ Server local: arquivos │
│  Client 2 ───────── stdio ─────────▶ Server local: banco    │
│  Client 3 ──── Streamable HTTP ────▶ Server remoto: API     │
└────────────────────────────────────────────────────────────┘
        cada server expõe: tools · resources · prompts

Tools, resources e prompts: o que um MCP server oferece?

Tools são o que exige mais cuidado: a especificação diz que ferramentas "representam execução arbitrária de código" e que o host deve obter consentimento explícito do usuário antes de chamar qualquer uma (especificação).

Do lado do client existe a primitiva elicitation, pela qual o servidor pede uma informação ou confirmação ao usuário no meio de uma operação.

O que acontece numa chamada, passo a passo?

1. Listagem. O client envia tools/list e recebe as ferramentas, cada uma com name, description e inputSchema (um JSON Schema dos parâmetros).
2. Decisão. Você pede algo em linguagem natural; o modelo lê as descrições, escolhe a ferramenta e monta os argumentos.
3. Aprovação. O host mostra a chamada e pede sua autorização, a menos que você tenha liberado aquela ferramenta.
4. Execução. O client envia tools/call; o servidor executa e devolve o resultado num array content, que o modelo usa para responder.

Tudo trafega em JSON-RPC 2.0, por dois transportes oficiais: stdio, em que o host inicia o servidor como processo local, e Streamable HTTP, para servidores remotos, com autenticação por token ou, preferencialmente, OAuth. O antigo transporte SSE está obsoleto.

Parte 3: MCP vs function calling vs plugins vs RAG

O MCP não substitui o que já existia: padroniza uma camada que cada fornecedor resolvia do seu jeito.

O resumo em uma linha: function calling é como o modelo pede para chamar uma função; MCP é como o aplicativo descobre quais funções existem e de onde vêm. Os dois convivem: o host recebe as ferramentas via MCP e as entrega ao modelo usando o function calling do provedor.

RAG também não compete com MCP: um MCP server pode ser justamente o caminho para buscar os trechos que o RAG coloca no contexto.

MCP é a mesma coisa que uma API?

Não. A API é o serviço; o MCP server é uma camada que a traduz para a IA, e muitos servidores só recebem a chamada e chamam a API REST por baixo. A API é feita para um programador ler a documentação; o MCP server, para um modelo descobrir sozinho o que pode fazer.

E o llms.txt, onde entra?

O llms.txt é complementar: um arquivo com a documentação do serviço escrita para o contexto de uma IA. O MCP executa (a ação acontece); o llms.txt ensina (a IA lê e escreve o código de integração). É o caminho para ferramentas que não aceitam MCP.

Parte 4: Como instalar um MCP server nas ferramentas populares?

Comandos conferidos nas documentações oficiais em 23 de setembro de 2026; a fonte de cada bloco está linkada.

Como adicionar um MCP server no Claude Code?

O Claude Code registra servidores com claude mcp add (docs do Claude Code). Para um servidor remoto, o recomendado é o transporte HTTP:

# Servidor remoto (exemplo: Notion)
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Servidor local por stdio: as opções vêm antes do nome e o "--" separa o comando do servidor
claude mcp add --env AIRTABLE_API_KEY=SUA_CHAVE --transport stdio airtable -- npx -y airtable-mcp-server

Gerencie com claude mcp list, claude mcp get <nome> e claude mcp remove <nome>; dentro da sessão, /mcp mostra o status e faz o login OAuth. O --scope define onde a configuração vive: local (padrão, só você neste projeto), project (.mcp.json versionado, para o time) ou user (você, em todos os projetos). Chave de API nunca vai no .mcp.json versionado.

Como adicionar um MCP server no Claude Desktop e no claude.ai?

Há dois caminhos (Central de Ajuda da Anthropic):

• Servidor remoto (conector personalizado): nos planos Pro e Max, vá em Customize > Connectors, clique em "+" e escolha "Add custom connector"; informe a URL do servidor e, se necessário, as credenciais OAuth nas configurações avançadas. Em Team e Enterprise, quem adiciona é o dono da organização, em Organization settings > Connectors. O plano gratuito também aceita conectores personalizados, limitado a um.
• Servidor local (stdio): edite o arquivo claude_desktop_config.json (no macOS, em ~/Library/Application Support/Claude/; no Windows, em %APPDATA%\Claude\) e reinicie o aplicativo:

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": ["--directory", "/CAMINHO/ABSOLUTO/weather", "run", "weather.py"]
    }
  }
}

Como adicionar um MCP server no Cursor?

O Cursor lê a configuração de .cursor/mcp.json (vale para o projeto) ou de ~/.cursor/mcp.json (vale para todos os projetos) (docs do Cursor):

{
  "mcpServers": {
    "meu-servidor-local": {
      "command": "npx",
      "args": ["-y", "nome-do-pacote-mcp"],
      "env": { "API_KEY": "${env:MINHA_API_KEY}" }
    },
    "meu-servidor-remoto": {
      "url": "https://exemplo.com/mcp",
      "headers": { "Authorization": "Bearer ${env:MEU_TOKEN}" }
    }
  }
}

A sintaxe ${env:NOME} lê a variável do sistema, para versionar o arquivo sem expor a chave. Há instalação em um clique pelo Marketplace e pelo cursor.directory, e por padrão o Cursor pede aprovação antes de cada ferramenta MCP.

Como adicionar um MCP server no Codex?

O Codex, da OpenAI, compartilha a mesma configuração entre o Codex CLI, a extensão de IDE e o app desktop do ChatGPT (docs do Codex):

# Servidor local, com variáveis de ambiente
codex mcp add context7 --env MINHA_VAR=valor -- npx -y @upstash/context7-mcp

# Login em servidor remoto que usa OAuth
codex mcp login <nome-do-servidor>

Ou direto em ~/.codex/config.toml:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

[mcp_servers.meu_remoto]
url = "https://mcp.exemplo.com"
bearer_token_env_var = "MEU_TOKEN"

No terminal, /mcp mostra os servidores ativos. As chaves enabled_tools e disabled_tools ligam só parte das ferramentas de um servidor.

Parte 5: O MCP é seguro?

O protocolo é tão seguro quanto os servidores que você instala e as permissões que você concede. A própria especificação admite que o MCP não consegue impor seus princípios de segurança no nível do protocolo: host, servidor e usuário precisam fazer sua parte. Quatro pontos cobrem quase todos os riscos.

Boas práticas para quem usa MCP

• Instale só de fontes verificáveis: o site ou repositório oficial do serviço, ou o registro oficial. Desconfie de pacote com nome parecido com o de uma marca.
• Mantenha a aprovação ligada para ferramentas que escrevem, apagam ou enviam algo, e leia os argumentos antes de aprovar. "Permitir sempre" só para leitura em servidor confiável.
• Use a chave mais fraca que resolve: leitura quando só precisa ler, chave de sandbox enquanto testa, modo somente leitura quando existir (o GitHub tem --read-only).
• Separe sessões: não junte, na mesma sessão, um servidor que lê conteúdo público e outro que mexe em dado sensível ou dinheiro.
• Chave fora do chat e do git: credencial vai em variável de ambiente. Se desconfiar de vazamento, gere outra no painel.

Parte 6: Como criar um MCP server?

Os SDKs oficiais (Python, TypeScript, Java, Kotlin, C# e outros) transformam uma função comum numa ferramenta, gerando nome, descrição e schema a partir do código. Os exemplos abaixo seguem o tutorial oficial Build an MCP server da versão 2026-07-28 e expõem uma ferramenta útil em pagamentos: converter um valor escrito por uma pessoa em centavos, o formato que as APIs esperam.

Esqueleto em Python

Instale o SDK num projeto gerenciado pelo uv:

uv init centavos && cd centavos
uv add "mcp[cli]"

Crie server.py:

from decimal import Decimal

from mcp.server import MCPServer

mcp = MCPServer("centavos")


@mcp.tool()
def reais_para_centavos(valor: str) -> str:
    """Converte um valor em reais escrito por uma pessoa (ex.: "R$ 1.234,56") em centavos inteiros.

    Args:
        valor: Valor em reais, com vírgula como separador decimal
    """
    limpo = valor.replace("R$", "").replace(".", "").replace(",", ".").strip()
    return str(int(Decimal(limpo) * 100))


if __name__ == "__main__":
    mcp.run(transport="stdio")

A docstring vira a descrição que o modelo lê e o tipo do parâmetro vira o schema: escreva a docstring pensando no modelo.

Esqueleto em TypeScript

npm install @modelcontextprotocol/server zod
npm install -D @types/node typescript

import { McpServer } from "@modelcontextprotocol/server";
import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
import { z } from "zod";

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

server.registerTool(
  "reais_para_centavos",
  {
    description: 'Converte um valor em reais (ex.: "R$ 1.234,56") em centavos inteiros',
    inputSchema: z.object({
      valor: z.string().describe("Valor em reais, com vírgula como separador decimal"),
    }),
  },
  async ({ valor }) => {
    const limpo = valor.replace("R$", "").replace(/\./g, "").replace(",", ".").trim();
    const centavos = Math.round(Number(limpo) * 100);
    return { content: [{ type: "text", text: String(centavos) }] };
  }
);

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Servidor MCP rodando em stdio");
}

main();

A configuração de package.json e tsconfig.json para compilar está no tutorial oficial.

A armadilha número um: não escreva em stdout

Num servidor stdio, a saída padrão é o canal do protocolo. Um print() em Python ou um console.log() em Node corrompe as mensagens JSON-RPC e quebra o servidor. Registre logs em stderr (console.error() no Node). A documentação oficial repete o aviso em todas as linguagens.

Como testar e conectar o servidor

1. Teste isolado no MCP Inspector, ferramenta oficial que lista e chama as ferramentas sem modelo no meio.
2. Conecte num host, por exemplo: claude mcp add centavos -- uv --directory /caminho/absoluto/centavos run server.py.
3. Peça em linguagem natural ("quanto é R$ 1.234,56 em centavos?") e confira a chamada reais_para_centavos antes de aprovar.

O que separa um servidor bom de um perigoso?

• Ferramentas específicas, não genéricas: "criar_link_de_cobranca" em vez de "chamar_qualquer_endpoint". Schema estreito é fácil de auditar e limita o estrago de uma injeção.
• Descrições escritas para o modelo: ele escolhe pelo texto; descrição vaga gera chamada errada.
• Tipos rígidos: enum para valores fechados, inteiro para dinheiro em centavos.
• Local ou remoto: stdio fica restrito à máquina de quem instala; Streamable HTTP atende muitos usuários e exige autenticação (a especificação recomenda OAuth).

Parte 7: O ecossistema de MCP servers

Onde encontrar MCP servers?

• Registro oficial do MCP (modelcontextprotocol.io/registry): metadados centralizados de servidores públicos, apoiado por Anthropic, GitHub, PulseMCP e Microsoft, ainda em prévia. Guarda metadados, não código (o pacote segue no npm, PyPI ou Docker Hub). Os nomes seguem DNS reverso (io.github.usuario/servidor) e só o dono verificado da conta ou do domínio publica naquele espaço, o que dificulta servidor falso com nome de marca.
• Servidores de referência (github.com/modelcontextprotocol/servers): implementações de exemplo mantidas pelo projeto, como o servidor de sistema de arquivos.
• Marketplaces dos hosts: o Cursor tem Marketplace e o cursor.directory; o Claude tem o diretório de conectores. Eles consomem o registro oficial e adicionam curadoria.

Observação honesta: o registro delega a varredura de segurança aos registros de pacotes e aos marketplaces. Estar listado prova quem publicou, não que o código é seguro.

Quais são os MCP servers mais conhecidos?

Verificado em setembro/2026.

Quais gateways de pagamento brasileiros têm MCP?

Em setembro de 2026, têm MCP server oficial: Asaas (docs.asaas.com/mcp), Efí (github.com/efipay/mcp-server-efi) e AbacatePay, além do Stripe, cujo Pix no Brasil é só por convite. O do HeroPay está em desenvolvimento; até ele sair, a integração com IA no HeroPay passa pelo llms.txt e pela API REST. Compare o que cada MCP expõe e o preço de cada cobrança que a IA vai criar: veja a comparação Stripe vs HeroPay e o ranking de melhores gateways de pagamento.

Parte 8: O caso pagamentos, e onde o HeroPay está hoje

Pagamento é o teste mais duro para um MCP server, porque o erro não é um arquivo mal formatado: é dinheiro. Antes de conectar o MCP de qualquer gateway (os da Parte 7, como Stripe, Asaas, Efí e AbacatePay), confira se ele segue as regras deste guia.

O que um MCP de pagamentos bem desenhado aplica:

O HeroPay hoje. O MCP server do HeroPay está em desenvolvimento. O caminho que funciona hoje, em qualquer ferramenta (Claude, ChatGPT, Cursor, Lovable e outros), é o llms.txt: cole https://heropay.ai/llms.txt e o link da documentação no chat, e a IA escreve no seu código a integração com a API REST, com a chave no servidor e o webhook validado pelo header X-HeroPay-Signature (HMAC SHA-256 do corpo bruto). Para conferir o contrato real sem MCP, peça à IA um curl contra o sandbox e mostre a resposta a ela. O passo a passo por ferramenta está em Claude, Cursor e Lovable, e o panorama em /ai.

Quanto custa. O HeroPay não cobra pelo llms.txt, pelo sandbox nem por chamada de API. Você paga só as vendas aprovadas: Pix R$ 0, boleto R$ 0 e cartão 3,49% por transação aprovada, em até 12x, sem mensalidade. Numa venda de R$ 197 no Pix, você recebe R$ 197. Veja a tabela completa em preços.

Coloque em prática

1. Instale um MCP server de leitura primeiro, como o Context7 ou o GitHub em modo --read-only, para ver o ciclo listar, decidir, aprovar e executar sem risco.
2. Crie o esqueleto deste guia em Python ou TypeScript e teste no MCP Inspector.
3. Integre pagamentos no sandbox. Crie a conta, guarde a chave de teste em variável de ambiente, cole o llms.txt do HeroPay na sua ferramenta de IA e peça o primeiro link de cobrança em português:

Criar conta sandbox · Ler a documentação

Mitos e verdades sobre MCP

"MCP é coisa só do Claude." Mito. A Anthropic criou o protocolo, mas ele está na Linux Foundation desde dezembro de 2025 e é suportado por ChatGPT, Codex, Cursor, VS Code, Gemini, Copilot e outros.

"Com MCP, a IA aprende a usar o sistema." Mito. O modelo não é retreinado. Ele recebe, na hora, a lista de ferramentas com descrição e parâmetros, e decide com base nesse texto.

"MCP substitui a API." Mito. A maioria dos MCP servers chama a API do serviço por baixo. O produto que atende clientes continua usando API e SDK; o MCP é para a IA operar e prototipar.

"Se está no registro oficial, é seguro." Mito. O registro verifica quem publicou (conta do GitHub ou domínio), não audita o código. Segurança continua sendo sua avaliação.

"Injeção de prompt é teórica." Mito. Há demonstrações públicas com servidores reais desde 2025, incluindo vazamento de repositórios privados.

"Dá para criar um MCP server em uma tarde." Verdade, para um servidor local simples. Um servidor remoto para muitos usuários, com OAuth e escopos, é outro projeto.

Glossário do tema

• MCP (Model Context Protocol): padrão aberto que define como aplicativos de IA descobrem e usam ferramentas e dados de sistemas externos.
• MCP server: programa que expõe tools, resources e prompts para aplicativos de IA via MCP.
• stdio e Streamable HTTP: os dois transportes oficiais, o primeiro para servidores locais, o segundo para remotos.
• JSON-RPC: formato leve de requisição e resposta em JSON usado pelas mensagens do MCP.
• Tool poisoning: ataque em que instruções maliciosas ficam escondidas na descrição de uma ferramenta.
• Injeção de prompt: instrução maliciosa inserida em conteúdo que a IA lê, para desviá-la do pedido do usuário.
• llms.txt: arquivo de texto com a documentação de um serviço escrita para ser lida por uma IA.

Continue aprendendo

• HeroPay para quem constrói com IA: llms.txt, API e MCP em desenvolvimento
• Aceite pagamentos no Claude · no Cursor · no Lovable
• HeroPay para desenvolvedores
• Webhooks assinados: confie no evento, não no polling
• Link de pagamento
• Segurança no HeroPay
• Preços · Glossário

Fontes e verificação

Todas as fontes consultadas em 23 de setembro de 2026.

• Model Context Protocol, introdução: modelcontextprotocol.io/docs/getting-started/intro
• Arquitetura (versão 2026-07-28): modelcontextprotocol.io/docs/learn/architecture
• Especificação vigente e princípios de segurança: modelcontextprotocol.io/specification/latest
• Boas práticas de segurança: modelcontextprotocol.io/docs/tutorials/security/security_best_practices
• Tutorial oficial de servidor: modelcontextprotocol.io/docs/develop/build-server
• Registro oficial: modelcontextprotocol.io/registry/about
• Anthropic, lançamento do MCP (25/11/2024): anthropic.com/news/model-context-protocol
• Anthropic, doação à Agentic AI Foundation (dez/2025): anthropic.com/news/donating-the-model-context-protocol-and-establishing-of-the-agentic-ai-foundation
• Linux Foundation, criação da AAIF: linuxfoundation.org
• Claude Code, MCP: code.claude.com/docs/en/mcp
• Claude, conectores personalizados: support.claude.com
• Cursor, MCP: cursor.com/docs/context/mcp
• Codex, MCP: learn.chatgpt.com/docs/extend/mcp
• GitHub MCP server: github.com/github/github-mcp-server
• Stripe MCP: docs.stripe.com/mcp
• Invariant Labs, tool poisoning (abr/2025): invariantlabs.ai · GitHub MCP (mai/2025): invariantlabs.ai
• Simon Willison, injeção de prompt em MCP: simonwillison.net