OpenCode e MCP: o que é o Model Context Protocol e como ele entra no fluxo do agente?

Um agente de código, sozinho, enxerga só o repositório aberto na sua frente

Ele lê arquivo, escreve arquivo, roda comando e para por aí

O MCP é o protocolo que abre a porta pro que vive do lado de fora: dados e ferramentas externas, num formato padronizado, em vez de uma integração na unha pra cada serviço

E o OpenCode entra nessa história como cliente desse protocolo

Aqui eu fico em três coisas: o que é o MCP de verdade, que tipo de ganho ele traz pra quem usa um agente de código, e o que conferir na documentação oficial antes de sair ligando servidor

Bora? 🙂

O que é o Model Context Protocol (MCP) e quem cuida dele hoje

O MCP é um protocolo aberto que padroniza a integração entre aplicações de LLM e fontes de dados e ferramentas externas

Traduzindo: em vez de cada agente inventar o seu próprio jeito de conversar com cada ferramenta, todo mundo fala o mesmo idioma

Se você conhece a ideia de plugin, dá pra chegar perto assim: o MCP é o contrato que diz COMO o plugin se apresenta e COMO o modelo aciona ele

Formação Recomendada

Formação Vibe Coding

Do Prompt ao Produto: Crie Software Real com IA

• 474 aulas
• 20 projetos
• 39h 27min

Conhecer formação

Servidor e cliente: quem é quem?

Boa pergunta pra resolver logo, porque os dois nomes aparecem o tempo todo

O servidor MCP é o lado que expõe as ferramentas

O cliente é o lado que consome essas ferramentas e entrega elas pro modelo, e é esse o papel do OpenCode

A escala que o protocolo tomou

Os SDKs Tier 1 do MCP somam perto de meio bilhão de downloads por mês

Os SDKs de TypeScript e de Python já passaram de 1 bilhão de downloads acumulados cada um

Número de download não é medida de qualidade, mas serve pra uma coisa: não é hype de nicho, virou infraestrutura mesmo

Quem manda no projeto hoje

A Anthropic doou o Model Context Protocol para a Agentic AI Foundation (AAIF), um fundo dirigido sob a Linux Foundation, em 09/12/2025

A AAIF foi cofundada por Anthropic, Block e OpenAI, com apoio de Google, Microsoft, AWS, Cloudflare e Bloomberg

O MCP entrou como projeto fundador, ao lado do goose (Block) e do AGENTS.md (OpenAI)

E tem um detalhe que costuma preocupar quem depende do protocolo: o modelo de governança seguiu inalterado depois da doação, com os mantenedores tocando o mesmo processo aberto de decisão

O que a spec 2026-07-28 trouxe

A versão mais recente da especificação é a 2026-07-28, e ela mexeu no miolo

• núcleo stateless: o transporte deixou de ter sessão no nível do protocolo, e o header Mcp-Session-Id foi removido, pra que qualquer instância do servidor consiga responder à mesma requisição
• Multi Round-Trip Requests
• roteamento por header
• resultados de list cacheáveis
• endurecimento da autorização
• um framework formal de extensões, incluindo MCP Apps e a extensão Tasks

A spec completa mora em modelcontextprotocol.io, e vale a leitura se você mantém servidor próprio

Por que o MCP interessa a quem usa um agente de código

Aqui está o ponto que faz o protocolo sair do papel

O OpenCode é um agente de código open source pro terminal e atua como cliente MCP, conectando tanto a servidores locais quanto remotos

E as ferramentas expostas por esses servidores ficam disponíveis pro LLM ao lado das ferramentas nativas do OpenCode

Ou seja: pro modelo, não existe uma gaveta separada de "coisas de fora"

É tudo o mesmo conjunto de ferramentas na hora de decidir o próximo passo

O ganho real, sem promessa

O ganho não é mágica, é alcance

O agente deixa de ficar preso ao que está no disco e passa a poder acionar algo que vive fora do repositório, no meio da tarefa, sem você sair da conversa pra fazer aquilo na mão

Cada servidor declarado recebe um nome único, e esse nome pode ser citado no prompt

Isso muda o jeito de pedir: em vez de torcer pro modelo escolher certo, você aponta o servidor que quer que ele use

O que a documentação garante é o mecanismo, não um catálogo pronto de integrações

O que a ferramenta faz depende do servidor que você ligar

Como o OpenCode declara um servidor MCP na prática

Só o que está documentado, na ordem:

1. Declare o servidor na chave mcp do arquivo opencode.json, dando um nome único pra ele

O erro comum deste passo é repetir nome: o nome é a identidade do servidor e é o que você cita no prompt, então nome duplicado não tem como funcionar bem

2. Servidor local usa type: "local" com um array command, e aceita variáveis de ambiente quando o servidor precisa delas

3. Servidor remoto usa type: "remote" com url, e aceita headers quando o servidor precisa deles

O erro comum destes dois passos é trocar o tipo: colocar url num servidor declarado como local, ou tentar command num remoto

{
  "mcp": {
    "meu-servidor-local": {
      "type": "local",
      "command": ["comando-do-servidor", "argumento"],
      "enabled": true
    },
    "meu-servidor-remoto": {
      "type": "remote",
      "url": "https://endereco-do-seu-servidor/mcp",
      "enabled": true
    }
  }
}

