Composio + Scrapeless: Adicione uma Caixa de Ferramentas MCP Personalizada

TL;DR:

• Scrapeless não está no catálogo de ferramentas da Composio, então se junta como uma ferramenta MCP personalizada. O painel da Composio tem um diálogo Adicionar MCP Personalizado, marcado como Beta, que cria uma a partir de um servidor MCP remoto.
• O diálogo aceita quatro valores. Um nome de exibição, a URL do servidor https://api.scrapeless.com/mcp, chave da API como tipo de autenticação, e x-api-token como o nome do cabeçalho em Configurações Avançadas.
• Deixe o prefixo do cabeçalho vazio. Scrapeless espera a chave pura em x-api-token. Com um prefixo como token, o handshake e a listagem de 25 ferramentas ainda têm sucesso, mas cada chamada de ferramenta falha.
• Composio verifica se uma chave foi inserida, não se o Scrapeless a aceita. Verifique a chave e o valor do cabeçalho antes de adicionar a ferramenta, e confirme com uma chamada de ferramenta depois.
• A ferramenta pertence a um projeto Composio. Adicione seu slug CUSTOM_ a uma sessão e passe session.mcp.url para qualquer cliente MCP.
• Obtenha uma chave no plano gratuito do Scrapeless e adicione a ferramenta em poucos minutos.

As sessões Composio dão a um agente ferramentas autenticadas em uma longa lista de aplicativos, com as credenciais mantidas do lado da Composio. O que uma sessão não inclui é a web ao vivo, como uma página à medida que é renderizada hoje ou os resultados de uma busca no Google. O servidor MCP do Scrapeless fornece isso como ferramentas, e o recurso MCP Personalizado da Composio permite que uma sessão as chame junto com suas ferramentas internas.

Este guia adiciona Scrapeless através do diálogo do painel e depois usa a ferramenta em uma sessão. A maior parte do trabalho é um único formulário. A parte que precisa de cuidado é o cabeçalho, pois um formato de cabeçalho errado parece estar conectado até que uma ferramenta realmente seja executada.

Por que Scrapeless se Junta à Composio como uma Ferramenta MCP Personalizada

O catálogo da Composio contém as ferramentas que a Composio publica, e Scrapeless não é uma delas. Para um serviço fora do catálogo, o guia MCP Personalizado da Composio descreve o caminho. Você registra um servidor MCP remoto pelo seu URL público HTTPS e esquema de autenticação, e a Composio cria uma ferramenta com um slug CUSTOM_, sincroniza as ferramentas do servidor e encaminha cada chamada de ferramenta para o servidor com as credenciais da conta conectada.

Três limites vêm junto. O MCP personalizado é experimental, e a Composio diz que seu fluxo de configuração e contratos podem mudar. A ferramenta é escopo do projeto Composio que a registra. E a Composio não hospeda o servidor, então o servidor deve ser acessível via HTTPS; Scrapeless é um endpoint hospedado, então nada roda na sua máquina.

O mesmo guia ainda descreve o registro como apenas via API e lista a gestão do painel como vindo em breve. O painel da Composio em setembro de 2026 já mostrava um diálogo Adicionar MCP Personalizado, rotulado como Beta e Apenas MCP, e esse diálogo é o caminho que este guia segue. A rota da API é coberta na FAQ.

O que Scrapeless Adiciona a uma Sessão Composio

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 na nuvem passo a passo.
• crawl_start, crawl_result e crawl_cancel executam um rastreamento em segundo plano e coletam depois.
• google_search e google_trends retornam resultados de busca e dados de tendência, e ai_scraper captura respostas de assistentes de IA como ChatGPT, Gemini e Perplexidade.

Todas as 25 chegam como uma única ferramenta. Em uma sessão padrão, o guia da Composio diz que um agente descobre ferramentas personalizadas através da pesquisa de ferramentas e as executa através do Roteador de Ferramentas, da mesma forma que alcança ferramentas internas.

Pré-requisitos

