Webhound

Otorga a los agentes un presupuesto de investigación y obtén informes o conjuntos de datos citados e inspeccionables.

GitHub
2

Documentación

Webhound MCP

Sitio web · Tesis · Configuración de MCP · npm · Registro oficial

La investigación no tiene un punto de parada natural. Un prompt le dice a un agente qué investigar, pero no le dice al agente cuánto trabajo merece la pregunta.

Webhound añade ese control que falta. Dale un prompt y un presupuesto en dólares; gasta ese esfuerzo buscando, leyendo, verificando y ensamblando un informe citado o un conjunto de datos estructurado. El resultado final incluye los documentos de trabajo, fuentes, rastros de afirmaciones, limitaciones y el paquete de evidencia detrás de la respuesta.

Ejecuta Webhound desde cualquier agente que hable MCP. Webhound crea informes y conjuntos de datos privados y presupuestados, funciona como sidecar de investigación del agente, acepta notas respaldadas por fuentes sin interrupciones, diagnostica fallos y devuelve salidas citadas con fuentes y rastros de afirmaciones.

Este paquete es el transporte local stdio. Webhound también admite MCP alojado en:

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

Paquetes nativos para clientes

Este repositorio también empaqueta el MCP alojado y la habilidad webhound-research para GitHub Copilot, Claude Code, Cursor y Kiro:

  • GitHub Copilot usa plugin.json, .mcp.json y skills/webhound-research/SKILL.md.
  • Claude Code usa .claude-plugin/plugin.json, .mcp.json y la misma habilidad. El marketplace incluido se puede probar con claude plugin marketplace add WebhoundAI/webhound-mcp, luego claude plugin install webhound@webhound.
  • Cursor usa .cursor-plugin/plugin.json, mcp.json y la misma habilidad.
  • Kiro usa POWER.md y mcp.json.

Ambos archivos MCP apuntan al endpoint remoto de producción de Webhound y no contienen ninguna clave API, token de portador, cliente OAuth estático ni credencial de publicador compartida. Cada persona autoriza su propia cuenta de Webhound mediante OAuth. La entrada oauthScopes en mcp.json es requerida por Kiro para que solicite los dos alcances compatibles de Webhound en lugar de los predeterminados no relacionados de Kiro. Cursor ignora ese campo específico de Kiro y completa OAuth desde los metadatos de autorización publicados de Webhound.

La habilidad compartida enseña a cada cliente el mismo contrato público:

  • Hound es el arnés de investigación de Webhound, construido con DeepSeek V4 Pro y GPT-5.4 en planificación, ejecución, verificación y ensamblaje.
  • El prompt define la investigación. El presupuesto en dólares controla el esfuerzo de investigación.
  • done=true es la puerta de finalización. El agente luego inspecciona el paquete de evidencia cuando la respuesta depende del rastro de investigación.

Modo desarrollador de ChatGPT:

  1. Activa el Modo desarrollador en Configuración → Seguridad e inicio de sesión.
  2. Abre Configuración → Plugins, crea una aplicación y usa la URL de MCP alojado anterior.
  3. Haz clic en Conectar. ChatGPT abre la página de autorización de Webhound.
  4. Inicia sesión en Webhound y aprueba los alcances de MCP solicitados. No pegues una clave API en el flujo de OAuth.

La aplicación de ChatGPT puede aceptar archivos adjuntos y devolver estado normal de MCP, salida, documentos de trabajo, afirmaciones y fuentes. Webhound deliberadamente no adjunta un panel interactivo personalizado debajo de las llamadas a herramientas. La distribución pública aún requiere el envío del plugin a través de OpenAI.

Replit Agent:

Add Webhound to Replit

El enlace de instalación proporciona solo la URL de MCP alojado de Webhound. Replit descubre los metadatos de OAuth de Webhound y cada persona autoriza su propia cuenta; el payload no contiene clave API, token de portador, secreto de cliente OAuth ni credencial de publicador compartida.

n8n:

Instala n8n-nodes-webhound a través de Configuración → Nodos de la comunidad. Expone operaciones nativas de informe, conjunto de datos, observación/espera, salida, paquete de evidencia, cuenta y ayuda. Los inicios que generan gastos requieren tanto un presupuesto explícito en dólares como una confirmación separada. Cada usuario o espacio de trabajo de n8n proporciona su propia clave API de Webhound cifrada; el paquete no contiene ninguna credencial de publicador compartida.

