Factory Droid + Scrapeless: Adicionar um Servidor MCP Remoto

TL;DR:

• droid mcp add conecta o Scrapeless em um comando. Use --type http, um cabeçalho x-api-token e --no-oauth; a entrada cai em ~/.factory/mcp.json.
• Escreva a chave como ${SCRAPELESS_API_KEY}, com chaves. O Droid expande essa forma e nomeia a variável quando ela não está definida, mas envia um $SCRAPELESS_API_KEY puro como texto literal.
• Um projeto .factory/mcp.json pode manter a referência com segurança. A chave permanece no ambiente de cada desenvolvedor, e o servidor lista como connected [project].
• droid mcp list separa quatro problemas diferentes. connected, needs authentication, failed: Failed to connect to MCP server e uma falha de variável não definida apontam cada um para uma correção diferente.
• connected prova que o cabeçalho chegou, não que a chave funciona. Uma chave inventada também se lista como conectada, então confirme com uma chamada de ferramenta.
• Uma chamada de ferramenta sem interface precisa de --auto high, então limite seu escopo. droid exec --auto high --only-tools 'MCP:scrapeless/scrape_markdown' permite a chamada de execução usar apenas essa ferramenta e nada mais.
• Obtenha uma chave no plano gratuito do Scrapeless e adicione o servidor em alguns minutos.

O Factory Droid planeja e edita o código do seu terminal, e droid exec executa o mesmo agente sem interface em scripts e CI. Nenhum modo consegue olhar uma página da web por si só. Um servidor MCP fornece ferramentas que o Droid chama durante uma tarefa, e o servidor MCP Scrapeless hospedado oferece busca de páginas, um navegador em nuvem e pesquisa.

A configuração é um comando. O que decide se ele se mantém é como a chave chega ao cabeçalho, em qual arquivo de configuração a entrada vive e o que droid mcp list está realmente relatando.

O Que o Droid Pode Chamar Depois Que o Scrapeless É Adicionado

O servidor Scrapeless expõe 25 ferramentas. scrape_markdown, scrape_html e scrape_screenshot retornam uma página em uma chamada. Dezesseis ferramentas browser_*, de browser_create a browser_close, executam uma sessão de navegador em nuvem passo a passo. crawl_start, crawl_result e crawl_cancel gerenciam um rastreamento. google_search e google_trends retornam dados de pesquisa e tendências, e ai_scraper captura respostas de assistentes de IA como ChatGPT e Perplexity.

A arquitetura MCP separa o cliente que chama ferramentas do servidor que as fornece, razão pela qual o Droid precisa apenas de uma URL e um cabeçalho para usar um servidor hospedado em outro lugar.

Pré-requisitos

• Factory Droid CLI. Este guia usou as versões 0.213.0 e 0.220.0.
• Uma conta Factory com login, ou FACTORY_API_KEY definida, para o passo em que o modelo executa um prompt.
• Uma chave da API Scrapeless do painel Scrapeless.

Passo 1: Adicione o Servidor

droid mcp add scrapeless https://api.scrapeless.com/mcp --type http --header "x-api-token: YOUR_SCRAPELESS_API_KEY" --no-oauth

--type http seleciona o transporte HTTP transmitível; o tipo padrão é stdio, que trataria a URL como um comando para lançar. --no-oauth desativa o fluxo OAuth que o Droid oferecerá para um servidor remoto autenticado por cabeçalho.

Added HTTP MCP server scrapeless with URL: https://api.scrapeless.com/mcp

A entrada escrita em ~/.factory/mcp.json:

{
  "mcpServers": {
    "scrapeless": {
      "url": "https://api.scrapeless.com/mcp",
      "headers": {
        "x-api-token": "YOUR_SCRAPELESS_API_KEY"
      },
      "oauth": false,
      "disabled": false,
      "type": "http"
    }
  }
}

"oauth": false é o que --no-oauth adicionou. "disabled": false mantém o servidor ativo.

