Warp + Scrapeless: Conectar um Servidor MCP Remoto

TL;DR:

• Warp conecta-se ao Scrapeless como um servidor MCP remoto via HTTP transmitível. Um arquivo .warp/.mcp.json na raiz do seu projeto com um cabeçalho url e x-api-token é toda a configuração.
• Escreva ${SCRAPELESS_API_KEY}, incluindo as chaves. Warp expande essa forma quando lê o arquivo. $SCRAPELESS_API_KEY e {{SCRAPELESS_API_KEY}} chegam ao Scrapeless como texto literal, e o servidor ainda parece saudável em /mcp.
• Uma variável não definida derruba todo o arquivo. Cada servidor nele é substituído por Warp config error … Missing or empty environment variable: SCRAPELESS_API_KEY.
• Servidores de projeto começam manualmente. Abra /mcp, selecione scrapeless e pressione Enter; a linha se move de offline para running · 25 tools.
• running · 25 tools não prova a chave. Uma chave inventada alcança o mesmo status. Uma chamada de ferramenta, ou a verificação rápida na Etapa 5, separa uma chave válida de uma inválida.
• O nome do cabeçalho é x-api-token. Uma entrada Authorization: Bearer falha com "rejeitou as credenciais configuradas (HTTP 401)", mesmo quando o próprio token é válido.
• Obtenha uma chave no plano gratuito do Scrapeless e adicione o servidor em poucos minutos.

O Warp Agent executa comandos em um terminal real e lê seu código, mas não tem visão de como uma página da web é renderizada neste momento. Um servidor MCP fecha essa lacuna: ferramentas que o agente chama durante a tarefa, respondidas por um serviço que busca e renderiza a página para ele.

Este guia adiciona o servidor MCP hospedado do Scrapeless ao Warp Agent CLI, o binário warp. A configuração é algumas linhas de JSON. Se funciona ou não depende de três detalhes: qual arquivo o Warp lê, como a chave é referenciada dentro dele e o que a linha de status /mcp diz e não diz.

O que o Scrapeless Adiciona a uma Sessão do Warp Agent

O servidor expõe 25 ferramentas, agrupadas por trabalho:

• scrape_markdown, scrape_html e scrape_screenshot retornam uma página renderizada como Markdown, HTML bruto ou uma imagem em uma chamada.
• Dezesseis ferramentas browser_*, de browser_create e browser_goto a browser_click, browser_type e browser_snapshot, conduzem uma sessão de navegador em nuvem passo a passo.
• crawl_start, crawl_result e crawl_cancel executam uma coleta em segundo plano e a coletam depois.
• google_search e google_trends retornam resultados de pesquisa e dados de tendência, e ai_scraper captura respostas de assistentes de IA como ChatGPT, Gemini e Perplexity.

Nada roda na sua máquina para isso. O transporte HTTP transmitível do MCP é um único endpoint HTTPS que aceita JSON-RPC via POST, e o Warp fala isso nativamente. Seu log do MCP registra MCP: Using Streaming HTTP transport para este servidor sem nenhuma configuração de transporte no arquivo.

Onde o Warp Procura Definições de Servidores MCP

O Warp lê definições de servidores de arquivos de configuração, bem como de sua página de configurações. A documentação do MCP do Warp lista essas localizações:

Servidores de projeto de qualquer provedor nunca começam por conta própria. O Warp os detecta e espera que você inicie cada um, e a escolha dura apenas para a sessão, então após uma reinicialização você inicia-os novamente.

O CLI também mantém uma configuração separada do aplicativo Warp. A página de configuração do Warp Agent CLI fornece ~/.warp_cli/.mcp.json como aquele arquivo no macOS. No Linux, o Warp Agent CLI v0.2026.09.09.08.26.stable_02 não pegou um servidor de ~/.warp_cli/.mcp.json ou de ~/.warp/.mcp.json, enquanto descobriu os três arquivos de escopo de projeto e os rotulou como Warp (.warp/.mcp.json), Claude (.mcp.json) e Other Agents (.agents/.mcp.json). Este guia usa .warp/.mcp.json, o arquivo que o Warp nomeia como o seu.

