Como Conectar Scrapeless ao Grok: Configuração do Conector MCP

TL;DR:

• O CLI do Grok fala MCP, então conectar o Scrapeless é uma tabela TOML: um cabeçalho url e um cabeçalho x-api-token.
• grok mcp doctor responde se funcionou — ✓ server started (1.0s), ✓ handshake OK (protocol 2025-06-18), ✓ 25 tools discovered.
• O escopo decide se o servidor será executado. Um .grok/config.toml local ao repositório em uma pasta não confiável reporta ✗ folder untrusted e conta como 0 servidores; a mesma tabela em escopo de usuário inicia.
• O cabeçalho é x-api-token, não Authorization: Bearer. Um cabeçalho Bearer falha na handshake: grok mcp doctor reporta ✗ handshake failed com HTTP 401.
• grok mcp add --header "..." escreve a configuração correta e coloca sua chave no histórico do shell; escrever a tabela você mesmo não faz isso.
• 25 tools discovered prova que o cabeçalho chegou, não que a chave é válida — o Scrapeless lista todas as 25 ferramentas para qualquer valor de chave. Uma tools/call real que retorna o conteúdo da página é a única prova de que a credencial funciona.
• Obtenha uma chave no plano gratuito do Scrapeless primeiro.

Um agente em um terminal é bom em ler arquivos e executar comandos, e cegos a qualquer coisa na web aberta. MCP é como essa lacuna se fecha: o cliente cria definições de ferramentas a partir de um servidor, o modelo escolhe uma no meio do caminho, e "o que esta página diz agora" se torna uma chamada em vez de um copiar-colar.

O CLI do Grok possui uma implementação MCP de primeira classe, incluindo um subcomando de diagnóstico que reporta qual etapa da conexão falhou em vez de um único vermelho ou verde. Configurar o conector envolve duas tabelas TOML; ler esse diagnóstico é a parte que economiza tempo mais tarde.

O Que Você Recebe

Vinte e cinco ferramentas, enumeradas a partir de um tools/list ao vivo em vez de copiadas da documentação:

scrape_markdown cobre a maior parte do que um agente pede — uma chamada, um documento. O grupo browser_* é uma sessão que o modelo conduz em várias etapas, que é o que qualquer coisa atrás de um clique ou login precisa.

Pré-requisitos

• O CLI do Grok. A versão usada aqui é grok 0.2.118 (1e1687c1cf).
• Uma chave de API do Scrapeless.
• Nada para instalar para o servidor. Ele é hospedado, então não há pacote e nenhum processo local — o cliente se conecta a uma URL via HTTP transmissível, um dos dois transportes que a especificação do Protocolo de Contexto do Modelo define.

Passo 1: Adicione o Servidor

O CLI tem um subcomando para isso:

grok mcp add -t http -s user scrapeless https://api.scrapeless.com/mcp \
  --header "x-api-token: YOUR_SCRAPELESS_API_KEY"

Added HTTP MCP server 'scrapeless' with URL: https://api.scrapeless.com/mcp to user config
File modified: ~/.grok/config.toml

-t http seleciona o transporte (as alternativas são stdio e o sse obsoleto), e -s user escreve para ~/.grok/config.toml em vez do repositório.

O que ele escreve é um par de tabelas TOML:

[mcp_servers.scrapeless]
url = "https://api.scrapeless.com/mcp"
enabled = true

[mcp_servers.scrapeless.headers]
x-api-token = "YOUR_SCRAPELESS_API_KEY"

Saber que a estrutura importa, porque a flag --header coloca sua chave no histórico do shell e na lista de processos enquanto o comando é executado. Escrever essas seis linhas você mesmo evita ambos, e permite adicionar os timeouts que o CLI não define:

[mcp_servers.scrapeless]
url = "https://api.scrapeless.com/mcp"
startup_timeout_sec = 30
tool_timeout_sec = 120

[mcp_servers.scrapeless.headers]
x-api-token = "YOUR_SCRAPELESS_API_KEY"

O nome do cabeçalho é o detalhe a ser acertado. O Scrapeless lê x-api-token; a maioria dos exemplos de MCP mostra Authorization: Bearer porque é o que o framework de autenticação HTTP especifica para credenciais bearer. Um cabeçalho Bearer aqui falha antes que a handshake seja completada — a requisição initialize retorna HTTP 401 Unauthorized: Missing x-api-token header, e o doutor conta o servidor como falhando.

Passo 2: Leia o Diagnóstico

Esta é a parte que vale a pena aprender. grok mcp doctor reporta cada etapa separadamente:

MCP Doctor

  Config sources
    ~/.grok/config.toml                      1 server
    ~/.claude.json                           not found
    .mcp.json                                not found
    grok.com                                 skipped (not logged in)

  scrapeless (http: https://api.scrapeless.com/mcp)
    ✓ server started (1.0s)
    ✓ handshake OK (protocol 2025-06-18)
    ✓ 25 tools discovered

Quatro fatos independentes nessa saída. Quais arquivos de configuração foram lidos e quantos servidores cada um contribuiu. Se a conexão foi aberta, e quanto tempo levou. Se a handshake do MCP foi completada, e em qual versão do protocolo. E quantas ferramentas retornaram da descoberta.

As duas últimas são intercâmbios ordinários de JSON-RPC 2.0 — uma requisição initialize seguida de uma tools/list — que é por isso que podem ter sucesso ou falhar independentemente uma da outra.
Uma falha em qualquer um desses pontos leva a uma causa diferente, razão pela qual a saída em estágios supera um único vermelho ou verde. Também há um modo --json quando você quer afirmar isso em um script em vez de lê-lo.

grok mcp list é a verificação mais rápida uma vez que esteja funcionando:

  scrapeless: https://api.scrapeless.com/mcp

Etapa 3: Entenda o Escopo, Ou Não Vai Começar

Grok lê a configuração MCP do escopo do usuário e de um .grok/config.toml local no repositório. O segundo tem uma condição anexada que produz uma execução inicial confusa.

A mesma tabela de servidores, colocada em uma pasta de projeto:

  Config sources
    ~/.grok/config.toml                      not found
    /root/verify-grok-proj/.grok/config.toml 0 servers

  scrapeless (http: https://api.scrapeless.com/mcp)
    ✗ folder untrusted (repo-local (project-scoped) server not started for an untrusted folder)

Duas coisas a notar. O servidor não iniciou — um servidor MCP com escopo de projeto não é lançado até que a pasta seja confiável, porque um arquivo de configuração em um repositório retirado pode, de outra forma, apontar seu agente para qualquer endpoint que o autor escolheu. E a linha de fonte de configuração lê 0 servidores mesmo que o arquivo defina um, então contar fontes não é suficiente para dizer que a configuração foi aceita.

Use o escopo do usuário para uma chave que seja sua. Use o escopo do projeto para compartilhar um servidor com uma equipe e espere o passo de confiança da pasta por máquina.

Etapa 4: Confirme a Capacidade, Não o Insígnia

25 tools discovered é o resultado de um tools/list, e essa chamada é respondida pelo próprio servidor MCP — nunca chega à API upstream. Portanto, a descoberta tem sucesso, independentemente de a credencial por trás dela ser boa ou não.

Essa não é uma distinção teórica. Um gateway de roteamento na frente deste mesmo endpoint com um token armazenado desatualizado descobriu seu conjunto completo de ferramentas e, em seguida, retornou um erro de token inválido na primeira chamada real, enquanto o mesmo endpoint com uma chave funcional retornou HTTP 200.

A verificação que resolve isso é uma chamada de ferramenta:

initialize   HTTP 200   server=scrapeless-mcp-server v0.2.0
tools/list   HTTP 200   25 tools
tools/call scrape_markdown  HTTP 200  8940 chars of page content

O conteúdo da página nesse resultado é a evidência. Tudo antes disso é um relatório de configuração sobre si mesmo: com uma chave errada, a chamada ainda retorna HTTP 200, sem uma isError flag, e seu texto começa com Failed to fetch data.

Nota: impulsionar essa chamada de dentro de uma transformação Grok exige autenticação xAI, a qual o ambiente deste guia não tinha — grok -p "..." retorna Not signed in. O conector, o handshake, a descoberta e a chamada de ferramenta acima são todos verificados; a transformação final autorada pelo modelo é o único passo tomado em confiança aqui. Faça login com grok login ou configure XAI_API_KEY e as mesmas ferramentas estão disponíveis para o modelo.

Etapa 5: Solicite-a

Uma vez que as ferramentas são descobertas, o modelo escolhe entre elas. Nomear a ferramenta remove uma rodada de adivinhação:

Use the scrapeless scrape_markdown tool on
https://books.toscrape.com/catalogue/category/books/mystery_3/index.html
and give me the first five titles with their prices as a table.

Duas práticas ajudam. Nomeie a ferramenta quando o trabalho for uma busca, e descreva a sequência quando não for — as ferramentas browser_* compartilham uma sessão, então "crie uma sessão, vá para a URL, clique no filtro e, em seguida, leia o texto" é uma instrução diferente de quatro não relacionadas.

E peça pela forma de saída que você deseja. scrape_markdown retorna um documento; se você obtém uma tabela ou um parágrafo é decidido pela solicitação, não pela ferramenta.

Configurando isso agora? O plano gratuito Scrapeless cobre chamadas suficientes para passar pelo handshake e as primeiras chamadas de ferramenta.

O Que Retorna

scrape_markdown retorna a página como Markdown no bloco de conteúdo:

Response:  "-   [Home](https://books.toscrape.com/index.html)
-   [Books](https://books.toscrape.com/catalogue/category/books_1/index.html)
...

Markdown em vez de HTML é o padrão certo para um modelo. A mesma página tem 8.940 caracteres de scrape_markdown contra 53.800 de scrape_html, então scrape_html gasta aproximadamente seis vezes o contexto em marcação que ninguém lê. Use scrape_html quando seu próprio código analisar o resultado, e scrape_markdown quando o modelo for o consumidor.

Um Roteador Muda a Contagem de Ferramentas

Se o cliente apontar para um gateway que está na frente de vários servidores MCP atrás de uma URL, a lista descoberta são as próprias ferramentas de despacho do roteador em vez das do provedor. O mesmo cliente, o mesmo comando: 3 ferramentas através de um gateway de roteamento inteligente, 25 contra https://api.scrapeless.com/mcp diretamente.

Ambos os arranjos são legítimos. Um roteador mantém uma credencial e uma trilha de auditoria através de muitos provedores; uma conexão direta dá ao modelo a superfície real de ferramentas. A contagem de ferramentas de grok mcp doctor lhe diz qual você está executando, o que é motivo suficiente para lê-la após qualquer alteração de configuração.
Para o mesmo produto dirigido por código em vez de um agente, nosso guia de web scraping Grok cobre o padrão modelo-plus-fetch, e o post de lançamento do servidor MCP cobre o que o servidor expõe. A página da API de Scraping descreve a família de atores por trás dessas ferramentas, a documentação contém a referência por ator e preços lista o custo de uma chamada.

Conclusão

Duas tabelas TOML e um nome de cabeçalho compõem todo o conector. grok mcp doctor então lhe diz qual dos quatro estágios funcionou, e sua linha 25 tools discovered é a que você deve verificar após qualquer alteração — porque 3 significa que você está falando com um roteador e 0 servidores de um arquivo que tem um significa que a pasta não é confiável.

Os dois erros que vale a pena evitar são ambos baratos. Use x-api-token em vez de um cabeçalho Bearer, já que a versão Bearer é rejeitada com um 401 durante o handshake e grok mcp doctor a sinaliza imediatamente. E trate a descoberta como um relatório de configuração sobre si mesma: um tools/call retornando conteúdo de página real é o que realmente prova que a credencial funciona.

Pronto para dar ao Grok um fetch que ele possa chamar? Comece com o plano gratuito do Scrapeless e adicione o servidor.

FAQ

P: O Grok suporta servidores MCP?

Sim. O CLI possui um subcomando grok mcp dedicado com add, list, remove, enable, disable e doctor, e suporta os transportes stdio, http e sse. HTTP remoto é o que deve ser usado para um servidor hospedado como este, pois não precisa de um processo local.

P: Como eu adiciono o servidor MCP do Scrapeless ao Grok?

grok mcp add -t http -s user scrapeless https://api.scrapeless.com/mcp --header "x-api-token: ...", ou escreva as tabelas equivalentes [mcp_servers.scrapeless] e [mcp_servers.scrapeless.headers] em ~/.grok/config.toml você mesmo. A rota escrita à mão mantém a chave fora do histórico do shell e permite que você defina startup_timeout_sec e tool_timeout_sec.

P: Por que meu servidor MCP com escopo de projeto não está iniciando?

Porque a pasta não é confiável. Um .grok/config.toml local do repositório não é iniciado até que você confie na pasta, e o diagnóstico afirma isso explicitamente: ✗ folder untrusted (repo-local (project-scoped) server not started for an untrusted folder). A linha de config-source também conta como 0 servidores, o que faz com que o arquivo pareça vazio quando não está. Mover a entrada para o escopo do usuário evita o bloqueio quando a chave é sua.

P: O cabeçalho deve ser x-api-token ou Authorization: Bearer?

x-api-token. Uma requisição sem ele retorna 401 Unauthorized: Missing x-api-token header. Um cabeçalho Bearer é rejeitado da mesma forma no handshake, então grok mcp doctor mostra ✗ handshake failed e Found 0 healthy, 1 failing — o médico capta o erro de uma palavra antes de qualquer chamada de ferramenta.

P: Como eu verifico quais ferramentas o Grok pode ver?

grok mcp doctor imprime a contagem descoberta por servidor, e --json fornece a mesma coisa de forma legível por máquina. Contra esse endpoint, ele relata 25. Se você ver 3, o cliente está apontado para um gateway de roteamento em vez do servidor, e essas três são as ferramentas de despacho do roteador.

P: 25 tools discovered é suficiente para saber que funciona?

Não. A descoberta é um tools/list, que o servidor MCP responde localmente sem contatar a API upstream, então tem sucesso mesmo contra uma credencial rejeitada. Faça uma chamada de ferramenta e procure conteúdo de página real; uma chave ruim retorna texto começando com Failed to fetch data, e o Scrapeless não define isError sobre isso.

P: Eu preciso estar conectado ao xAI para que o conector funcione?

O conector em si não precisa: o handshake e a descoberta de ferramentas funcionam sem qualquer credencial xAI. Fazer com que o modelo realmente chame uma ferramenta faz, porque essa é uma turn de inferência do Grok — sem isso, grok -p "..." retorna Not signed in. Execute grok login ou defina XAI_API_KEY.

P: Posso limitar quais ferramentas o modelo pode chamar?

Sim, do lado do cliente. O CLI expõe regras de permissão de permitir e negar, além de --tools e --disallowed-tools para embutidos, então uma configuração que só precisa de conteúdo de página pode permitir scrape_markdown e deixar as ferramentas de sessão de navegador indisponíveis. Restrições à tarefa.