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

TL;DR:

• Adicionar Scrapeless ao Claude é uma entrada de configuração: um servidor HTTP MCP remoto em https://api.scrapeless.com/mcp com sua chave em um cabeçalho x-api-token.
• O handshake retorna scrapeless-mcp-server v0.2.0 no protocolo 2025-06-18, e tools/list retorna 25 ferramentas — scrape_markdown, o conjunto browser_*, crawl_*, google_search, google_trends e ai_scraper.
• O escopo decide se ele se conecta. A mesma entrada no escopo do usuário relatará ✔ Connected; em um projeto .mcp.json, ele relata ⏸ Pending approval e permanece desconectado até você aprová-lo interativamente.
• Scrapeless se autentica em x-api-token, não em Authorization: Bearer. Um cabeçalho Bearer falha no momento da conexão: Claude relata ✘ Failed to connect com HTTP 401.
• Passar a chave com --header a coloca no histórico do shell e na lista de processos; escrever o arquivo de configuração diretamente não o faz.
• Um status Connected apenas prova que o cabeçalho está presente — Scrapeless aceita qualquer valor de chave no handshake e ainda lista todas as 25 ferramentas. Prove a chave com uma chamada real de ferramenta que retorne conteúdo da página.
• Obtenha uma chave no plano gratuito do Scrapeless e conecte-se em cerca de um minuto.

Claude pode raciocinar sobre uma página da web em detalhes e não pode buscar uma. Um servidor MCP muda isso: o modelo obtém ferramentas que pode chamar no meio da conversa, então "ver o que esta página diz agora" deixa de ser um pedido que você responde colando.

Conectar Claude ao servidor MCP do Scrapeless via HTTP remoto leva uma entrada de configuração. As partes que merecem cuidado são os dois escopos que se comportam de maneira diferente e a diferença entre uma conexão que relata verde e uma que realmente funciona.

O Que Você Recebe Assim Que Está Conectado

O servidor expõe 25 ferramentas, enumeradas ao vivo em vez de copiadas de um documento:

Dois grupos são importantes para trabalhos diferentes. scrape_markdown responde "o que esta página diz" em uma única chamada. O conjunto browser_* é uma sessão que você controla passo a passo, para qualquer coisa por trás de um clique ou um formulário.

Cada uma dessas chamadas viaja como um pedido JSON-RPC nos bastidores — MCP é um transporte e um esquema sobre a especificação JSON-RPC 2.0, que é o motivo pelo qual uma sequência initialize / tools/list / tools/call é tudo que há na superfície do protocolo.

Pré-requisitos

• Claude Code instalado, ou outro cliente MCP que suporte servidores HTTP remotos.
• Uma chave API Scrapeless do painel de controle.
• Nada para instalar para o próprio servidor. Ele é hospedado, então não há pacote, nenhum tempo de execução e nenhum processo local.

Esse último ponto é a diferença entre os dois transports. Um servidor stdio é um comando local que o cliente inicia, o que significa um pacote para instalar e manter atualizado. Um servidor HTTP remoto é uma URL, e a especificação do Modelo Context Protocol define ambos; o transporte HTTP transmitível é o que não precisa de processo local algum.

Passo 1: Adicione o Servidor

A referência MCP do Claude Code documenta o comando como uma linha:

claude mcp add --transport http scrapeless https://api.scrapeless.com/mcp \
  --header "x-api-token: YOUR_SCRAPELESS_API_KEY"

Isso funciona, e tem um custo que vale a pena saber: tudo após --header vai para o histórico do seu shell e é visível na lista de processos enquanto o comando é executado. Escrever o arquivo de configuração diretamente evita ambos.

Para o escopo do usuário, adicione a entrada em ~/.claude.json:

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

Observe o nome do cabeçalho. Scrapeless se autentica em x-api-token, e a maioria dos guias de configuração de MCP mostra Authorization: Bearer porque é isso que o framework de autenticação HTTP define para credenciais bearer. Copiar essa forma aqui falha antes que o handshake seja concluído: claude mcp list relata ✘ Failed to connect — Server rejected the configured Authorization header (HTTP 401), com o detalhe Unauthorized: Missing x-api-token header.

Passo 2: Entenda Qual Escopo Você Usou

Claude lê a configuração do MCP de mais de um lugar, e os dois se comportam de maneira diferente de uma forma que produz uma execução inicial confusa.

No escopo do usuário, o servidor está ativo imediatamente:

scrapeless:
  Scope: User config (available in all your projects)
  Status: ✔ Connected
  Type: http
  URL: https://api.scrapeless.com/mcp

A entrada idêntica em um projeto .mcp.json não se conecta:

scrapeless:
  Scope: Project config (shared via .mcp.json)
  Status: ⏸ Pending approval (run `claude` to approve)
  Type: http
  URL: https://api.scrapeless.com/mcp

Um arquivo com escopo de projeto é compartilhado com todos que fazem checkout do repositório, então ele é bloqueado por trás de uma aprovação interativa antes que o cliente possa interagir com ele. Esse é o padrão correto — um arquivo de configuração em um repositório pode, de outra forma, direcionar seu cliente para qualquer coisa — mas isso significa que a entrada do projeto parece quebrada até que alguém abra uma sessão e a aprove.

Use o escopo de usuário para uma chave que é sua. Use o escopo de projeto quando toda a equipe deve obter o servidor e espera-se que cada pessoa a aprove uma vez.

Etapa 3: Confirme que Funciona de Fato

✔ Connected significa que o handshake foi bem-sucedido. Não significa que uma chamada será.

A listagem de ferramentas é respondida pelo próprio servidor MCP e nunca chega à API upstream, então um servidor pode anunciar um conjunto completo e saudável de ferramentas enquanto cada chamada real falha em uma credencial. Isso não é hipotético: um gateway que atendia este mesmo endpoint com um token armazenado desatualizado listou seu conjunto completo de ferramentas e retornou um erro de token inválido na primeira chamada real, enquanto o mesmo endpoint com uma boa chave retornou HTTP 200.

Portanto, verifique com uma chamada, não com um distintivo. Dentro de uma sessão Claude, /mcp lista os servidores conectados e suas ferramentas; solicitar uma página exercita o caminho de ponta a ponta:

Use scrapeless to fetch https://books.toscrape.com/catalogue/category/books/mystery_3/index.html
as markdown and list the first five book titles with their prices.

A chamada subjacente e seu resultado, capturados diretamente contra o endpoint:

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 no resultado é a confirmação que vale a pena ter. Com uma chave errada, a mesma chamada ainda retorna HTTP 200 e nenhum isError sinal; o texto do resultado começa com Failed to fetch data em vez disso.

O Que Retorna

scrape_markdown retorna a página como Markdown no bloco de conteúdo, que é a forma que um modelo pode realmente usar:

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

Markdown em vez de HTML é intencional. Através das ferramentas MCP, a mesma página tem 8.940 caracteres de scrape_markdown contra 53.800 de scrape_html, então solicitar HTML consome aproximadamente seis vezes o contexto em marcação que o modelo não precisa. Acesse scrape_html quando você for fazer a análise você mesmo, e scrape_markdown quando o modelo for o consumidor.

Está trabalhando agora em uma configuração de conector? O plano gratuito do Scrapeless inclui chamadas suficientes para concluir o handshake e os primeiros poucos chamadas de ferramentas.

Um Roteador na Frente Muda o Que Claude Vê

Se seu cliente aponta para um gateway que roteia vários servidores MCP atrás de uma URL em vez de ir diretamente para o endpoint, a lista de ferramentas muda de forma. Apontado para um gateway de roteamento inteligente, o mesmo cliente descobriu 3 ferramentas — as meta-ferramentas de busca e despacho do próprio roteador. Apontado para https://api.scrapeless.com/mcp, ele descobriu todas 25.

Nenhum deles está errado. Um roteador mantém uma credencial e uma trilha de auditoria através de muitos provedores, ao custo de o modelo ver os nomes das ferramentas a uma indirection. Conectar-se diretamente dá ao modelo a superfície real da ferramenta. Escolha por configuração e verifique a contagem descoberta para saber qual você obteve.

Induzindo-o Corretamente

Dois hábitos fazem a diferença entre um servidor conectado e um útil.

Nomeie a ferramenta quando o trabalho for inequívoco. "Use scrape_markdown nesta URL" pula uma rodada do modelo decidindo como buscar. Para trabalho em várias etapas — fazer login, filtrar, ler o resultado — descreva a sequência em vez disso, porque as ferramentas browser_* compartilham uma sessão e a ordem importa.

Peça pela forma que você quer de volta. Um modelo fornecido com 8.940 caracteres de Markdown fará um resumo, a menos que você diga para retornar uma tabela de títulos e preços. A ferramenta retorna um documento; a saída útil é o que quer que você pediu ao modelo para fazer.

