coreclaw webscraper

O serviço MCP CoreClaw expõe os fluxos de trabalho públicos do CoreClaw OpenAPI v2 por meio do Model Context Protocol (MCP). Após a conexão, o Agente de IA pode descobrir Workers do CoreClaw, visualizar schemas de entrada, executar Workers ou tarefas salvas, consultar status de execução, ler logs e exportar resultados estruturados.

Arquitetura

用户对话 -> AI Agent -> MCP 协议 -> CoreClaw MCP 服务 -> CoreClaw OpenAPI v2
                              HTTP       mcp.coreclaw.com      openapi.coreclaw.com

O endpoint de entrada HTTP Streamable hospedado é:

https://mcp.coreclaw.com/mcp

Priorize o endpoint hospedado. A execução local do coreclaw-mcp-server só é necessária durante desenvolvimento, depuração ou quando o cliente suporta apenas stdio local.

Pré-requisitos

• Conta CoreClaw. Se ainda não tiver uma, registre-se primeiro.
• Chave de API CoreClaw, disponível em Console -> Configurações -> API & Integrações.
• Cliente compatível com MCP. Consulte Plataformas suportadas abaixo.

Início rápido

Adicione a seguinte configuração no seu cliente MCP:

{
  "mcpServers": {
    "coreclaw": {
      "url": "https://mcp.coreclaw.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_CORECLAW_API_KEY"
      }
    }
  }
}

Após salvar a configuração, reinicie ou recarregue o cliente se solicitado. Depois disso, o Agente de IA poderá chamar as ferramentas CoreClaw na conversa.

Métodos de autenticação

O serviço MCP hospedado usa autenticação Authorization: Bearer <token> — o mesmo cabeçalho do CoreClaw OpenAPI v2. Para compatibilidade com integrações antigas, os cabeçalhos api-key e X-API-Key ainda são aceitos:

• Authorization: Bearer YOUR_CORECLAW_API_KEY (recomendado)
• api-key: YOUR_CORECLAW_API_KEY (legado)
• X-API-Key: YOUR_CORECLAW_API_KEY (legado)

O serviço MCP encaminha as credenciais de autenticação para o CoreClaw OpenAPI v2, e as requisições upstream usam uniformemente Authorization: Bearer <token>.

Não envie chaves de API para sistemas de controle de versão. Quando o cliente suportar armazenamento seguro de credenciais, priorize esse recurso.

Ferramentas disponíveis

O serviço MCP CoreClaw expõe 42 ferramentas — 39 operações do OpenAPI v2 (1:1) mais 3 assistentes de orquestração. As interfaces de criação/atualização de versão de Worker e de detalhes internos do Worker são internas e não são expostas via MCP.

Descoberta e pré-verificação

Ferramenta	Descrição	API correspondente
list_proxy_regions	Consulta códigos e nomes de regiões de proxy	GET /api/v2/proxy/region
list_store_workers	Pesquisa Workers públicos da Store	GET /api/v2/store
list_workers	Lista Workers da conta atual	GET /api/v2/workers
get_worker	Obtém metadados, versão, README e parâmetros do Worker	GET /api/v2/workers/{workerId}
get_worker_input_schema	Obtém o schema de entrada público do Worker	GET /api/v2/workers/{workerId}/input-schema
get_account_info	Consulta saldo da conta, cota de tráfego e data de expiração	GET /api/v2/users/account

Tarefas de Worker (modelos de tarefa salvos)

Ferramenta	Descrição	API correspondente
list_worker_tasks	Lista tarefas de Worker salvas na conta atual	GET /api/v2/worker-tasks
get_worker_task	Obtém detalhes de uma tarefa salva	GET /api/v2/worker-tasks/{workerTaskId}
get_worker_task_input	Obtém o payload de entrada de uma tarefa salva	GET /api/v2/worker-tasks/{workerTaskId}/input
create_worker_task	Cria tarefa salva (agendamento opcional)	POST /api/v2/worker-tasks
update_worker_task	Atualiza metadados/agendamento da tarefa	PUT /api/v2/worker-tasks/{workerTaskId}
update_worker_task_input	Atualiza apenas o payload de entrada da tarefa	PUT /api/v2/worker-tasks/{workerTaskId}/input
delete_worker_task	Exclui tarefa salva	DELETE /api/v2/worker-tasks/{workerTaskId}

Assistentes de orquestração

Três ferramentas de conveniência que combinam várias chamadas de API em uma única chamada de ferramenta.