• Uma conta Composio com um projeto. As ferramentas MCP personalizadas pertencem a um projeto.
• Uma chave da API Scrapeless do painel Scrapeless. Uma chave que serve apenas a Composio pode ser rotacionada sem afetar suas outras integrações.
• Python 3 para a verificação no Passo 1, que usa apenas a biblioteca padrão.
• Para o Passo 4, o SDK Python da Composio (este guia usou composio 0.21.1) e sua chave da API do projeto Composio. O código da sessão do Passo 4 ainda não foi executado contra um projeto Composio para este guia.

Passo 1: Verifique a Chave e o Valor do Cabeçalho

O guia da Composio lista uma lacuna conhecida que vale a pena planejar: quando você conecta um servidor de chave de API, a configuração verifica se uma chave foi fornecida, não se o servidor remoto a aceita. Scrapeless adiciona um segundo ponto cego, porque ele responde ao handshake MCP e lista suas ferramentas para qualquer valor de chave. Uma chave errada ou um formato de cabeçalho errado só aparece quando uma ferramenta é executada.
Este script envia as solicitações que um cliente MCP envia, com a chave no cabeçalho x-api-token, lista as ferramentas e então chama scrape_markdown uma vez. Ele segue o transporte HTTP transmitível do MCP, JSON-RPC sobre POST para um único ponto final, e não precisa de nada além da biblioteca padrão do Python:

import json
import os
import urllib.request

URL = "https://api.scrapeless.com/mcp"
PREFIX = os.environ.get("HEADER_PREFIX", "")
HEADERS = {
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream",
    "x-api-token": f"{PREFIX} {os.environ['SCRAPELESS_API_KEY']}".strip(),
}


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": "header-check", "version": "1.0"}},
})
post({"jsonrpc": "2.0", "method": "notifications/initialized"}, session)
_, listing = post({"jsonrpc": "2.0", "id": 2, "method": "tools/list"}, session)
_, result = post({
    "jsonrpc": "2.0", "id": 3, "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"])
print("tools listed:", len(listing["result"]["tools"]))
if text.startswith("Failed to fetch data"):
    print("key rejected:", text[:20])
else:
    print(f"key accepted: {len(text)} characters of Markdown")

Com sua chave exportada como SCRAPELESS_API_KEY, ele imprime:

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

Agora exporte HEADER_PREFIX=token e execute-o novamente. O script coloca token e um espaço antes da chave, a forma que um valor de cabeçalho prefixado assume:

scrapeless-mcp-server 0.2.0
tools listed: 25
key rejected: Failed to fetch data

A conexão e a contagem de ferramentas são idênticas em ambas as execuções. Apenas a chamada da ferramenta as diferencia, e Bearer como prefixo falha da mesma maneira.

Etapa 2: Adicionar Scrapeless Com Adicionar MCP Personalizado

No painel do Composio, abra Adicionar MCP Personalizado, a caixa de diálogo intitulada "Criar um kit de ferramentas de um servidor MCP remoto", e preencha-a:

Então escolha Adicionar.

O prefixo do cabeçalho é o campo a ser observado. Ele existe para APIs que esperam uma palavra de esquema na frente da credencial, como Bearer. O Scrapeless lê o valor completo do x-api-token como a chave, então qualquer prefixo transforma uma chave válida em uma que ele rejeita, como a segunda execução na Etapa 1 demonstrou.

Obtenha essas configurações corretas antes de salvar. Na API do Composio, o formato do cabeçalho faz parte do esquema de autenticação do kit de ferramentas, e o guia do MCP Personalizado diz que a URL do servidor e o esquema de autenticação não podem mudar após o registro; uma tentativa retorna 409 Conflict. Para corrigir um kit de ferramentas salvo com um prefixo, use Excluir na sua página e adicione-o novamente. Excluir um kit de ferramentas personalizado também remove suas configurações de autenticação e contas conectadas, portanto, você reconecta a conta depois.

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

Etapa 3: Conectar uma Conta e Deixar as Ferramentas Sincronizarem

