Webhound

Dê aos agentes um orçamento de pesquisa e obtenha relatórios ou conjuntos de dados citados e inspecionáveis.

Documentação

Webhound MCP

Site · Tese · Configuração do MCP · npm · Registro oficial

A pesquisa não tem um ponto de parada natural. Um prompt diz a um agente o que investigar, mas não diz ao agente quanto trabalho a pergunta merece.

O Webhound adiciona esse controle que falta. Dê a ele um prompt e um orçamento em dólares; ele gasta esse esforço pesquisando, lendo, verificando e montando um relatório citado ou um conjunto de dados estruturado. O resultado final inclui os documentos de trabalho, fontes, rastros de afirmações, limitações e o pacote de evidências por trás da resposta.

Execute o Webhound a partir de qualquer agente que fale MCP. O Webhound cria relatórios e conjuntos de dados privados e com orçamento, atua como um sidecar de pesquisa do agente, aceita notas não interruptivas baseadas em fontes, diagnostica falhas e retorna saídas citadas com fontes e rastros de afirmações.

Este pacote é o transporte local stdio. O Webhound também suporta MCP hospedado em:

https://api.webhound.ai/api/v2/mcp

Pacotes nativos do cliente

Este repositório também empacota o MCP hospedado e a habilidade webhound-research para GitHub Copilot, Claude Code, Cursor e Kiro:

O GitHub Copilot usa plugin.json, .mcp.json e skills/webhound-research/SKILL.md.
O Claude Code usa .claude-plugin/plugin.json, .mcp.json e a mesma habilidade. O marketplace incluído pode ser testado com claude plugin marketplace add WebhoundAI/webhound-mcp, depois claude plugin install webhound@webhound.
O Cursor usa .cursor-plugin/plugin.json, mcp.json e a mesma habilidade.
O Kiro usa POWER.md e mcp.json.

Ambos os arquivos MCP apontam para o endpoint remoto de produção do Webhound e não contêm chave de API, token de portador, cliente OAuth estático ou credencial de editor compartilhada. Cada pessoa autoriza sua própria conta Webhound por meio de OAuth. A entrada oauthScopes em mcp.json é exigida pelo Kiro para que ele solicite os dois escopos suportados do Webhound em vez dos padrões não relacionados do Kiro. O Cursor ignora esse campo específico do Kiro e conclui o OAuth a partir dos metadados de autorização publicados do Webhound.

A habilidade compartilhada ensina a cada cliente o mesmo contrato público:

Hound é o harness de pesquisa do Webhound, construído com DeepSeek V4 Pro e GPT-5.4 em planejamento, execução, verificação e montagem.
O prompt define a investigação. O orçamento em dólares controla o esforço de pesquisa.
done=true é o portão de conclusão. O agente então inspeciona o pacote de evidências quando a resposta depende do rastro da pesquisa.

Modo de desenvolvedor do ChatGPT:

Ative o Modo de desenvolvedor em Configurações → Segurança e login.
Abra Configurações → Plugins, crie um aplicativo e use a URL MCP hospedada acima.
Clique em Conectar. O ChatGPT abre a página de autorização do Webhound.
Entre no Webhound e aprove os escopos MCP solicitados. Não cole uma chave de API no fluxo OAuth.

O aplicativo ChatGPT pode aceitar anexos e retornar status MCP normal, saída, documentos de trabalho, afirmações e fontes. O Webhound deliberadamente não anexa um painel interativo personalizado abaixo das chamadas de ferramenta. A distribuição pública ainda exige o envio do plugin por meio da OpenAI.

Replit Agent:

O link de instalação fornece apenas a URL MCP hospedada do Webhound. O Replit descobre os metadados OAuth do Webhound e cada pessoa autoriza sua própria conta; o payload não contém chave de API, token de portador, segredo de cliente OAuth ou credencial de editor compartilhada.

n8n:

Instale n8n-nodes-webhound por meio de Configurações → Nós da Comunidade. Ele expõe operações nativas de relatório, conjunto de dados, observação/espera, saída, pacote de evidências, conta e ajuda. Inícios que geram custos exigem tanto um orçamento explícito em dólares quanto uma confirmação separada. Cada usuário ou espaço de trabalho do n8n fornece sua própria chave de API Webhound criptografada; o pacote não contém credencial de editor compartilhada.

Instalação

Crie uma chave de API Webhound e adicione o servidor stdio ao seu agente:

{
  "mcpServers": {
    "webhound": {
      "command": "npx",
      "args": ["-y", "webhound-mcp@0.5.3"],
      "env": {
        "WEBHOUND_KEY": "wh_..."
      }
    }
  }
}

Conector hospedado do Claude:

https://api.webhound.ai/api/v2/mcp

Cole a URL no fluxo de conector personalizado do Claude. O servidor hospedado expõe endpoints de descoberta, autorização e token OAuth para esse fluxo de conexão.

Smithery:

Adicione o servidor público webhound/webhound à sua própria caixa de ferramentas Smithery.
Cada nova conexão Smithery começa em auth_required e abre uma tela de configuração do Webhound que pede a esse usuário sua própria chave de API Webhound.
O Webhound troca essa chave por um token MCP com escopo armazenado nessa conexão Smithery.
Conectar outro cliente à mesma caixa de ferramentas já autorizada pode não solicitar novamente; isso é reutilização da conexão salva do mesmo usuário, não uma credencial de editor compartilhada com outros usuários.

Não distribua o endpoint privado da caixa de ferramentas de um usuário como se fosse uma credencial Webhound compartilhada. Outros usuários devem adicionar o Webhound à sua própria caixa de ferramentas ou conectar-se diretamente à URL MCP hospedada do Webhound.

Manus:

Open: https://manus.im/app/plugins
Choose: Create → Add MCP by URL
Server name: Webhound
Server URL: https://api.webhound.ai/api/v2/mcp
Advanced settings: leave empty

Salve, entre no Webhound, aprove a conexão e inicie uma nova tarefa Manus e envie:

Call webhound_onboarding once with client set to hosted. Send its
immediate_next_message exactly once. Treat agent_playbook.conversation_flow as
the canonical sequence; the matching first entry is already consumed, so after
I reply continue with the next unconsumed entry. setup_flow is reference-only
and next_action is only the entry instruction. Do not repeatedly call
onboarding to advance it. Continue the first run through done=true and return
the output with sources and provenance. If I change the subject, drop
onboarding immediately. Do not create or edit workspace rules unless I
explicitly ask.

Outros clientes hospedados devem usar a mesma URL de servidor com OAuth quando suportado. Somente clientes que não suportam OAuth devem usar uma chave Webhound gerada manualmente na configuração avançada de token de portador ou Authorization.

Claude Code:

claude mcp add --transport http webhound https://api.webhound.ai/api/v2/mcp

# Local stdio alternative:
claude mcp add --transport stdio webhound --env WEBHOUND_KEY=wh_... -- npx -y webhound-mcp@0.5.3

Codex:

[mcp_servers.webhound]
command = "npx"
args = ["-y", "webhound-mcp@0.5.3"]

[mcp_servers.webhound.env]
WEBHOUND_KEY = "wh_..."

Cursor e Claude Desktop usam a forma JSON acima.

Cline CLI:

cline mcp add webhound \
  --transport streamable-http \
  --header "Authorization: Bearer wh_..." \
  --yes \
  https://api.webhound.ai/api/v2/mcp

Você também pode usar a forma JSON stdio local acima nas configurações MCP do Cline. Após salvar a configuração stdio local, reinicie a sessão do agente ou abra uma nova se as ferramentas Webhound não aparecerem. Muitos clientes carregam servidores MCP apenas quando uma sessão é iniciada.

VS Code:

{
  "servers": {
    "webhound": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "webhound-mcp@0.5.3"],
      "env": {
        "WEBHOUND_KEY": "wh_..."
      }
    }
  }
}