Ferramenta	Descrição	Chamadas subjacentes
poll_run	Faz polling da execução até o estado final (ou timeout)	Repetir GET /api/v2/worker-runs/{runId}
verify_run	Retorna veredito estruturado ( PASS / NO_DATA / FAILED / ERROR_RECORD / RUNNING / SUBMIT_FAIL ) — verifica o status da execução e depois inspeciona a primeira linha de resultado, distinguindo dados reais de registros apenas de diagnóstico	get_worker_run + list_worker_run_results
run_workers_batch	Executa até 50 Workers em uma única chamada, retornando resumo e veredito por item. Concorrência 1–10, com verify opcional por item	Por item: POST /api/v2/workers/{workerId}/runs + poll_run (+ verify_run opcional)

poll_run aceita timeout_seconds (1–900, padrão 300) e poll_interval_seconds (1–60, padrão 5), e em caso de sucesso pode pré-buscar uma pequena prévia dos resultados ( limit ). Use-o para Workers cujo tempo de execução excede a janela de uma única chamada MCP. verify_run é usado para distinguir sucesso real de falsos positivos como "CAPTCHA/linha 403 preencheu a lista sem payload real" — ele marca o último caso como ERROR_RECORD . get_worker_run_log também suporta grep em processo (separado por pipe, sem diferenciar maiúsculas de minúsculas) além de context_lines e max_matches .

Execução

Ferramenta	Descrição	API correspondente
run_worker	Executa Worker com entrada JSON temporária	POST /api/v2/workers/{workerId}/runs
run_worker_task	Executa tarefa de Worker salva	POST /api/v2/worker-tasks/{workerTaskId}/runs

Fila de execução

Ferramenta	Descrição	API correspondente
queue_worker_run	Coloca a execução na fila, aguardando ativação explícita em vez de execução imediata	POST /api/v2/workers/{workerId}/queued-runs
list_run_queue_items	Lista execuções enfileiradas aguardando ativação	GET /api/v2/run-queue/items
activate_run_queue_items	Ativa execução enfileirada para execução	POST /api/v2/run-queue/items/activate
release_run_queue_items	Libera execução enfileirada de volta para a fila	POST /api/v2/run-queue/items/release
release_run_queue_item	Libera uma única execução enfileirada	POST /api/v2/run-queue/items/{queueId}/release

Consulta de execuções

Ferramenta	Descrição	API correspondente
list_worker_runs	Consulta histórico de execuções	GET /api/v2/worker-runs
get_last_worker_run	Consulta a execução mais recente da conta atual	GET /api/v2/worker-runs/last
get_worker_run	Consulta execução específica via run_id	GET /api/v2/worker-runs/{runId}
get_worker_last_run	Consulta a execução mais recente de um Worker específico	GET /api/v2/workers/{workerId}/runs/last

Resultados, exportação e logs

Ferramenta	Descrição	API correspondente
list_last_worker_run_results	Visualiza o resultado da execução mais recente da conta atual	GET /api/v2/worker-runs/last/result
export_last_worker_run_results	Exporta o resultado da execução mais recente da conta atual	GET /api/v2/worker-runs/last/export
get_last_worker_run_log	Visualiza o log da execução mais recente da conta atual	GET /api/v2/worker-runs/last/log
list_worker_run_results	Visualiza o resultado de uma execução específica	GET /api/v2/worker-runs/{runId}/result
export_worker_run_results	Exporta o resultado de uma execução específica	GET /api/v2/worker-runs/{runId}/result/export
get_worker_run_log	Visualiza o log de uma execução específica	GET /api/v2/worker-runs/{runId}/log
list_worker_last_run_results	Visualiza o resultado da execução mais recente de um Worker específico	GET /api/v2/workers/{workerId}/runs/last/result
export_worker_last_run_results	Exporta o resultado da execução mais recente de um Worker específico	GET /api/v2/workers/{workerId}/runs/last/export
get_worker_last_run_log	Visualiza o log da execução mais recente de um Worker específico	GET /api/v2/workers/{workerId}/runs/last/log

Reexecução e controle

