Configuração MCP no OpenCode: adicione servidores, OAuth e corrija timeouts

Você adiciona um servidor MCP ao opencode.json, reinicia o terminal e as ferramentas nunca aparecem. Ou elas aparecem, o login no navegador abre, mas o retorno nunca chega. Ou tudo funciona até a primeira chamada lenta morrer com um timeout. Essas três falhas explicam a maior parte dos problemas com a configuração MCP no OpenCode, e cada uma tem uma correção curta e simples.

Este artigo percorre os campos exatos que o OpenCode lê, os comandos que mostram o que está errado e as configurações que acabam com o chute. Os trechos seguem a documentação oficial de MCP do OpenCode conferida em outubro de 2026, então cole-os como estão e altere apenas os nomes, caminhos e URLs.

Onde o OpenCode lê sua configuração

O OpenCode não escolhe um arquivo de configuração e ignora os outros. Ele mescla todas as fontes que encontra e, quando duas fontes definem o mesmo campo, vence a que vem depois na ordem abaixo. É por isso que um servidor que você "removeu" do arquivo do projeto continua voltando: ele ainda está definido no seu arquivo global.

Locais de configuração e ordem de mesclagem

Tanto JSON quanto JSONC (JSON com comentários) funcionam. Adicionar "$schema": "https://opencode.ai/config.json" no topo dá ao seu editor autocompletar e sublinhados vermelhos em erros de digitação. Erros de digitação são a razão mais comum de um servidor ser ignorado em silêncio, então a linha do schema se paga em poucos minutos.

💡 Dica: Quando um servidor se comporta de forma estranha, verifique primeiro o arquivo global. Uma entrada desatualizada ali pode substituir uma entrada perfeitamente boa do projeto.

Use variáveis, não segredos colados

O OpenCode substitui dois marcadores em qualquer lugar da configuração. {env:NAME} lê uma variável de ambiente, e {file:path} insere o conteúdo de um arquivo. Use-os para todo token, para que a configuração continue segura para versionar.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "tracker": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer {env:TRACKER_TOKEN}"
      }
    }
  }
}

Copiar prompt

Caminhos de arquivo relativos são resolvidos a partir do diretório da configuração, enquanto caminhos que começam com / ou ~ são absolutos. Se a variável estiver ausente no shell que iniciou o OpenCode, o servidor nunca recebe um token válido e responde 401, o que parece exatamente um token errado. Exporte a variável no mesmo shell e depois inicie o OpenCode a partir dele.

Adicione servidores locais e remotos

Tudo fica sob um campo de nível superior chamado mcp. Cada item filho é um servidor com um nome que você escolhe, e esse nome vira o prefixo das suas ferramentas, então escolha nomes curtos, em minúsculas e sem espaços.

Um servidor local mínimo

Um servidor local é um processo que o OpenCode inicia para você e com o qual se comunica pela entrada e saída padrão.

{
  "mcp": {
    "files": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/home/dev/projects"],
      "enabled": true,
      "timeout": 15000
    }
  }
}

Copiar prompt

Dois campos são obrigatórios: "type": "local" e command. O ponto que costuma confundir as pessoas é que command é um array de strings, uma entrada por argumento, e não uma única string de shell. Escrever "command": "npx -y some-server" é o jeito mais rápido de ter um servidor que nunca inicia.

Variáveis de ambiente e diretório de trabalho

Servidores locais muitas vezes precisam de credenciais ou de uma pasta específica. environment passa variáveis para o processo filho, e cwd define o diretório de trabalho dele. Caminhos relativos em cwd são resolvidos a partir do workspace.