Use a mesma forma de servidor stdio para Windsurf. O Windsurf geralmente o armazena em ~/.codeium/windsurf/mcp_config.json.

Hound

Hound é o harness de pesquisa exposto pelo Webhound, não um modelo de fundação selecionável ou modo. Ele é construído com DeepSeek V4 Pro e GPT-5.4 em planejamento, execução, verificação e montagem. Não é um pass-through direto para um modelo e não deve ser descrito como "resolvendo" para um único backend de provedor.

O prompt define o que investigar. O orçamento em dólares do usuário define quanto esforço de pesquisa o Hound pode gastar pesquisando, lendo, escrevendo e verificando antes da montagem. O MCP não expõe níveis de modelo ou modos alternativos.

Padrões

Padrões de configuração recomendados:

orçamento: $5
produto: report
execução gratuita: honre a preferência salva; use automaticamente apenas quando ativada, ou após consentimento explícito de uma execução para um relatório ou conjunto de dados exato $5

Como regra geral, $1 compra cerca de 15 minutos de pesquisa, então o padrão $5 é cerca de 75 minutos. Pontos de partida recomendados são $2 rápido, $5 padrão, $10 profundo e $20 exaustivo/maior risco (cerca de 300 minutos ou cinco horas). Estes não são limites; os usuários podem escolher um orçamento personalizado maior ou dizer por quanto tempo querem que o Webhound pesquise, usando cerca de $1 por 15 minutos.

webhound_onboarding retorna o fluxo guiado de primeira execução ciente do cliente, incluindo estado de conta e execuções incluídas, o modelo de orçamento, configuração primeiro versus começar direto, orientação relatório-versus-conjunto de dados, espera por done=true, proveniência, exportação e acompanhamento de cobrança. Clientes hospedados como Manus recebem o fluxo completo de pesquisa, mas nenhum fluxo de escrita no espaço de trabalho, a menos que o usuário solicite explicitamente essa ação separada. Iniciar um relatório ou conjunto de dados normal nunca aciona a configuração de regras do espaço de trabalho.

Novos usuários podem ter um passe de execução gratuita não divisível. Ele cobre um relatório ou conjunto de dados exato $5. Pode ser usado na interface Webhound, API, MCP hospedado ou neste pacote MCP stdio.

Os agentes podem ler e atualizar padrões com:

webhound_onboarding
webhound_help
webhound_uninstall
webhound_get_defaults
webhound_set_defaults

Se um usuário solicitar explicitamente regras de espaço de trabalho, o agente deve mostrar o conteúdo proposto completo e o destino exato antes de escrever. Após a aprovação, ele lê o arquivo de volta e rejeita conteúdo vazio ou apenas com frontmatter.

Fluxo de Ferramentas

O ciclo de vida principal é destacado e visível:

Inicie o trabalho com webhound_start_report ou webhound_start_dataset.
Observe com webhound_watch ou webhound_wait.
Enquanto o Webhound executa, continue fazendo trabalho independente útil quando puder melhorar o resultado. Se o agente chamador encontrar uma nota concreta baseada em fontes, salve-a com webhound_add_sidecar_notes. Isso não interrompe o ciclo atual Planejador -> Executor -> Verificador.
Notas sidecar são estado compartilhado. Use webhound_list_sidecar_notes para inspecionar o que já foi salvo e webhound_update_sidecar_note para corrigir, restaurar ou dispensar uma nota sem direcionar a sessão.
Trate done=true como o sinal autoritativo de conclusão.
Se uma execução ainda estiver saudável e seu ambiente puder dormir, agende um check-in, crie um lembrete ou execute um heartbeat único, use runtime_estimate.recommended_next_check_seconds e chame webhound_watch então. Se ainda estiver em execução, repita usando a estimativa atualizada. Se restarem apenas alguns minutos, use webhound_wait.
Se uma ação que gera custos retornar billing_required ou uma sessão em execução retornar credit_exhausted, envie o usuário para https://www.webhound.ai/billing para adicionar créditos, adicionar um cartão ou ativar recarga automática. Peça para ele avisar quando terminar. Após a resposta, chame webhound_account para confirmar que a cobrança está pronta e repita a ação original de iniciar/adicionar orçamento/retomar.
Se awaiting_input, responda com webhound_send_message usando reason="awaiting_input"; isso retoma a sessão.
Use webhound_send_message com reason="user_guidance" somente quando o usuário mudar o objetivo, escopo, restrições ou entrega. Não use direcionamento para sugestões comuns de fontes.
Somente quando o usuário solicitar explicitamente reduzir o escopo restante do relatório ou terminar com a pesquisa já coletada, chame webhound_set_budget. Leia budget_control.minimum_target_budget do status de observação/sessão quando eles quiserem terminar no limite seguro mais próximo. Reduzir o orçamento não ignora a montagem: o orçamento revisado se torna o limite de parada, e o Webhound executa a montagem final normal depois. Nunca faça isso apenas porque notas parciais parecem suficientes ou a execução está demorando.
Quando done=true e output_ready=true, chame webhound_get_session para a sessão canônica completa em uma resposta. Se uma execução terminal não tiver saída, trate seu alerta digitado EMPTY_OUTPUT ou DATASET_ZERO_ROWS como uma falha em vez de reivindicar sucesso.
webhound_get_evidence_pack retorna essa mesma sessão completa mais orientação de acompanhamento de evidências. Use-o quando a resposta depender do rastro da pesquisa.
Use webhound_get_output para o resultado polido completo ou webhound_export_session quando o usuário precisar de um arquivo. Use as ferramentas de afirmações e fontes quando precisar de uma superfície focada.
Para conjuntos de dados, inspecione linhas/esquema mais fontes; exporte CSV/JSON quando o usuário precisar usar os dados em outro lugar.
Após ler/exportar a saída final e o pacote de evidências, use seu próprio julgamento para apresentar alguns tópicos focados que o usuário poderia explorar em seguida. Baseie-os em coisas concretas que a sessão descobriu: entidades inexplicadas, lacunas de fontes, rastros de artigos, afirmações contestadas, linhas ausentes ou comparações estreitas. Estes devem ser acompanhamentos opcionais mais profundos, não sugestões genéricas de "pesquisar mais". Se vários forem independentes, eles podem ser iniciados em paralelo como execuções separadas do Webhound.
Se o usuário pedir um link compartilhável, use webhound_get_shareable_link. Isso torna esse relatório ou conjunto de dados público para qualquer pessoa com o link e retorna a URL de compartilhamento correta: /document/:id para relatórios, /dataset/:id para conjuntos de dados. Não é publicação no Explore e não cria uma publicação /p/:slug. Orçamento controla a profundidade. Como regra geral, $1 compra cerca de 15 minutos de pesquisa. Uma execução saudável pode continuar buscando, lendo, escrevendo e verificando por várias esperas enquanto usa o orçamento. Mais orçamento significa mais espaço para pesquisa antes da montagem final; não é um sinal para o agente chamador apressar a execução. Não envie orientações de finalização/encerramento nem interrompa a sessão apenas porque notas de trabalho parciais parecem utilizáveis.

Formulários de esquema de conjunto de dados

Omita schema para permitir que o Webhound infira um esquema conciso. Quando os campos importam, use exatamente uma destas formas.

Esquema nativo do Webhound:

{
  "entity_name": "Company",
  "attributes": [
    { "name": "company_name", "type": "string", "is_primary": true },
    { "name": "website", "type": "string", "standard_format": "url" },
    { "name": "employee_count", "type": "number" }
  ]
}

Esquema JSON Object Schema:

{
  "type": "object",
  "title": "Company",
  "required": ["company_name"],
  "properties": {
    "company_name": {
      "type": "string",
      "description": "Official company name",
      "x-webhound-primary": true
    },
    "website": { "type": "string", "format": "uri" },
    "employee_count": { "type": "integer" }
  }
}