Para uma visão mais ampla do MCP, nosso guia de integração MCP cobre o protocolo e a paisagem do cliente, e a página Scraping API descreve a família de atores que essas ferramentas atendem. A documentação traz a referência por ator, e preços lista o custo de uma chamada.

Conclusão

Todo o conector é uma URL, um nome de cabeçalho e uma decisão de escopo. https://api.scrapeless.com/mcp com x-api-token no escopo de usuário relata ✔ Connected e entrega ao Claude 25 ferramentas; a mesma entrada em um arquivo de projeto aguarda uma aprovação que é fácil de confundir com uma configuração quebrada.
Duas coisas valem a pena levar além da configuração. O cabeçalho é x-api-token, não Bearer — a forma Bearer é rejeitada com um 401 no momento da conexão, então claude mcp list mostra isso falhando imediatamente. E um status verde é um handshake: um tools/call que retorna conteúdo real da página é a única evidência de que a credencial por trás dele é boa.

Pronto para dar ao Claude uma chamada que ele possa fazer? Comece com o plano gratuito Scrapeless e adicione o servidor.

FAQ

Q: Como faço para adicionar o servidor Scrapeless MCP ao Claude?

Adicione uma entrada remota HTTP apontando para https://api.scrapeless.com/mcp com sua chave em um cabeçalho x-api-token. Ou execute claude mcp add --transport http scrapeless https://api.scrapeless.com/mcp --header "x-api-token: ...", ou escreva o mesmo objeto type/url/headers no seu arquivo de configuração — o que mantém a chave fora do histórico do shell.

Q: Por que meu servidor MCP aparece como pendente de aprovação?

Porque está definido em um projeto .mcp.json em vez de na configuração do seu usuário. Um arquivo de projeto viaja com o repositório, então o cliente exige uma aprovação interativa antes de se conectar a ele. A mesma entrada em escopo de usuário se conecta imediatamente. Abra uma sessão e aprove, ou mova a entrada para o escopo do usuário se a chave for apenas sua.

Q: Devo usar Authorization: Bearer ou x-api-token?

x-api-token. Scrapeless lê esse cabeçalho especificamente — uma solicitação sem ele retorna 401 Unauthorized: Missing x-api-token header. Uma entrada apenas Bearer é rejeitada da mesma maneira no momento da conexão, então Claude mostra ✘ Failed to connect em vez de ✔ Connected.

Q: Como sei se a conexão realmente está funcionando?

Faça uma chamada de ferramenta. A saída de status informa que o handshake foi bem-sucedido, e as listas de ferramentas são servidas pelo servidor MCP sem contatar a API upstream, então ambas podem parecer saudáveis diante de uma credencial rejeitada. Um tools/call que retorna conteúdo real da página é a prova; uma chave errada produz um resultado começando com Failed to fetch data, ainda sem uma flag isError.

Q: Qual é a diferença entre os transportes stdio e HTTP aqui?

Um servidor stdio é um processo local que o cliente inicia, então precisa de um pacote instalado e mantido atualizado. O servidor MCP Scrapeless é hospedado, então o transporte HTTP precisa apenas de uma URL e um cabeçalho — sem instalação, sem tempo de execução local e sem versão para rastrear na sua máquina.

Q: Quantas ferramentas devo esperar ver?

25 do endpoint diretamente. Se você vê 3, seu cliente está apontado para um gateway de roteamento em vez do endpoint, e essas três são as próprias ferramentas de despacho do roteador. Se você vê uma lista nomeando Mapas, Trabalhos, Hotéis ou Voos, esse é um conjunto de ferramentas mais antigo — verifique a contagem contra um fresh tools/list.

Q: Isso funciona no Claude Desktop assim como no Claude Code?

Ambos suportam MCP, mas eles leem arquivos de configuração diferentes, e a configuração do Desktop é comumente mostrada com um comando stdio local em vez de uma URL. A entrada HTTP remota acima é a forma do Claude Code; para o walkthrough do Desktop, veja nosso post anterior sobre como executar o servidor Scrapeless MCP no Claude, e note que sua lista de ferramentas antecede as atuais 25.

Q: Posso limitar quais ferramentas o modelo pode chamar?

Sim — isso é uma preocupação de permissão do lado do cliente em vez de uma configuração do servidor. Claude Code expõe regras de permitir e negar para ferramentas, então uma configuração que só precisa de conteúdo da página pode permitir scrape_markdown e deixar as ferramentas da sessão do navegador indisponíveis. Resuma ao que o trabalho precisa.