Instalación

Crea una clave API de Webhound y luego agrega el servidor stdio a tu agente:

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

Conector alojado de Claude:

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

Pega la URL en el flujo de conector personalizado de Claude. El servidor alojado expone los endpoints de descubrimiento, autorización y token de OAuth para ese flujo de conexión.

Smithery:

  1. Agrega el servidor público webhound/webhound a tu propia caja de herramientas de Smithery.
  2. Cada nueva conexión de Smithery comienza en auth_required y abre una pantalla de configuración de Webhound que solicita a ese usuario su propia clave API de Webhound.
  3. Webhound intercambia esa clave por un token MCP con alcance almacenado en esa conexión de Smithery.
  4. Conectar otro cliente a la misma caja de herramientas ya autorizada puede no volver a solicitar; eso es la reutilización de la conexión guardada del mismo usuario, no una credencial de publicador compartida con otros usuarios.

No distribuyas el endpoint privado de la caja de herramientas de un usuario como si fuera una credencial compartida de Webhound. Otros usuarios deben agregar Webhound a su propia caja de herramientas o conectarse directamente a la URL de MCP alojado de 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

Guarda, inicia sesión en Webhound, aprueba la conexión y luego comienza una nueva tarea de Manus y envía:

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.

Otros clientes alojados deben usar la misma URL de servidor con OAuth cuando sea compatible. Solo los clientes que no admiten OAuth deben usar una clave de Webhound generada manualmente en su configuración avanzada de token de portador o 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 y Claude Desktop usan la forma JSON anterior.

Cline CLI:

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

También puedes usar la forma JSON local stdio anterior en la configuración de MCP de Cline. Después de guardar la configuración local stdio, reinicia la sesión del agente o abre una nueva si las herramientas de Webhound no aparecen. Muchos clientes cargan servidores MCP solo cuando comienza una sesión.

VS Code:

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

Usa la misma forma de servidor stdio para Windsurf. Windsurf comúnmente lo almacena en ~/.codeium/windsurf/mcp_config.json.

Hound

Hound es el arnés de investigación expuesto por Webhound, no un modelo de fundación seleccionable ni un modo. Está construido con DeepSeek V4 Pro y GPT-5.4 en planificación, ejecución, verificación y ensamblaje. No es un paso directo a un solo modelo y no debe describirse como "resolviendo" a un único backend de proveedor.

El prompt define qué investigar. El presupuesto en dólares del usuario define cuánto esfuerzo de investigación puede gastar Hound buscando, leyendo, escribiendo y verificando antes del ensamblaje. El MCP no expone niveles de modelo ni modos alternativos.

Valores predeterminados

Valores predeterminados recomendados de configuración:

  • presupuesto: $5
  • producto: report
  • ejecución gratuita: respeta la preferencia guardada; úsala automáticamente solo cuando esté habilitada, o después de un consentimiento explícito de una sola ejecución para un informe o conjunto de datos exacto de $5

Como regla general, $1 compra aproximadamente 15 minutos de investigación, por lo que el valor predeterminado de $5 es de aproximadamente 75 minutos. Los puntos de partida recomendados son $2 rápido, $5 estándar, $10 profundo y $20 exhaustivo/de mayor riesgo (aproximadamente 300 minutos o cinco horas). Estos no son límites; los usuarios pueden elegir un presupuesto personalizado mayor o decir cuánto tiempo quieren que Webhound investigue, usando aproximadamente $1 por cada 15 minutos.

webhound_onboarding devuelve el flujo guiado de primera ejecución consciente del cliente, incluido el estado de cuenta y de ejecuciones incluidas, el modelo de presupuesto, configuración-primero versus entrar-directo, orientación informe-versus-conjunto-de-datos, espera a través de done=true, procedencia, exportación y seguimiento de facturación. Los clientes alojados como Manus reciben el flujo completo de investigación pero ningún flujo de escritura en el espacio de trabajo a menos que el usuario solicite explícitamente esa acción separada. Iniciar un informe o conjunto de datos normal nunca activa la configuración de reglas del espacio de trabajo.