Esquemas nativos exigem pelo menos um campo is_primary: true. Para JSON Schema, x-webhound-primary: true tem prioridade; caso contrário, a primeira propriedade obrigatória, depois a primeira propriedade, torna-se o campo primário determinístico. A resposta inicial ecoa normalized_schema antes do início do conjunto de dados.

Ferramentas Públicas

webhound_health
webhound_onboarding
webhound_help
webhound_uninstall
webhound_get_defaults
webhound_set_defaults
webhound_start_report
webhound_start_dataset
webhound_watch
webhound_wait
webhound_add_sidecar_notes
webhound_list_sidecar_notes
webhound_update_sidecar_note
webhound_send_message
webhound_stop
webhound_resume
webhound_add_budget
webhound_set_budget
webhound_get_output
webhound_export_session
webhound_get_evidence_pack
webhound_get_shareable_link
webhound_get_claims
webhound_get_sources
webhound_search_sessions
webhound_list_sessions
webhound_get_session
webhound_upload_file
webhound_account
webhound_diagnose

Os formatos de upload suportados são CSV, XLSX, PDF, DOCX, TXT, Markdown e VTT. Converta arquivos legados XLS/DOC para XLSX/DOCX antes do upload. Tipo MIME, extensão do nome do arquivo e bytes de arquivo reconhecíveis são verificados antes que o upload chegue ao Webhound.

Conclusão e Diagnósticos

webhound_watch retorna:

done: status terminal
output_ready: um artefato existe; aguarde done=true antes de tratá-lo como final
completion_reason: budget_complete, natural_complete, awaiting_input, user_stopped, credit_exhausted, failed ou stuck_or_empty
alerts: problemas estruturados com próximas ações
budget_control: se um orçamento de relatório pode ser reduzido, gasto atual e orçamento, e o alvo inferior seguro mais próximo
next_research_instruction: orientação para o agente chamador derivar investigações focadas a partir da saída final e do pacote de evidências subjacente

Não apresente uma execução como bem-sucedida se alerts contiver um erro como empty_output, dataset_zero_rows ou credit_exhausted. Para credit_exhausted, use o billing_url e user_message_template retornados; não deixe o usuário com um erro bruto.

Se webhound_wait retornar still_running=true, isso é normal. Use a estimativa de tempo de execução retornada para agendar o próximo check-in quando o ambiente do agente suportar temporizadores/lembretes/automações, então chame webhound_watch nesse momento. Use webhound_add_sidecar_notes para notas com fonte encontradas pelo agente chamador. Use webhound_send_message(reason="awaiting_input") para respostas de checkpoint e webhound_send_message(reason="user_guidance") para mudanças reais de intenção do usuário, não para tempo decorrido normal ou sugestões de fonte. Use webhound_stop apenas quando o usuário pedir explicitamente para parar, pausar ou cancelar a execução.

CLI

webhound-mcp --help
webhound-mcp --version
webhound-mcp --self-test

--self-test verifica se o pacote carrega e se a lista de ferramentas de lançamento está presente. Use webhound_health de um cliente MCP para verificar autenticação ao vivo e estado da conta.

Desenvolvimento Local

git clone https://github.com/WebhoundAI/webhound-mcp.git
cd webhound-mcp
npm install
WEBHOUND_KEY=wh_... WEBHOUND_API_BASE=http://localhost:5000/api/v2 node bin/server.mjs

Execute o autoteste do pacote sem credenciais:

npm run self-test
npm test
npm run test:coverage
npm run verify
npm run release:check

A suíte de testes é totalmente offline e impõe 91% de cobertura de linhas, 75% de ramos e 88% de funções em todo o runtime MCP. npm run verify também reconstrói o bundle publicado, verifica o autoteste da CLI, verifica a paridade do runtime canônico, inspeciona o artefato empacotado e o instala em um projeto consumidor temporário.

Antes de publicar, compare este checkout com o runtime canônico webhound-server/mcp:

npm run parity:compare -- /absolute/path/to/webhound-server/mcp

Licença

MIT