CrewAI + Scrapeless: Dê ao Seu Agente Crew Dados da Web em Tempo Real

Uma equipe CrewAI é tão útil quanto as ferramentas que seus agentes podem acessar. Dê a um agente de pesquisa nada além de um modelo de linguagem e ele descreverá com confiança uma página que nunca abriu.

Conectar essa equipe ao Scrapeless MCP Server conserta o lado de entrada: os agentes obtêm controle de navegador, raspagem de página, pesquisa no Google e tendências do Google como ferramentas ordinárias do CrewAI, enquanto renderização, roteamento de proxy e anti-detecção ficam no servidor. Este guia executa a conexão de ponta a ponta e mostra a lista de ferramentas, os esquemas de argumentos e o markdown que uma chamada real retorna.

O Que Esta Configuração Oferece Sua Equipe

Seus agentes recebem 21 ferramentas chamáveis a partir de uma conexão. O Scrapeless MCP Server as expõe por meio de HTTP Streamable, e crewai-tools transforma cada uma em uma BaseTool padrão do CrewAI que qualquer agente pode utilizar.

As ferramentas se dividem em três grupos:

• Recuperação de página — scrape_markdown, scrape_html e scrape_screenshot obtêm uma URL e a retornam na forma que você solicitou.
• Controle de navegador ao vivo — dezesseis ferramentas browser_* que criam uma sessão e, em seguida, clicam, digitam, rolam, navegam, esperam e capturam instantâneas dentro dela.
• Superfícies de pesquisa — google_search e google_trends.

Como o trabalho é feito no lado do servidor, o processo da equipe permanece pequeno. Não há navegador local para instalar, nem pool de proxies para gerenciar, e nenhuma versão de driver a ser mantida alinhada com um lançamento do Chrome.

Por Que o Scrapeless MCP Server

A especificação do Protocolo de Contexto do Modelo define como um cliente descobre e invoca ferramentas em um servidor, o que torna uma conexão mais valiosa do que um invólucro escrito à mão: a lista de ferramentas, os esquemas de argumentos e o envelope de resultados chegam todos do servidor, em vez de serem codificados diretamente no seu projeto. As chamadas viajam como mensagens JSON-RPC 2.0, portanto, o formato de solicitação e resposta é um padrão publicado, em vez de uma convenção de fornecedor.

Scrapeless publica um endpoint hospedado, portanto, não há servidor a ser executado. O transporte é HTTP Streamable, o mecanismo HTTP do protocolo, e a autenticação se dá por meio de um único cabeçalho. Tudo que um agente CrewAI precisa é um dicionário. A mesma chave também apoia o Scrapeless Scraping Browser, que é o navegador em nuvem controlado pelas ferramentas browser_*, e a referência de parâmetros para cada ferramenta está na documentação do Scrapeless.

Pré-requisitos

• Python 3.10 ou posterior. Tanto crewai quanto crewai-tools atualmente exigem >=3.10,<3.14.
• Uma chave de API Scrapeless do painel de controle.
• Uma chave de provedor de modelo para o LLM que sua equipe utiliza. O CrewAI padrão é OpenAI e lê OPENAI_API_KEY.

Nota: Os exemplos abaixo foram executados com uma chave Scrapeless, mas sem uma chave de provedor de modelo. A conexão MCP, descoberta de ferramentas, esquemas de argumentos, invocação de ferramentas e ligação de agentes ocorreram ao vivo. A chamada final crew.kickoff() é uma lacuna nos pré-requisitos — ela precisa de uma chave de modelo, e o artigo marca essa etapa em vez de mostrar uma saída inventada.

Instalação

pip install "crewai==1.15.4" "crewai-tools[mcp]==1.15.4"

O extra [mcp] inclui a biblioteca cliente mcp e mcpadapt, que é a camada que converte definições de ferramentas MCP em ferramentas nativas do framework.

Se o seu ambiente já possui uma pilha OpenTelemetry, instale esses dois pacotes juntos, conforme mostrado, em vez de um por vez. crewai fixa opentelemetry-sdk~=1.42, e um conjunto de exportador parcialmente atualizado causa um erro de importação antes que qualquer um do seu código seja executado.

Defina a chave no seu shell:

export SCRAPELESS_API_KEY="sua_chave_api_aqui"

Conectar via HTTP Streamable

MCPServerAdapter recebe um dicionário descrevendo o servidor. A entrada headers carrega a chave de API Scrapeless:

import os
from crewai_tools import MCPServerAdapter