{
  "mcp": {
    "reports": {
      "type": "local",
      "command": ["node", "./tools/reports-server.js"],
      "cwd": "./mcp",
      "environment": {
        "API_TOKEN": "{env:REPORTS_API_TOKEN}",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Copiar prompt

Um servidor remoto com headers

Um servidor remoto já está rodando em outro lugar, então o OpenCode só precisa de um endereço e, normalmente, de uma credencial.

{
  "mcp": {
    "docs": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer {env:DOCS_MCP_TOKEN}"
      },
      "oauth": false,
      "timeout": 20000
    }
  }
}

Copiar prompt

Definir "oauth": false é a escolha certa para qualquer servidor que autentica com um token estático. Sem ele, o OpenCode trata um 401 como sinal para iniciar um login OAuth, o que confunde quando o problema real é um token ruim.

Verifique o resultado com mcp list

Execute opencode mcp list depois de cada edição. Ele mostra cada servidor configurado e seu status, para você saber em dois segundos se um servidor conectou, precisa de autenticação ou falhou. Faça isso antes de abrir uma sessão e se perguntar por que as ferramentas não aparecem.

Aqui está a referência completa dos campos em um só lugar:

💡 Dica: Defina "enabled": false em servidores que você só precisa de vez em quando. A entrada continua no arquivo, e nada é carregado na sua sessão até você reativá-la.

Corrija problemas de login OAuth

Servidores remotos que seguem o fluxo de autorização MCP quase não precisam de configuração. Quando o OpenCode recebe um 401, ele inicia o OAuth sozinho, se registra como cliente por meio de Dynamic Client Registration (RFC 7591), abre seu navegador e aguarda o redirecionamento. Os tokens resultantes são armazenados em ~/.local/share/opencode/mcp-auth.json.

Como funciona o OAuth automático

Para um servidor que oferece suporte a isso, a configuração inteira são dois campos e um comando.

1. Adicione o servidor apenas com type e url.
2. Execute opencode mcp auth tracker, substituindo tracker pelo nome do seu servidor.
3. Aprove a solicitação na aba do navegador que abrir.
4. Execute opencode mcp list e confirme que o servidor aparece como conectado.

Quatro comandos cuidam de todo o ciclo de vida:

Quando um login que funcionava na semana passada de repente falha, a causa costuma ser um token desatualizado ou revogado. Execute opencode mcp logout <name>, depois opencode mcp auth <name> de novo, e você começa do zero.

Clientes pré-registrados e escopos

Alguns provedores recusam o registro dinâmico e querem que você registre um app manualmente. Nesse caso, forneça ao OpenCode os dados do cliente que ele criaria sozinho.

{
  "mcp": {
    "tracker": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "clientId": "{env:TRACKER_CLIENT_ID}",
        "clientSecret": "{env:TRACKER_CLIENT_SECRET}",
        "scope": "tools:read tools:execute"
      }
    }
  }
}

Copiar prompt

O valor de scope é uma única string com os escopos separados por espaços, exatamente como o provedor os documenta. Peça o menor conjunto que funciona. Um escopo amplo que o provedor rejeita gera um erro na página de login que não diz nada útil sobre qual escopo era o problema.

O login falha em uma máquina remota

Este é o problema que consome uma tarde inteira. O OpenCode escuta uma porta local de callback enquanto você faz login, e relatos de usuários colocam o padrão em 19876. Se o OpenCode roda em um host remoto via SSH, seu navegador no notebook redireciona para 127.0.0.1:19876 no notebook, onde não há nada escutando. A aprovação é concluída, o callback nunca chega e o comando acaba dando timeout.

A correção é um encaminhamento de porta do seu notebook para o host remoto:

ssh -o ExitOnForwardFailure=yes -L 127.0.0.1:19876:127.0.0.1:19876 user@remote-host

Copiar prompt

Execute opencode mcp auth <name> dentro dessa sessão SSH, abra a URL impressa no seu navegador local, e o callback agora passa pelo túnel.

Versões recentes também aceitam callbackPort e redirectUri dentro do objeto oauth, para provedores que exigem um callback fixo e pré-registrado. A URI de redirecionamento deve usar http:// com localhost, 127.0.0.1 ou [::1] e uma porta explícita. Se você mudar a porta, encaminhe essa mesma porta. Confira o schema no seu editor antes de confiar em qualquer um dos dois campos, já que versões antigas não os reconhecem.

Correções de timeout que funcionam

Existem dois timeouts diferentes, e confundi-los desperdiça horas. Um define quanto tempo o OpenCode espera um servidor iniciar e listar suas ferramentas. O outro define quanto tempo uma única chamada de ferramenta pode durar depois que o servidor está no ar.

O padrão de inicialização

O campo timeout é em milissegundos e tem como padrão 5000 tanto para servidores locais quanto remotos. Cinco segundos bastam para um script pequeno. Não bastam para npx -y com cache frio, porque o pacote precisa ser baixado antes de o servidor sequer iniciar. O servidor então aparece com falha e suas ferramentas nunca carregam.

Corrija nesta ordem:

1. Aumente o campo só para aquele servidor. Defina "timeout": 15000 ou 30000 na entrada lenta e deixe as outras como estão.
2. Remova o download. Instale o pacote globalmente com npm install -g e depois aponte command para o binário instalado. A inicialização cai para uma fração de segundo.
3. Teste o endpoint dos servidores remotos. Execute um curl simples contra a URL. Se o curl também estiver lento, o problema é a latência da rede ou o servidor, não a sua configuração.

Quando as chamadas de ferramenta morrem aos 60 segundos

Um erro diferente aparece depois, no meio de uma sessão: MCP error -32001: Request timed out. Esse é o timeout de requisição da biblioteca cliente MCP, e muitos clientes construídos sobre o SDK em TypeScript usam 60 segundos como padrão. Aumentar o timeout de inicialização não muda isso para uma chamada de ferramenta em execução.

Procure primeiro uma configuração por requisição no schema da sua versão. Se não houver, mude a ferramenta em vez do cliente. Faça a primeira ferramenta retornar um id de job imediatamente e adicione uma segunda ferramenta que informe o status do job. O modelo envia a tarefa, recebe um id e volta para verificar, que é o padrão de enviar e depois consultar que as APIs de geração de imagens e de geração de vídeo também usam, pelo mesmo motivo.