Se você trabalhar no aplicativo de desktop Warp, o mesmo JSON mcpServers vai em Configurações > Agentes > Servidores MCP através do botão + Adicionar.

Pré-requisitos

• O Warp Agent CLI, com login em uma conta Warp. Este guia usa a versão v0.2026.09.09.08.26.stable_02, que warp --version imprime.
• Créditos de IA nessa conta Warp, para a etapa em que o agente chama uma ferramenta.
• Uma chave de API do Scrapeless do painel do Scrapeless.
• Uma pasta de projeto para manter o arquivo de configuração. Os testes aqui usaram um repositório Git.

Etapa 1: Adicione .warp/.mcp.json ao Seu Projeto

Crie .warp/.mcp.json na raiz do projeto:

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

Um servidor de URL leva duas propriedades no Warp: url, que é obrigatória, e headers, um objeto de chave-valor que é opcional em geral e obrigatório aqui, porque o Scrapeless autentica cada solicitação pelo cabeçalho x-api-token. Não há campo type para definir.

O arquivo contém uma referência de variável, não uma chave, portanto pode viver no controle de versão. Cada pessoa que abre o projeto exporta sua própria chave. Isso mantém a credencial fora do repositório, o que a orientação de gerenciamento de segredos do OWASP considera um lugar onde um segredo nunca deve estar.

Passo 2: Exporte a Chave Com o Placeholder Certo

Exporte a variável no shell que inicia o Warp, depois inicie o CLI a partir da pasta do projeto:

export SCRAPELESS_API_KEY="your-scrapeless-api-key"
cd path/to/your-project
warp

O Warp expande as referências ${VAR} ao ler um arquivo de configuração do disco. A forma importa, e uma forma errada falha silenciosamente. Cada variante abaixo foi enviada através de um proxy de log local para ver o que realmente chegou ao Scrapeless:

As segunda e terceira linhas são a armadilha. Elas parecem exatamente como uma configuração funcional até que a primeira chamada de ferramenta do agente retorne uma falha de autenticação.

O caso não exportado é barulhento, mas chega mais longe do que um único servidor. O Warp rejeita o arquivo inteiro e lista uma única linha de erro em vez de cada servidor definido nele:

Warp config error  /path/to/your-project/.warp/.mcp.json · Missing or empty environment variable: SCRAPELESS_API_KEY

Nos testes, um segundo servidor válido definido no mesmo arquivo desapareceu da lista também. Exporte a variável no seu perfil shell, ou em qualquer coisa que inicie suas sessões de terminal, para que cada processo warp herde-a.

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

Passo 3: Inicie o Servidor a Partir de /mcp

Digite /mcp na entrada do CLI para abrir a visualização de gerenciamento do MCP, depois digite scrapeless na caixa de pesquisa. A linha nomeia o rótulo do fornecedor, o projeto e o transporte:

scrapeless  Warp · scrapeless-demo · HTTP/SSE · offline

Pressione Enter na linha. Dentro de alguns segundos, o Warp executa o handshake do MCP, lista as ferramentas e atualiza a linha:

scrapeless  Warp · scrapeless-demo · HTTP/SSE · running · 25 tools

Entrar em uma linha em execução para o servidor interrompe-o. Como servidores com escopo de projeto são com escopo de sessão, repita este início cada vez que abrir o CLI nesse projeto.

Passo 4: Leia o Status Antes de Solicitar

Cada estado em /mcp aponta para uma solução diferente:

A linha failed merece uma análise mais atenta, porque seu aviso aponta para longe da causa. Com Authorization: Bearer ${SCRAPELESS_API_KEY} como o cabeçalho, o Warp registra:

[error] MCP: Failed to connect to server: Transport creation error: MCP server 'scrapeless' rejected the configured credentials (HTTP 401). The request included the credential header(s) you configured, so the server did not accept that value — check the token itself, its expiry, and its scope. The server did not ask for OAuth.

O token naquela solicitação era válido. O Scrapeless rejeitou a solicitação porque o nome do cabeçalho estava errado, e seu corpo de resposta diz isso: Unauthorized: Missing x-api-token header. Altere o nome do cabeçalho e mantenha a chave inalterada.

O Warp escreve um arquivo de log por início do servidor em ${XDG_STATE_HOME:-$HOME/.local/state}/warp-terminal/mcp no Linux. Cada arquivo se abre com um lembrete de que pode conter informações sensíveis, como chaves de API, então leia-o localmente e faça a remoção antes de compartilhá-lo.

Passo 5: Prove a Chave, Depois Solicite o Agente

Um servidor em execução com 25 ferramentas só mostra que um cabeçalho chegou. O Scrapeless responde initialize e tools/list para qualquer valor de chave, incluindo um inventado. A diferença aparece em tools/call: com uma chave ruim, a chamada ainda retorna HTTP 200, e o texto do resultado começa com Failed to fetch data.

Esta verificação executa o mesmo handshake que o Warp executa e, em seguida, chama scrape_markdown uma vez, usando nada além da biblioteca padrão do Python:

import json
import os
import urllib.request

URL = "https://api.scrapeless.com/mcp"
HEADERS = {
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream",
    "x-api-token": os.environ["SCRAPELESS_API_KEY"],
}


def post(payload, session_id=None):
    headers = dict(HEADERS)
    if session_id:
        headers["Mcp-Session-Id"] = session_id
    request = urllib.request.Request(URL, data=json.dumps(payload).encode(), headers=headers)
    with urllib.request.urlopen(request, timeout=120) as response:
        body = response.read().decode()
        session_id = response.headers.get("Mcp-Session-Id") or session_id
    events = [line[5:].strip() for line in body.splitlines() if line.startswith("data:")]
    return session_id, json.loads(events[-1]) if events else None


session, init = post({
    "jsonrpc": "2.0", "id": 1, "method": "initialize",
    "params": {"protocolVersion": "2025-06-18", "capabilities": {},
               "clientInfo": {"name": "key-check", "version": "1.0"}},
})
post({"jsonrpc": "2.0", "method": "notifications/initialized"}, session)
_, result = post({
    "jsonrpc": "2.0", "id": 2, "method": "tools/call",
    "params": {"name": "scrape_markdown", "arguments": {"url": "https://example.com"}},
}, session)

server = init["result"]["serverInfo"]
text = "".join(part.get("text", "") for part in result["result"]["content"])
print(server["name"], server["version"])
if text.startswith("Failed to fetch data"):
    print("key rejected:", text[:60])
else:
    print(f"key accepted: {len(text)} characters of Markdown")

Com uma chave válida exportada, imprime:

scrapeless-mcp-server 0.2.0
key accepted: 184 characters of Markdown

Uma vez que a chave é validada, nomeie o servidor e a ferramenta quando o trabalho for uma única busca:
Nota: a ação do agente precisa de créditos de IA na sua conta Warp, e não foi executada para este artigo porque a conta de teste não tinha mais; o Warp respondeu "Você está sem créditos de IA." O início do servidor, o handshake e a verificação da chave acima foram executados contra o mesmo endpoint com a mesma configuração.

Use the scrapeless MCP server's scrape_markdown tool to fetch
https://books.toscrape.com/catalogue/category/books/mystery_3/index.html
and list the first three book titles with their prices.

Naquela página de categoria scrape_markdown retorna 8.940 caracteres onde scrape_html retorna 53.800, então o Markdown custa ao agente cerca de um sexto do contexto para o mesmo conteúdo. Use scrape_html quando seu próprio código analisar o resultado e scrape_markdown quando o agente lê isso.