Los nuevos usuarios pueden tener un pase de ejecución gratuita no divisible. Cubre un informe o conjunto de datos exacto de $5. Se puede usar desde la interfaz de usuario de Webhound, API, MCP alojado o este paquete MCP stdio.

Los agentes pueden leer y actualizar los valores predeterminados con:

  • webhound_onboarding
  • webhound_help
  • webhound_uninstall
  • webhound_get_defaults
  • webhound_set_defaults

Si un usuario solicita explícitamente reglas del espacio de trabajo, el agente debe mostrar el contenido propuesto completo y el destino exacto antes de escribir. Después de la aprobación, lee el archivo de nuevo y rechaza contenido vacío o solo de frontmatter.

Flujo de herramientas

El ciclo de vida central está separado y es visible:

  1. Comienza el trabajo con webhound_start_report o webhound_start_dataset.
  2. Observa con webhound_watch o webhound_wait.
  3. Mientras Webhound se ejecuta, sigue haciendo trabajo independiente útil cuando pueda mejorar el resultado. Si el agente que llama encuentra una nota concreta respaldada por fuentes, guárdala con webhound_add_sidecar_notes. Esto no interrumpe el ciclo actual Planificador -> Ejecutor -> Verificador.
  4. Las notas sidecar son estado compartido. Usa webhound_list_sidecar_notes para inspeccionar lo que ya se ha guardado y webhound_update_sidecar_note para corregir, restaurar o descartar una nota sin dirigir la sesión.
  5. Trata done=true como la señal autoritativa de finalización.
  6. Si una ejecución aún está saludable y tu entorno puede dormir, programa un registro, crea un recordatorio o ejecuta un latido único, usa runtime_estimate.recommended_next_check_seconds y llama a webhound_watch entonces. Si aún se está ejecutando, repite usando la estimación actualizada. Si solo quedan unos minutos, usa webhound_wait.
  7. Si una acción que genera gastos devuelve billing_required o una sesión en ejecución devuelve credit_exhausted, envía al usuario a https://www.webhound.ai/billing para agregar créditos, agregar una tarjeta o habilitar la recarga automática. Pídeles que te avisen cuando terminen. Después de que respondan, llama a webhound_account para confirmar que la facturación está lista, luego reintenta la acción original de inicio/agregar-presupuesto/reanudar.
  8. Si awaiting_input, responde con webhound_send_message usando reason="awaiting_input"; eso reanuda la sesión.
  9. Usa webhound_send_message con reason="user_guidance" solo cuando el usuario cambie el objetivo, el alcance, las restricciones o el entregable. No uses la dirección para sugerencias ordinarias de fuentes.
  10. Solo cuando el usuario solicite explícitamente reducir el alcance restante del informe o terminar con la investigación ya recopilada, llama a webhound_set_budget. Lee budget_control.minimum_target_budget del estado de observación/sesión cuando quieran terminar en el límite seguro más cercano. Reducir el presupuesto no omite el ensamblaje: el presupuesto revisado se convierte en el límite de parada, y Webhound ejecuta el ensamblaje final normal después. Nunca hagas esto solo porque las notas parciales parezcan suficientes o la ejecución esté tomando tiempo.
  11. Cuando done=true y output_ready=true, llama a webhound_get_session para la sesión canónica completa en una respuesta. Si una ejecución terminal no tiene salida, trata su alerta escrita de EMPTY_OUTPUT o DATASET_ZERO_ROWS como un fallo en lugar de afirmar éxito.
  12. webhound_get_evidence_pack devuelve esa misma sesión completa más orientación de seguimiento de evidencia. Úsala cuando la respuesta dependa del rastro de investigación.
  13. Usa webhound_get_output para el resultado pulido completo o webhound_export_session cuando el usuario necesite un archivo. Usa las herramientas de afirmaciones y fuentes cuando necesites una superficie enfocada.
  14. Para conjuntos de datos, inspecciona filas/esquema más fuentes; exporta CSV/JSON cuando el usuario necesite usar los datos en otro lugar.
  15. Después de leer/exportar la salida final y el paquete de evidencia, usa tu propio criterio para mostrar algunos hilos enfocados que el usuario podría seguir después. Basalos en cosas concretas que la sesión descubrió: entidades inexplicadas, brechas de fuentes, rastros de documentos, afirmaciones disputadas, filas faltantes o comparaciones estrechas. Estos deben ser seguimientos más profundos opcionales, no sugerencias genéricas de "investigar más". Si varios son independientes, se pueden iniciar en paralelo como ejecuciones separadas de Webhound.
  16. Si el usuario pide un enlace compartible, usa webhound_get_shareable_link. Eso hace que ese informe o conjunto de datos sea público para cualquier persona con el enlace y devuelve la URL de compartir correcta: /document/:id para informes, /dataset/:id para conjuntos de datos. No es publicación de Explore y no crea una publicación de /p/:slug. El presupuesto controla la profundidad. Como regla general, $1 compra aproximadamente 15 minutos de investigación. Una ejecución saludable puede seguir buscando, leyendo, escribiendo y verificando a través de varias esperas mientras utiliza el presupuesto. Más presupuesto significa más espacio para investigación antes del ensamblaje final; no es una señal para que el agente llamador apresure la ejecución. No envíes orientación de finalización/cierre ni detengas la sesión solo porque las notas de trabajo parciales parezcan utilizables.