💡 Dica: Envie os logs do servidor para o stderr, nunca para o stdout. Um servidor local compartilha o stdout com o protocolo, então um único console.log perdido pode corromper o handshake e parecer um timeout.

Depure um servidor que não conecta

Quando a correção não é óbvia, pare de editar a configuração e teste cada camada separadamente.

Execute o servidor manualmente

Copie o array command para um terminal e execute-o em uma única linha. Um servidor stdio saudável inicia e fica esperando entrada em silêncio. Se ele imprimir um erro, um módulo ausente ou um caminho ruim, você encontrou o problema sem o OpenCode no meio. Depois execute opencode mcp debug <name>, que diagnostica problemas de conexão e OAuth desse servidor específico.

Para um servidor remoto, curl -i a URL com os mesmos headers. Um 401 indica credenciais, um 404 indica o caminho, e um travamento indica a rede.

Erros comuns e correções

Mantenha o contexto pequeno por agente

Cada servidor conectado adiciona suas descrições de ferramentas ao contexto enviado em cada requisição. Um punhado de servidores pode consumir uma grande parte da janela de contexto antes de você digitar uma palavra, e o modelo fica pior para escolher a ferramenta certa quando tem cinquenta para escolher. A documentação do OpenCode diz isso com todas as letras: use servidores MCP com moderação.

Desative globalmente, ative por agente

Os nomes das ferramentas carregam o nome do servidor como prefixo, então um padrão glob liga ou desliga um servidor inteiro de uma vez. * corresponde a zero ou mais caracteres e ? corresponde a exatamente um.

{
  "tools": {
    "files_*": false,
    "tracker_*": false
  },
  "agent": {
    "builder": {
      "tools": { "files_*": true }
    },
    "planner": {
      "tools": { "tracker_*": true }
    }
  }
}

Copiar prompt

Com essa configuração, o agente builder enxerga apenas as ferramentas de sistema de arquivos e o agente planner enxerga apenas o tracker. Nenhum dos dois paga o custo em tokens da lista de ferramentas do outro servidor.

Como usar o Claude Sonnet 5

Bugs de configuração são uma correspondência de padrões tediosa: uma string onde deveria haver um array, uma variável que não foi exportada, uma porta que ninguém encaminhou. É aí que um modelo de programação mostra seu valor. O Claude Sonnet 5 no PicassoIA lê texto de configuração, saída de erro e até capturas de tela, então você pode colar o que vê e perguntar o que está errado.

1. Abra a página do modelo. Vá até Claude Sonnet 5 no PicassoIA e encontre a caixa de prompt.
2. Cole seu bloco mcp. Substitua antes todos os tokens e segredos por marcadores, depois adicione a saída de opencode mcp debug <name>.
3. Defina o esforço. O padrão low pula o raciocínio e responde mais rápido. Use medium ou high quando vários arquivos interagirem, por exemplo uma configuração global sobrescrita por uma configuração de projeto.
4. Adicione um prompt de sistema uma vez. Algo como: "Você revisa configurações MCP do opencode.json. Verifique type, command, timeout e oauth. Responda apenas com o JSON corrigido."
5. Anexe uma captura de tela, se tiver uma. A entrada de imagem lê erros do terminal. Aumente a resolução máxima da imagem quando o texto da captura estiver pequeno.
6. Mantenha max_tokens em 8192. Esse é o padrão e basta para alguns blocos de configuração.
7. Verifique antes de colar. Confira cada campo sugerido com a tabela acima e com a documentação oficial.

💡 Dica: Nunca cole um token real em nenhuma caixa de chat. Marcadores como TRACKER_TOKEN dão ao modelo tudo o que ele precisa.

Crie suas próprias imagens hoje

Configuração é só metade do que o MCP pode fazer. Quando um agente de programação consegue chamar ferramentas, ele também consegue chamar geradores de imagem. O PicassoIA expõe seus geradores via MCP, e o endereço do servidor fica na página de conexões MCP da sua conta. Qualquer servidor que fale HTTP segue o mesmo padrão remoto deste artigo: type, url, um header ou OAuth, e um timeout sensato.

Se preferir pular a configuração e só criar imagens, abra o Picasso IA e experimente estes modelos de texto para imagem:

• PicassoIA Image para resultados rápidos e de uso geral
• Seedream 5 Pro para cenas fotográficas e detalhadas
• GPT Image 2 para prompts com layouts precisos
• FLUX 2 Pro para texturas nítidas e luz natural

Escolha um, escreva um prompt sobre o que você acabou de configurar e compare como cada modelo interpreta. Dez minutos de experimentação ensinam mais sobre a redação de prompts do que uma hora de leitura, e cada imagem gerada é um ensaio gratuito para a próxima.