Passo 2: Coloque Uma Referência de Variável no Cabeçalho

O comando acima deixa uma chave literal no arquivo. Substitua-a por ${SCRAPELESS_API_KEY} para que o arquivo mantenha um nome e seu shell mantenha o valor. As chaves importam: o Droid expande a forma entre chaves de expansão de parâmetro POSIX e passa um $SCRAPELESS_API_KEY puro sem mudanças.

{
  "mcpServers": {
    "scrapeless": {
      "url": "https://api.scrapeless.com/mcp",
      "headers": {
        "x-api-token": "${SCRAPELESS_API_KEY}"
      },
      "oauth": false,
      "disabled": false,
      "type": "http"
    }
  }
}

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

Configured MCP servers:
  scrapeless  http  connected  [user]

Quando a variável não está definida nesse shell, o Droid a nomeia ao invés de falhar vagamente:

  scrapeless  http  failed: MCP server credential references an unset environment variable "SCRAPELESS_API_KEY"  [user]

Deixe de fora as chaves e esse aviso nunca aparece. O Droid envia o texto literal $SCRAPELESS_API_KEY, o servidor ainda lista como connected, e o problema só surge na primeira chamada de ferramenta.

Passo 3: Compartilhe o Servidor Através de um Projeto mcp.json

O Droid também lê .factory/mcp.json de um projeto, de modo que o servidor pode viver no repositório para todos que o clonam. Uma chave literal nesse arquivo seria comitada junto com ele, e credenciais codificadas são uma fraqueza de software catalogada por essa razão. A referência entre chaves é segura para cometer porque cada desenvolvedor fornece uma chave de seu próprio ambiente. Salve o mesmo JSON como .factory/mcp.json na raiz do repositório:

  scrapeless  http  connected  [project]

O rótulo entre colchetes é o escopo do qual o Droid carregou a entrada, que é a maneira mais rápida de confirmar que o arquivo do projeto é o que está em efeito. Sem a variável, a entrada do projeto relata a mesma falha de variável não definida, rotulada [project].
Configurando isso agora? O plano gratuito do Scrapeless cobre a conexão e suas primeiras chamadas de ferramenta.

Passo 4: Leia o que os relatórios da lista droid mcp indicam

As linhas Bearer aparecem com mais frequência porque quase todo exemplo de MCP autentica dessa maneira. O Scrapeless responde a uma solicitação sem x-api-token com uma resposta 401 Não Autorizado, e com OAuth ativado, o Droid interpreta isso como uma solicitação de login:

  scrapeless  http  needs authentication  [user]
Some servers need authentication. Start droid and run /mcp to authenticate.

Executar /mcp não resolve, pois o endpoint do Scrapeless não possui fluxo OAuth para completar. Mude o cabeçalho em vez disso.

O status que pode ser enganoso é connected. O handshake do Scrapeless aceita qualquer valor x-api-token não vazio, então uma chave digitada incorretamente ou revogada é listada exatamente como uma boa.

Passo 5: Execute o Droid Apenas Com Ferramentas Scrapeless

droid exec executa um prompt em modo headless, e ele começa em modo somente leitura. Uma chamada a uma ferramenta MCP vai além desse modo: no Droid 0.220.0 a execução para com "permissão insuficiente para prosseguir", e --auto medium ainda responde "Re-execute com --auto high". O flag --only-tools aceita seletores MCP, então emparelhe o nível de autonomia mais alto com um seletor que permite uma ferramenta:

droid exec --auto high --only-tools 'MCP:scrapeless/scrape_markdown' "Use the scrapeless MCP server's scrape_markdown tool on https://example.com and reply with the first heading of the page, quoted exactly."

O Droid responde:

The first heading of the page is:

"Example Domain"