server_params = {
    "url": "https://api.scrapeless.com/mcp",
    "transport": "streamable-http",
    "headers": {"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
}

with MCPServerAdapter(server_params) as tools:
    names = sorted(t.name for t in tools)
    print(f"contagem de ferramentas: {len(names)}")
    for n in names:
        print("  -", n)

Executá-lo lista o que o servidor realmente oferece:

contagem de ferramentas: 21
  - browser_click
  - browser_close
  - browser_create
  - browser_get_html
  - browser_get_text
  - browser_go_back
  - browser_go_forward
  - browser_goto
  - browser_press_key
  - browser_screenshot
  - browser_scroll
  - browser_scroll_to
  - browser_snapshot
  - browser_type
  - browser_wait
  - browser_wait_for
  - google_search
  - google_trends
  - scrape_html
  - scrape_markdown
  - scrape_screenshot

Dois detalhes que merecem destaque. Os nomes são simples — não há prefixo de servidor ou namespace pontuado, então scrape_markdown é a string literal que um agente chamará. E o gerenciador de contexto é importante: ele abre a sessão na entrada e a fecha na saída, o que é a razão pela qual o adaptador é escrito como um bloco with em vez de um construtor simples.

Dê a um Agente Apenas as Ferramentas que Ele Precisa

Entregar todas as 21 ferramentas a cada agente dificulta o trabalho do modelo, ao invés de facilitá-lo. O MCPServerAdapter aceita nomes de ferramentas após o dicionário do servidor e retorna apenas aquelas:

import os
from crewai_tools import MCPServerAdapter

server_params = {
    "url": "https://api.scrapeless.com/mcp",
    "transport": "streamable-http",
    "headers": {"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
}

with MCPServerAdapter(server_params, "scrape_markdown", "google_search") as tools:
    print("ferramentas filtradas:", [t.name for t in tools])
    for t in tools:
        schema = getattr(t, "args_schema", None)
        fields = list(schema.model_fields) if schema else "n/a"
        print(f"  {t.name} args: {fields}")

ferramentas filtradas: ['scrape_markdown', 'google_search']
  scrape_markdown args: ['url']
  google_search args: ['q', 'hl', 'gl']

Os esquemas de argumento vêm do servidor, portanto são o contrato real: scrape_markdown recebe um único url, e google_search recebe uma consulta, além dos códigos de idioma e país. Um agente de pesquisa que precisa apenas ler páginas e fazer pesquisas recebe exatamente duas ferramentas e nenhuma superfície de sessão de navegador para abusar.

Pronto para integrar isso na sua própria equipe? Crie uma conta gratuita na Scrapeless e conecte-se com a chave do seu painel.

Anexe as Ferramentas a uma Equipe

As ferramentas vão diretamente no construtor do Agent, e o agente entra em uma Crew com sua tarefa:

import os
from crewai import Agent, Task, Crew
from crewai_tools import MCPServerAdapter

server_params = {
    "url": "https://api.scrapeless.com/mcp",
    "transport": "streamable-http",
    "headers": {"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
}

with MCPServerAdapter(server_params, "scrape_markdown", "google_search") as tools:
    analyst = Agent(
        role="Analista de Pesquisa na Web",
        goal="Transformar páginas públicas em markdown limpo para análise posterior.",
        backstory="Trabalha com fontes públicas da web e devolve notas estruturadas.",
        tools=tools,
        verbose=False,
    )
    print("ferramentas do agente:", [t.name for t in analyst.tools])

    task = Task(
        description="Buscar https://quotes.toscrape.com/js/ e resumir os autores presentes.",
        expected_output="Uma lista de nomes de autores encontrados na página.",
        agent=analyst,
    )
    crew = Crew(agents=[analyst], tasks=[task], verbose=False)
    print("agentes da equipe:", len(crew.agents), "| tarefas da equipe:", len(crew.tasks))

ferramentas do agente: ['scrape_markdown', 'google_search']
agentes da equipe: 1 | tarefas da equipe: 1

O agente está segurando tanto ferramentas fornecidas pelo servidor quanto a equipe está montada. Tudo até este ponto funciona apenas com a chave da Scrapeless.

Nota: crew.kickoff() é o único passo abaixo que precisa de uma chave de fornecedor de modelo. Sem a OPENAI_API_KEY definida, a CrewAI levanta ValueError: OPENAI_API_KEY is required antes da primeira chamada ao modelo, então a execução é mostrada como a linha que você adiciona em vez de como saída capturada.

    result = crew.kickoff()
    print(result)

O que uma Chamada de Ferramenta Retorna

Chamar uma ferramenta diretamente é a maneira mais rápida de ver a forma retornada sem gastar tokens do modelo. scrape_markdown recebe a URL e devolve markdown:

import os
from crewai_tools import MCPServerAdapter

server_params = {
    "url": "https://api.scrapeless.com/mcp",
    "transport": "streamable-http",
    "headers": {"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
}

with MCPServerAdapter(server_params, "scrape_markdown") as tools:
    tool = list(tools)[0]
    md = tool.run(url="https://quotes.toscrape.com/js/")
    text = md if isinstance(md, str) else str(md)
    print("caracteres markdown:", len(text))
    print("contém Einstein:", "Einstein" in text)
    print("primeiros 180:", text[:180].replace("\n", " "))

caracteres markdown: 1580
contém Einstein: True
primeiros 180: Resposta:  "# [Quotes to Scrape](https://quotes.toscrape.com/)\n\n[Login](https://quotes.toscrape.com/login)\n\n“O mundo como o criamos é um processo do nosso pensamento. Ele pode

A página alvo constrói sua lista de citações no navegador em vez de enviá-la no HTML inicial, e as citações estão presentes no markdown de qualquer maneira — o servidor renderizou a página antes de convertê-la. Essa é a diferença prática entre uma ferramenta MCP apoiada por uma infraestrutura real e uma simples requisição HTTP: o agente solicita uma página e recebe a página que um usuário veria.
O Markdown também é o formato que um modelo de linguagem manipula de forma mais econômica. Títulos, links e a estrutura de parágrafos sobrevivem, enquanto scripts, estilos e markup de layout não, assim o agente utiliza seu contexto em conteúdo.

Conclusão

Conectar o CrewAI ao Servidor MCP Scrapeless requer um dicionário e um gerenciador de contexto. O servidor fornece 21 ferramentas com seus próprios esquemas de argumentos, crewai-tools as converte em ferramentas nativas do CrewAI, e nomear ferramentas específicas no adaptador mantém a superfície de cada agente pequena o suficiente para que um modelo a utilize bem.

A parte que vale a pena incorporar ao seu próprio projeto é o filtro de ferramentas. Uma equipe onde o agente de pesquisa possui scrape_markdown e google_search, e um agente de navegação separado possui o conjunto browser_*, oferece a cada modelo um menu curto e uma tarefa clara.

Comece no plano gratuito do Scrapeless para obter uma chave, revise os preços do Scrapeless ao dimensionar uma carga de trabalho, e leia a visão geral do Servidor MCP Scrapeless para a referência completa das ferramentas.

FAQ

P: Qual é o endpoint do Servidor MCP Scrapeless para o CrewAI?

O endpoint hospedado é https://api.scrapeless.com/mcp, acessado através do transporte streamable-http com sua chave no cabeçalho x-api-token. O CrewAI não precisa de nenhum processo de servidor local, pois as ferramentas são servidas remotamente.

P: Quantas ferramentas o Servidor MCP Scrapeless expõe?

Uma conexão ativa retorna 21 ferramentas: dezesseis ferramentas de controle de sessão browser_*, três ferramentas de recuperação de página (scrape_markdown, scrape_html, scrape_screenshot), e duas ferramentas de pesquisa (google_search, google_trends). Verifique a lista em tempo de execução em vez de assumir, pois um servidor pode adicionar ferramentas entre lançamentos.

P: Posso limitar quais ferramentas MCP um agente recebe?

Sim. Passe nomes de ferramentas para MCPServerAdapter após o dicionário do servidor — MCPServerAdapter(server_params, "scrape_markdown", "google_search") retorna apenas essas duas. Isso mantém o menu de ferramentas do modelo curto, o que geralmente melhora a precisão da seleção.

P: O CrewAI precisa de uma chave LLM para se conectar a um servidor MCP?

Não. O handshake MCP, a descoberta de ferramentas e as chamadas diretas de ferramentas funcionam apenas com a chave do Scrapeless. Uma chave do provedor de modelo é necessária no momento em que você chama crew.kickoff(), pois é quando um agente pede a um modelo qual ferramenta usar.

P: Por que usar um gerenciador de contexto com MCPServerAdapter?

O bloco with abre a sessão MCP na entrada e a fecha na saída. Construir o adaptador sem um deixa a conexão aberta, e as ferramentas só são válidas enquanto a sessão existir — acessá-las após o fechamento da sessão gera um erro.

P: O scrape_markdown lida com páginas que renderizam no navegador?

Sim. Uma página que escreve seu conteúdo via JavaScript ainda retorna esse conteúdo no markdown, pois a renderização acontece no lado do servidor antes da conversão. Uma busca HTTP simples pela mesma URL retorna o markup pré-renderizado em vez disso.

P: O que devo verificar antes de apontar uma equipe para um site ativo?

Revise os termos do site e suas diretrizes do /robots.txt, que seguem o padrão do Protocolo de Exclusão de Robôs. Mantenha a coleta a páginas públicas e forneça à equipe uma lista de tarefas delimitada em vez de uma instrução de rastreamento em aberto — um loop de agente pode, de outra forma, emitir muito mais solicitações do que você pretendia.