Um kit de ferramentas baseado em chave de API não tem nada a chamar até que uma conta esteja conectada, e é aqui que a chave vai. O prefixo de cabeçalho vazio da Etapa 2 apenas significa que nada é colocado antes da chave. Conectar abre uma página intitulada "Composio deseja se conectar ao seu" seguida pelo nome do kit de ferramentas, com um único campo Chave de API obrigatório. Cole sua chave de API do Scrapeless lá e escolha Conectar Conta. O Composio armazena a chave na conta conectada e a coloca no cabeçalho x-api-token de cada solicitação que envia para o Scrapeless.

A primeira sincronização começa em segundo plano assim que essa conta se torna ativa. De volta à página do Scrapeless, Contas Conectadas lista a conta como Ativa, e Ações Disponíveis mostra 25, uma para cada ferramenta do Scrapeless, sob nomes como "Raspador de Ai" e "Clique no Navegador". Conexões posteriores não sincronizam o kit de ferramentas novamente, então quando o Scrapeless adiciona ferramentas, use Sincronizar nessa página. Um kit de ferramentas personalizado contém no máximo 500 ferramentas.

Uma lista de ferramentas sincronizadas prova que o Composio alcançou o servidor. Isso não prova a chave, pela razão que a Etapa 1 mostrou, que é por isso que a última etapa termina em uma chamada de ferramenta.

A chave agora também vive com um terceiro. A orientação de gerenciamento de segredos da OWASP trata a rotação como rotina, e uma chave dedicada ao Composio é uma que você pode rotacionar sem quebrar nada mais.

Etapa 4: Usar o Kit de Ferramentas em uma Sessão

Adicione o slug do kit de ferramentas a uma sessão. Com mcp=True, a sessão também expõe um servidor MCP hospedado que qualquer cliente MCP pode usar.

Nota: este código segue o SDK Python do Composio 0.21.1 e os guias de sessão do Composio; ainda não foi executado contra um projeto do Composio para este guia. Ele precisa que COMPOSIO_API_KEY esteja definido como sua chave de API do projeto.

from composio import Composio

composio = Composio()  # reads COMPOSIO_API_KEY from the environment

session = composio.sessions.create(
    user_id="user_123",
    toolkits=["CUSTOM_SCRAPELESS"],
    connected_accounts={"CUSTOM_SCRAPELESS": ["ca_your_connected_account_id"]},
    mcp=True,
)

print(session.mcp.url)

Use o slug mostrado na página do seu kit de ferramentas se ele diferir de CUSTOM_SCRAPELESS; o Composio adiciona o prefixo CUSTOM_ quando registra o kit de ferramentas. A entrada connected_accounts fixa a conta como a qual as chamadas são executadas. Sessões combinam contas por user_id por conta própria apenas quando a configuração de autenticação do kit de ferramentas tem habilitado o roteamento de ferramentas correspondente, e sem isso as chamadas falham com NoActiveConnection. Fixar a conta funciona de qualquer maneira.
Guia do Composio para sessões via MCP passa session.mcp.url e session.mcp.headers para a configuração MCP do cliente, para frameworks como o OpenAI Agents SDK e o Claude Agent SDK. Os cabeçalhos carregam a credencial para essa URL, então entregue-os ao cliente sem registrá-los.

Em seguida, dê ao agente um trabalho verificável:

Use the Scrapeless scrape_markdown tool to fetch https://example.com
and reply with the first heading of the returned page, quoted exactly.

Uma configuração funcional responde com "# Example Domain". Uma resposta que cita Failed to fetch data remete à chave ou ao prefixo do cabeçalho.

Corrigir os Problemas Comuns

Para mais informações sobre o que o servidor expõe, leia o anúncio do servidor MCP Scrapeless. A documentação do MCP do navegador contém a referência de configuração, a página da API de extração cobre os atores por trás das ferramentas e a precificação lista o custo de uma chamada.

Conclusão

