OpenCode + Scrapeless: Conectar um Servidor MCP Remoto

TL;DR:

• OpenCode usa Scrapeless como um remote servidor MCP em opencode.json. A entrada precisa de um url, um cabeçalho x-api-token e "oauth": false.
• Escreva a chave como {env:SCRAPELESS_API_KEY}, não ${SCRAPELESS_API_KEY}. OpenCode substitui a primeira forma e envia a segunda como texto literal, e o servidor ainda lista como conectado enquanto cada chamada de ferramenta falha com um 401.
• ✓ connected apenas prova que o cabeçalho está presente. O handshake do Scrapeless aceita qualquer valor x-api-token e ainda lista todas as 25 ferramentas, então leia um resultado de ferramenta antes de confiar na configuração.
• A configuração oauth decide como um erro de Bearer aparece. Deixado em seu padrão, um cabeçalho Authorization: Bearer mostra ⚠ needs authentication; com "oauth": false o mesmo cabeçalho mostra ✗ failed com um 401.
• As ferramentas chegam nomeadas <server>_<tool>. Uma entrada de servidor chamada scrapeless fornece o modelo scrapeless_scrape_markdown, e as 25 definições retornam como uma resposta tools/list de cerca de 30 KB.
• Obtenha uma chave no plano gratuito do Scrapeless e conecte OpenCode em poucos minutos.

OpenCode executa um agente de codificação em seu terminal contra o provedor de modelo que você configurar. Ele lê arquivos e executa comandos, mas uma pergunta sobre uma página da web ao vivo precisa de uma ferramenta que busque uma, e um servidor MCP é como o OpenCode pega ferramentas que não são enviadas com ele.

O servidor MCP do Scrapeless é hospedado, assim, conectá-lo é configuração, não instalação. Este guia cobre a entrada de configuração, a sintaxe de substituição que quebra silenciosamente, o que cada status opencode mcp list significa e como distinguir uma chave funcional de um servidor que simplesmente se conectou.

O Que o OpenCode Recebe do Scrapeless

O servidor lista 25 ferramentas. Três retornam uma página em uma chamada: scrape_markdown, scrape_html e scrape_screenshot. Dezesseis ferramentas browser_*, como browser_create, browser_goto, browser_click e browser_type, conduzem uma sessão de navegador em nuvem passo a passo. crawl_start, crawl_result e crawl_cancel gerenciam um rastreamento, e google_search, google_trends e ai_scraper completam o conjunto.

Para a maioria dos prompts, a útil é scrape_markdown. Ela retorna a página renderizada como Markdown, que é a forma que um modelo lê mais baratamente, e precisa apenas de uma URL.

Pré-requisitos

• OpenCode, com um provedor de modelo já configurado. Este guia usa OpenCode 1.17.19.
• Uma chave API do Scrapeless do painel do Scrapeless.
• Nada para instalar para o servidor. Ele roda em https://api.scrapeless.com/mcp e o OpenCode o alcança via HTTP.

Etapa 1: Adicionar o Servidor a opencode.json

OpenCode lê servidores MCP do bloco mcp de sua configuração. O arquivo global é ~/.config/opencode/opencode.json, e um opencode.json na raiz de um projeto se aplica a esse projeto:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "scrapeless": {
      "type": "remote",
      "url": "https://api.scrapeless.com/mcp",
      "oauth": false,
      "headers": {
        "x-api-token": "{env:SCRAPELESS_API_KEY}"
      }
    }
  }
}

"type": "remote" faz OpenCode conectar via HTTP em vez de lançar um comando local. "oauth": false impede que ele inicie um fluxo OAuth, que o endpoint do Scrapeless não oferece; seus caminhos de descoberta OAuth retornam 404, e ele se autentica apenas pelo cabeçalho. opencode mcp add também pode escrever uma entrada e aceita as flags --url e --header, mas editar o arquivo diretamente é a maneira confiável de conseguir a referência {env:} exatamente certa.

Etapa 2: Usar Substituição {env:}, Não ${}

OpenCode substitui {env:VARIABLE_NAME} pelo valor dessa variável de ambiente quando carrega a configuração. Variáveis de ambiente são o lar usual para credenciais que mudam entre máquinas, a mesma divisão que as diretrizes de configuração do aplicativo Twelve-Factor recomenda, e {env:} é como OpenCode as lê. Exporte a chave no shell que inicia o OpenCode:

export SCRAPELESS_API_KEY="your-scrapeless-api-key"
opencode mcp list

●  ✓ scrapeless connected
│      https://api.scrapeless.com/mcp

O estilo de shell ${SCRAPELESS_API_KEY} parece equivalente e não é. OpenCode o passa como texto literal, e como o handshake do Scrapeless aceita qualquer token não vazio, o servidor ainda lista ✓ connected. O problema aparece apenas quando o modelo chama uma ferramenta:

Failed to fetch data. Error: [Scrapeless]: Request POST /api/v1/unlocker/request failed with status 401

Deixar a variável não exportada falha mais cedo e de forma mais visível. Com {env:SCRAPELESS_API_KEY} apontando para nada, o próprio handshake é rejeitado:

●  ✗ scrapeless failed
│      SSE error: Non-200 status code (401)
│      https://api.scrapeless.com/mcp

Configurando isso agora? O plano gratuito do Scrapeless cobre a conexão e suas primeiras chamadas de ferramenta.

Etapa 3: Ler Cada Status da Lista mcp do opencode

A linha de status diz se o OpenCode conseguiu abrir a conexão. Não diz se a chave funciona.