Formas de esquema de dataset

Omite schema para permitir que Webhound infiera un esquema conciso. Cuando los campos importan, usa exactamente una de estas formas.

Esquema nativo de 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 de objeto:

{
  "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" }
  }
}

Los esquemas nativos requieren al menos un campo is_primary: true. Para JSON Schema, x-webhound-primary: true tiene prioridad; de lo contrario, la primera propiedad requerida, luego la primera propiedad, se convierte en el campo primario determinista. La respuesta de inicio hace eco de normalized_schema antes de que comience el dataset.

Herramientas 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

Los formatos de carga admitidos son CSV, XLSX, PDF, DOCX, TXT, Markdown y VTT. Convierte archivos XLS/DOC heredados a XLSX/DOCX antes de cargarlos. El tipo MIME, la extensión del nombre de archivo y los bytes de archivo reconocibles se verifican antes de que la carga llegue a Webhound.

Finalización y diagnóstico

webhound_watch devuelve:

  • done: estado terminal
  • output_ready: existe un artefacto; espera a done=true antes de tratarlo como final
  • completion_reason: budget_complete, natural_complete, awaiting_input, user_stopped, credit_exhausted, failed o stuck_or_empty
  • alerts: problemas estructurados con próximas acciones
  • budget_control: si se puede reducir un presupuesto de informe, el gasto actual y el presupuesto, y el objetivo inferior seguro más cercano
  • next_research_instruction: orientación para que el agente llamador derive investigaciones siguientes enfocadas a partir de la salida final y el paquete de evidencia subyacente

No presentes una ejecución como exitosa si alerts contiene un error como empty_output, dataset_zero_rows o credit_exhausted. Para credit_exhausted, usa el billing_url y user_message_template devueltos; no dejes al usuario con un error sin procesar.

Si webhound_wait devuelve still_running=true, eso es normal. Usa la estimación de tiempo de ejecución devuelta para programar el próximo control cuando el entorno del agente admita temporizadores/recordatorios/automatizaciones, luego llama a webhound_watch en ese momento. Usa webhound_add_sidecar_notes para notas respaldadas por fuentes encontradas por el agente llamador. Usa webhound_send_message(reason="awaiting_input") para respuestas de puntos de control y webhound_send_message(reason="user_guidance") para cambios reales de intención del usuario, no para tiempo transcurrido normal o sugerencias de fuentes. Usa webhound_stop solo cuando el usuario pida explícitamente detener, pausar o cancelar la ejecución.

CLI

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

--self-test verifica que el paquete se cargue y que la lista de herramientas de lanzamiento esté presente. Usa webhound_health desde un cliente MCP para verificar la autenticación en vivo y el estado de la cuenta.

Desarrollo 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

Ejecuta la autoprueba del paquete sin credenciales:

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

El conjunto de pruebas es completamente sin conexión y exige una cobertura de línea del 91 %, de rama del 75 % y de función del 88 % en todo el runtime de MCP. npm run verify también reconstruye el paquete publicado, verifica la autoprueba de CLI, verifica la paridad del runtime canónico, inspecciona el artefacto empaquetado y lo instala en un proyecto de consumidor temporal.

Antes de publicar, compara este checkout con el runtime canónico webhound-server/mcp:

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

Licencia

MIT