Adicionar Scrapeless ao Composio exige um diálogo: um nome de exibição, https://api.scrapeless.com/mcp, autenticação com chave da API, x-api-token como o nome do cabeçalho e um prefixo de cabeçalho vazio. Conecte uma conta com sua chave, deixe as ferramentas sincronizarem e adicione o kit de ferramentas CUSTOM_ a uma sessão.

O que precisa de atenção é a lacuna entre sincronizado e funcional. O Composio confirma que uma chave foi inserida, e o Scrapeless lista suas ferramentas para qualquer chave, então um erro de prefixo passa por ambas as verificações. Execute a verificação da chave antes de adicionar o kit de ferramentas e uma chamada real de ferramenta após isso, e a configuração é comprovada de ponta a ponta.

Pronto para dar aos seus agentes Composio uma visão ao vivo da web? Comece com o plano gratuito do Scrapeless e adicione o kit de ferramentas.

FAQ

Q: Posso adicionar um servidor MCP personalizado ao Composio?

Sim. MCP personalizado registra um servidor remoto pelo seu URL HTTPS e esquema de autenticação e o transforma em um kit de ferramentas com escopo de projeto com um slug CUSTOM_. O painel tem um diálogo Adicionar MCP Personalizado para isso, e a API do Composio oferece o mesmo registro por meio de seus endpoints de kit de ferramentas personalizados.

Q: O que deve ir no Prefixo do Cabeçalho para Scrapeless?

Nada. Defina o nome do cabeçalho como x-api-token e deixe o prefixo vazio, porque o Scrapeless lê todo o valor do cabeçalho como a chave. Um prefixo token ou Bearer faz com que cada chamada de ferramenta falhe, mesmo que as ferramentas ainda sincronizem.

Q: Onde eu insiro a chave da API do Scrapeless no Composio?

Na página de conexão, quando você conecta uma conta no kit de ferramentas. O diálogo Adicionar MCP Personalizado apenas define o nome do cabeçalho e o prefixo; a página de conexão pede pela Chave da API, e o Composio envia esse valor como o cabeçalho x-api-token.

Q: Por que minhas ferramentas Scrapeless sincronizam no Composio, mas cada chamada falha?

A listagem de ferramentas funciona com qualquer valor de chave, então um kit de ferramentas sincronizado não prova a credencial. Chamadas que retornam Failed to fetch data significam que o valor do cabeçalho está errado: um Prefixo do Cabeçalho preenchido ou uma chave inválida. Execute a verificação da Etapa 1 com sua chave para ver qual.

Q: Posso mudar as configurações do cabeçalho após adicionar o kit de ferramentas?

Não no local. O Composio considera a URL do servidor e o esquema de autenticação como fixos após o registro. Exclua o kit de ferramentas, adicione-o novamente com as configurações corretas e conecte a conta novamente, uma vez que a exclusão remove suas conexões.

Q: Posso registrar o Scrapeless através da API do Composio em vez do painel?
Sim. POST /api/v3.1/custom/toolkits/upsert leva a URL do servidor e um esquema de autenticação API_KEY com um objeto headers. Composio permite nomes de cabeçalho diferentes de Authorization, contanto que um valor de cabeçalho contenha {{generic_api_key}}, assim a entrada para Scrapeless é "x-api-token": "{{generic_api_key}}". Para servidores com chave de API, o guia adiciona uma etapa de configuração de autenticação separada antes que as contas possam se conectar.

P: O conjunto de ferramentas Scrapeless está disponível em todos os meus projetos Composio?

Não. Um conjunto de ferramentas MCP personalizado é limitado ao projeto que o registra. Adicione Scrapeless em cada projeto que precisar dele.

P: Claude, Cursor ou outro cliente MCP podem usar Scrapeless através do Composio?

Sim. Crie uma sessão com mcp=True e dê ao cliente session.mcp.url e session.mcp.headers. O cliente então acessa as ferramentas Scrapeless através da sessão Composio.

P: Quantas ferramentas o Scrapeless adiciona ao Composio?

25: três ferramentas scrape_*, dezesseis ferramentas browser_*, três ferramentas crawl_*, além de google_search, google_trends e ai_scraper.