Um modo de falha é parecido com uma chave ruim, mas não é. Se a linha de status diz conectado e uma chamada de ferramenta responde Failed to fetch data, verifique se outro servidor MCP na máquina expõe as mesmas ferramentas Scrapeless, como um gateway que roteia vários provedores atrás de uma única credencial. O agente pode ter chamado aquele em vez disso. OpenCode prefixa cada ferramenta com o nome de seu servidor, então a linha de transcrição nomina o servidor que respondeu.

A maioria dos exemplos de MCP se autentica com Authorization: Bearer, o esquema a especificação do token Bearer OAuth 2.0 define. Scrapeless lê x-api-token em vez disso, então um cabeçalho Bearer recebe uma resposta 401 Não Autorizado. Com oauth em seu padrão, OpenCode trata esse 401 como um convite para fazer login:

●  ⚠ scrapeless needs authentication
│      https://api.scrapeless.com/mcp

Com "oauth": false, o mesmo cabeçalho lê ✗ failed com o 401, que descreve um cabeçalho errado de forma mais precisa do que um convite para se autenticar.

Passo 4: Chamar uma Ferramenta de um Prompt

Nomeie o servidor e a ferramenta pela primeira vez, para que o resultado tenha apenas uma fonte possível:

Use the scrapeless MCP server's scrape_markdown tool on https://example.com
and reply with the first markdown heading line.

opencode run --format json imprime cada passo como um evento JSON. O evento da ferramenta daquele prompt:

type: tool_use
tool: scrapeless_scrape_markdown
status: completed
output: Response: "# Example Domain\n\nThis domain is for use in documentation ...

A resposta do modelo foi # Example Domain. O nome da ferramenta segue o padrão <server>_<tool> do OpenCode, então uma entrada chamada scrapeless coloca o mesmo prefixo em todas as 25 ferramentas.

Essa saída é a verificação que opencode mcp list não pode te dar. Um resultado que começa com o conteúdo da página significa que a chave funciona. Um resultado que começa com Failed to fetch data significa que a conexão está boa e a chave não está. A especificação das ferramentas MCP fornece um isError sinalizador para chamadas falhadas, mas o Scrapeless retorna ambos os resultados como texto de ferramenta comum sem isso, então o texto é o que deve ser lido.

Cada servidor conectado também adiciona suas definições de ferramentas ao contexto do modelo, e a resposta tools/list do Scrapeless para todas as 25 ferramentas é cerca de 30 KB. Definir "enabled": false na entrada mantém configurado, mas fora das sessões que não precisam da web.

Para o que o servidor expõe, o anúncio do servidor MCP Scrapeless cobre o lançamento, e nosso guia de integração MCP compara as maneiras como os agentes alcançam um navegador. A documentação do MCP para Navegadores traz a referência de configuração, a página da API de Scraping descreve os atores por trás das ferramentas, e a precificação lista o que uma chamada custa.

Conclusão

OpenCode precisa de quatro coisas da entrada: "type": "remote", a URL Scrapeless, um cabeçalho x-api-token escrito como {env:SCRAPELESS_API_KEY}, e "oauth": false. A sintaxe de substituição é o detalhe mais propenso a erro, porque a forma quebrada ainda se conecta.

opencode mcp list captura um cabeçalho ausente, uma variável não exportada e uma confusão de Bearer. Apenas um resultado de ferramenta captura uma chave ruim, então faça uma chamada e leia o que volta antes de construir qualquer coisa sobre a conexão.

Pronto para dar ao OpenCode uma visão ao vivo da web? Comece com o plano gratuito do Scrapeless e adicione o servidor.

FAQ

Q: Como eu adiciono um servidor MCP remoto com um cabeçalho de chave API ao OpenCode?

Adicione uma entrada sob mcp em opencode.json com "type": "remote", o servidor url, "oauth": false e um objeto headers. Para Scrapeless o cabeçalho é x-api-token, escrito como {env:SCRAPELESS_API_KEY} para que a chave fique fora do arquivo.

Q: Por que ${SCRAPELESS_API_KEY} não funciona em opencode.json?
A sintaxe de substituição do OpenCode é {env:SCRAPELESS_API_KEY}. A forma estilo shell é enviada como texto literal, então o servidor ainda lista como conectado e as chamadas de ferramenta retornam com failed with status 401.

Q: Por que a lista do opencode mcp diz que precisa de autenticação?

O servidor retornou um 401 enquanto oauth estava habilitado, então o OpenCode oferece um login. Para o Scrapeless, isso quase sempre significa um cabeçalho Authorization: Bearer; mude para x-api-token e defina "oauth": false.

Q: "Conectado" significa que minha chave Scrapeless é válida?

Não. O handshake do Scrapeless e a listagem de ferramentas têm sucesso com qualquer valor x-api-token não vazio. Apenas uma chamada de ferramenta revela uma chave inválida, como resultado que começa com Failed to fetch data.

Q: Quais são os nomes das ferramentas Scrapeless dentro do OpenCode?

O OpenCode nomeia as ferramentas MCP <server>_<tool>. Com a entrada chamada scrapeless, o modelo vê scrapeless_scrape_markdown e o mesmo prefixo nas outras 24 ferramentas.

Q: De onde o OpenCode lê o opencode.json?

A configuração global é ~/.config/opencode/opencode.json, e um projeto pode adicionar seu próprio opencode.json em sua raiz. A variável de ambiente OPENCODE_CONFIG aponta o OpenCode para um arquivo de configuração específico em vez disso.

Q: Preciso instalar um pacote para o servidor MCP do Scrapeless?

Não. O servidor está hospedado em https://api.scrapeless.com/mcp, e o OpenCode se conecta a ele via HTTP, então não há pacote, nenhum processo local e nenhuma versão para manter atualizada.