4. Pra desligar um servidor sem apagar do config, use enabled: false

Ótimo pra isolar problema: desliga tudo, liga um por um e vê quem estava atrapalhando

5. Use os comandos de CLI em vez de editar tudo na mão

opencode mcp add
opencode mcp list
opencode mcp auth
opencode mcp auth list
opencode mcp debug

O add é guiado e cobre local e remoto

O list mostra os servidores configurados com status de conexão, e é aqui que aparece o erro mais comum de todos: servidor listado bonitinho no arquivo, mas sem conexão

O debug existe justamente pra investigar problema de conexão com OAuth

6. Em servidor remoto, deixe o OAuth acontecer

O OpenCode detecta a resposta 401 e inicia o fluxo, usando Dynamic Client Registration (RFC 7591) quando o servidor suporta

O comando de auth abre o navegador, e depois de autenticar os tokens ficam guardados em ~/.local/share/opencode/mcp-auth.json

O erro comum deste passo é autenticação pendente: o servidor aparece configurado, mas a conexão só fecha depois que você conclui o fluxo no navegador

O que verificar antes de ligar vários servidores MCP no OpenCode

Tem um custo que a própria documentação do OpenCode faz questão de avisar, e eu acho isso honesto da parte deles

Cada servidor MCP adiciona contexto

Com muitas ferramentas expostas, isso soma rápido, e a recomendação oficial é ter cuidado na escolha dos servidores ativos

Tome cuidado aqui: a tentação de ligar tudo "porque pode ser útil um dia" cobra o preço em toda mensagem que você manda

E a V2?

Existe uma V2 do OpenCode, e ela lê a configuração global e de projeto dos mesmos locais da V1

A configuração em formato V1 é traduzida em memória, sem reescrever o seu arquivo

Durante o beta, a V1 continua rodando como opencode e a V2 instala e roda separadamente como opencode2

Onde conferir a fonte

O que vale mesmo é a documentação oficial de MCP do OpenCode, que é de onde sai tudo que eu descrevi acima, e a especificação do protocolo em modelcontextprotocol.io

O projeto é mantido pelo time por trás do SST, que passou a se chamar publicamente Anomaly

O repositório oficial migrou de sst/opencode pro anomalyco/opencode, que hoje está em torno de 166 mil estrelas

Se você tem link antigo salvo, atualiza aí 😀

O que aprendi montando um agente com MCP

Esse agente eu montei no n8n, e o MCP ali é o mesmo protocolo que o OpenCode consome do outro lado

No vídeo eu monto o fluxo em duas metades: um workflow que expõe o servidor MCP e outro que consome esse servidor a partir de um agente

Essa divisão é exatamente a de quem publica as ferramentas e quem usa as ferramentas, e ficou muito mais clara pra mim depois de separar em dois workflows em vez de amontoar tudo num só

O servidor que eu montei expunha 3 ações: buscar e-mails, gerar um resumo em documento e enviar um e-mail

É pequeno de propósito, e serve bem pra sentir o que significa "ferramenta externa na mão do agente": o modelo decidia sozinho parâmetros como quantidade de e-mails e as datas do filtro, que é justamente o pedaço chato de fazer na mão

Detalhe que me pegou e pode te pegar: sem filtrar por caixa de entrada, o fluxo puxa também os e-mails enviados por você mesmo

E se o servidor não estiver ativado, ninguém acessa nada, nem consumidor local nem externo

No agente eu configurei memória simples com janela de 5 mensagens, e falo lá mesmo que 3 dariam conta da sequência real (pedir e-mails, pedir resumo, enviar e-mail)

Sobrou folga por segurança, e é aí que mora a lição transferível: menos ação exposta e menos contexto carregado costuma bastar

Isso conversa direto com o aviso do OpenCode sobre custo de contexto por ferramenta exposta

Outra coisa que eu faria de novo: testar o MCP com um agente montado no próprio ambiente antes de expor pra fora

Assim, quando quebra, você sabe que o problema é o seu MCP e não a integração do outro serviço

Quem quiser ir mais fundo nessa parte de orquestração, eu já escrevi sobre agentes de IA em fluxos n8n e sobre monitorar fluxos n8n quando o número de automações cresce

No vídeo acima dá pra ver o servidor MCP em pé e as ações sendo acionadas pelo agente, que é o conceito funcionando na tela antes de você mexer no opencode.json

Conclusão

O MCP virou o padrão de ligação entre LLM e ferramenta externa, com adoção grande nos SDKs e hoje mantido como projeto da Agentic AI Foundation, sob a Linux Foundation, com a governança seguindo igual depois da doação

O OpenCode consome esse padrão como cliente, colocando as ferramentas do servidor no mesmo conjunto das ferramentas embutidas do agente, com declaração na chave mcp do opencode.json e comandos de CLI pra adicionar, listar, autenticar e depurar

Próximo passo honesto: leia a documentação oficial de MCP do OpenCode, rode opencode mcp list pra ver o status de conexão do que já está configurado e comece com poucos servidores ativos, por causa do custo de contexto

Até o próximo post!