Ferramenta	Descrição	API correspondente
rerun_last_worker_run	Reexecuta a execução mais recente da conta atual	POST /api/v2/worker-runs/last/rerun
rerun_worker_run	Reexecuta uma execução específica	POST /api/v2/worker-runs/{runId}/rerun
rerun_worker_last_run	Reexecuta a execução mais recente de um Worker específico	POST /api/v2/workers/{workerId}/runs/last/rerun
abort_last_worker_run	Interrompe a execução ativa mais recente da conta atual	POST /api/v2/worker-runs/last/abort
abort_worker_run	Interrompe uma execução ativa específica	POST /api/v2/worker-runs/{runId}/abort
abort_worker_last_run	Interrompe a execução ativa mais recente de um Worker específico	POST /api/v2/workers/{workerId}/runs/last/abort

Fluxos de trabalho típicos

Ao executar um Worker temporariamente, normalmente chame nesta ordem:

list_store_workers(keyword)
  -> get_worker_input_schema(worker_id)
    -> run_worker(worker_id, input_json, is_async=true)
      -> get_worker_run(run_id)
        -> list_worker_run_results(run_id) 或 export_worker_run_results(run_id)

Ao executar uma tarefa salva, use:

list_worker_tasks(worker_id)
  -> run_worker_task(worker_task_id, is_async=true)
    -> get_worker_run(run_id)
      -> list_worker_run_results(run_id)

Se o schema de entrada do Worker exigir região de proxy, chame list_proxy_regions primeiro. Use as ferramentas rerun_* somente quando o usuário solicitar explicitamente uma nova tentativa ou execução repetida; use as ferramentas abort_* somente quando o usuário solicitar explicitamente a interrupção da execução.

Entrada do Worker

Ao chamar run_worker , coloque os campos de negócio em input_json :

{
  "worker_id": "YOUR_WORKER_ID",
  "version": "latest",
  "input_json": "{\"keyword\":\"coffee\",\"limit\":10}",
  "is_async": true
}

O serviço MCP envolve input_json como o input.parameters.custom usado pelo CoreClaw. Chamadas avançadas podem passar o objeto CoreClaw input completo diretamente via raw_input_json , mas não podem passar input_json e raw_input_json ao mesmo tempo.

Plataformas suportadas

Plataforma	Método de configuração	Guia
Claude Desktop	Streamable HTTP	Guia de configuração
Claude CLI	Streamable HTTP	Guia de configuração
Codex Desktop	Streamable HTTP	Guia de configuração
Cursor	Streamable HTTP	Guia de configuração
ChatGPT	Streamable HTTP	Guia de configuração
VS Code	Streamable HTTP	Guia de configuração
Windsurf	Streamable HTTP	Guia de configuração
Cline	Streamable HTTP	Guia de configuração
n8n	Streamable HTTP	Guia de configuração
HTTP genérico	Qualquer cliente MCP Streamable HTTP ou chamador de ferramentas estilo REST	Guia de configuração

Endpoints compatíveis com REST

Além do endpoint MCP padrão /mcp , o serviço também oferece o endpoint compatível com REST /mcp/<tool_name> , adequado para plataformas que preferem fazer requisições HTTP por ferramenta:

curl -X POST https://mcp.coreclaw.com/mcp/list_store_workers \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_CORECLAW_API_KEY" \
  -d '{"keyword":"amazon","offset":1,"limit":5}'

Mais exemplos de JSON-RPC e REST em Cliente HTTP genérico .

Solução de problemas

Sintoma	Causa possível	Como resolver
Invalid API key	Chave ausente, incorreta ou expirada	Verifique a chave em Console -> Configurações -> API & Integrações
Worker does not exist (50001)	Erro de worker_id	Use list_store_workers ou list_workers para obter o slug/path retornado
Ferramentas não aparecem	O cliente não carregou a configuração MCP Streamable HTTP	Reinicie o cliente e verifique o caminho da configuração MCP
Execução iniciada, mas sem linhas de resultado	A execução ainda está em andamento ou falhou	Faça polling com get_worker_run ; em caso de falha, chame get_worker_run_log
Região de proxy rejeitada	Código de região de proxy inválido	Chame list_proxy_regions e use os códigos de região retornados

Notas de limitação

• O serviço hospedado usa Streamable HTTP. Clientes que suportam apenas stdio local precisam executar coreclaw-mcp-server localmente.
• A autenticação é baseada em chave de API; o endpoint hospedado não requer OAuth.
• Interfaces internas não são expostas via MCP, incluindo criação/atualização de versão de Worker e detalhes internos do Worker.

Próximos passos

• Configurar Claude Desktop
• Configurar Codex Desktop
• Configurar HTTP genérico
• Ler a documentação da API CoreClaw