Adicionar --list-tools ao mesmo seletor mostra o que aquela execução pode alcançar. O Droid nomeia ferramentas MCP <server>___<tool>, e scrapeless___scrape_markdown é a única marcada como permitida, enquanto as outras 24 ferramentas do Scrapeless e as ferramentas embutidas de arquivo e shell do Droid estão marcadas como bloqueadas. 'MCP:scrapeless' permite todas as 25 ferramentas do Scrapeless em vez disso, e --add-tools e --remove-tools aceitam os mesmos seletores.

O conteúdo da página no resultado é a confirmação. Com uma chave ruim, a mesma chamada ainda retorna HTTP 200, e o texto do resultado começa com Failed to fetch data; o Scrapeless não marca isso como um erro de MCP, então leia o texto em vez do status.

Para mais sobre o servidor em si, o anúncio do servidor Scrapeless MCP cobre o que ele expõe e nosso guia de integração MCP compara como os agentes alcançam um navegador. A documentação do MCP do Navegador possui a referência de configuração, a API de Scraping descreve os atores por trás das ferramentas, e preços lista o custo de uma chamada.

Conclusão

Adicionar o Scrapeless ao Droid é um comando. Manter a configuração confiável depende do que droid mcp list pode e não pode ver: a referência entre chaves ${SCRAPELESS_API_KEY} permite que o Droid nomeie uma variável ausente, --no-oauth transforma um erro de cabeçalho em uma falha em vez de um prompt de login, e apenas uma chamada de ferramenta, não um status connected, prova que a chave funciona.

Coloque a referência entre chaves em um projeto .factory/mcp.json e toda a equipe obtém o servidor sem que ninguém comprometa uma chave.

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

Perguntas Frequentes

P: Como adiciono um servidor MCP remoto com uma chave de API ao Factory Droid?

Execute droid mcp add scrapeless https://api.scrapeless.com/mcp --type http --header "x-api-token: YOUR_SCRAPELESS_API_KEY" --no-oauth. A entrada vai para ~/.factory/mcp.json, onde você pode substituir a chave literal por ${SCRAPELESS_API_KEY}.

P: O Droid expande variáveis de ambiente em cabeçalhos MCP?

Sim, na forma entre chaves. ${SCRAPELESS_API_KEY} é substituído pelo valor da variável, e uma variável não definida produz um status de falha que a nomeia. Uma $SCRAPELESS_API_KEY nua é enviada como texto literal.
P: Por que a lista do droid mcp diz que precisa de autenticação?

O servidor retornou um 401 enquanto o OAuth estava habilitado, então o Droid oferece um login. Para Scrapeless, isso quase sempre significa um cabeçalho Authorization: Bearer. Use x-api-token e adicione --no-oauth; executar /mcp não pode corrigir uma incompatibilidade de cabeçalho.

P: Qual é a diferença entre ~/.factory/mcp.json e .factory/mcp.json?

~/.factory/mcp.json é sua configuração de usuário e se aplica a todos os projetos. .factory/mcp.json em um repositório se aplica a esse projeto, aparece como [project] em droid mcp list e pode ser enviado para o controle de versão contanto que a chave seja uma referência ${SCRAPELESS_API_KEY}.

P: Estar conectado significa que minha chave Scrapeless é válida?

Não. O handshake do Scrapeless aceita qualquer valor x-api-token não vazio, então uma chave errada também é listada como connected. Uma chamada de ferramenta que retorna o conteúdo da página é a prova; uma chave ruim retorna texto começando com Failed to fetch data.

P: Como eu limito a execução de um droid exec às ferramentas Scrapeless?

Passe --only-tools 'MCP:scrapeless' para cada ferramenta Scrapeless, ou 'MCP:scrapeless/scrape_markdown' para uma, junto com --auto high, que uma chamada de ferramenta MCP precisa. --add-tools e --remove-tools aceitam os mesmos seletores.

P: Como eu removo o servidor Scrapeless do Droid?

Execute droid mcp remove scrapeless. O comando exclui a entrada do arquivo de configuração que a define.