As chamadas da ferramenta MCP seguem seu perfil de execução ativo. mcp_permissions padrão é agent_decides, e os mcp_allowlist e mcp_denylist do perfil recebem IDs de servidor MCP que podem ser executados sem aprovação ou devem sempre pedir.

O anúncio do servidor MCP Scrapeless descreve o que o servidor expõe, a documentação do MCP do navegador contém a referência de configuração, a API de scraping cobre os atores por trás das ferramentas, e preços lista o custo de uma chamada.

Conclusão

O conector é uma entrada em .warp/.mcp.json com três condições: o cabeçalho é nomeado x-api-token, seu valor é ${SCRAPELESS_API_KEY} com as chaves, e a variável é exportada no shell que inicia warp. Depois disso, inicie o servidor de /mcp uma vez por sessão.

Dois resultados precisam de cuidado porque parecem bons. Uma forma de placeholder incorreta e uma chave errada mostram running · 25 tools, e apenas uma chamada de ferramenta as expõe. As falhas que aparecem leem de forma diferente: um cabeçalho Bearer produz failed … rejected the configured credentials e uma variável não exportada produz um erro de configuração que oculta todos os servidores no arquivo.

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

FAQ

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

Crie .warp/.mcp.json na raiz do projeto com uma entrada mcpServers que tenha um url e um objeto headers, por exemplo "x-api-token": "${SCRAPELESS_API_KEY}". Exporte a variável, inicie warp naquela pasta, e depois inicie o servidor de /mcp. No aplicativo desktop Warp, cole o mesmo JSON em Configurações > Agentes > Servidores MCP > + Adicionar.

Q: O Warp expande variáveis de ambiente nos cabeçalhos MCP?

Sim, na forma ${VAR}. Um valor de cabeçalho de ${SCRAPELESS_API_KEY} alcançou o servidor como a chave exportada. $SCRAPELESS_API_KEY sem chaves e {{SCRAPELESS_API_KEY}} foram enviados como texto literal.

Q: Por que meu servidor MCP Warp mostra em execução com uma chave de API errada?

running · 25 tools significa que o handshake e a listagem da ferramenta funcionaram, e Scrapeless responde ambos para qualquer valor de chave. Uma chave errada aparece apenas quando uma ferramenta é executada: a chamada retorna texto começando com Failed to fetch data.

Q: Por que o Warp diz que o servidor MCP rejeitou as credenciais configuradas?

Para Scrapeless, a causa usual é o nome do cabeçalho, não o token. Um cabeçalho Authorization: Bearer produz rejected the configured credentials (HTTP 401), porque o servidor procura x-api-token e responde Missing x-api-token header.

Q: O que significa "Erro de configuração do Warp ... Variável de ambiente ausente ou vazia"?

O arquivo faz referência a uma variável que não está definida no shell que iniciou warp. O Warp rejeita o arquivo inteiro, então todos os servidores definidos nele desaparecem de /mcp até que você exporte a variável e inicie o CLI novamente.

Q: Os servidores MCP com escopo de projeto iniciam automaticamente no Warp?

Não. O Warp detecta .warp/.mcp.json, .mcp.json e .agents/.mcp.json em um projeto, mas lista seus servidores como offline até que você inicie cada um a partir de /mcp, e essa escolha dura apenas para a sessão atual.

Q: Por que o CLI do Warp Agent não lista meu servidor de ~/.warp_cli/.mcp.json?

A documentação do CLI fornece esse caminho para macOS. No Linux, o Warp Agent CLI v0.2026.09.09.08.26.stable_02 não leu ~/.warp_cli/.mcp.json ou ~/.warp/.mcp.json, e /mcp respondeu No matching MCP servers. O arquivo do projeto .warp/.mcp.json foi descoberto.

Q: Quantas ferramentas o servidor MCP Scrapeless adiciona ao Warp?
25: três scrape_* ferramentas, dezesseis browser_* ferramentas, três crawl_* ferramentas, além de google_search, google_trends e ai_scraper.