{
  "markdown": "# Webhound MCP\n\n[Website](https://www.webhound.ai/) ·\n[Thesis](https://www.webhound.ai/thesis) ·\n[MCP setup](https://www.webhound.ai/mcp-setup) ·\n[npm](https://www.npmjs.com/package/webhound-mcp) ·\n[Official registry](https://registry.modelcontextprotocol.io/)\n\nResearch has no natural stopping point. A prompt tells an agent what to\ninvestigate, but it does not tell the agent how much work the question\ndeserves.\n\nWebhound adds that missing control. Give it a prompt and a dollar budget; it\nspends that effort searching, reading, verifying, and assembling a cited\nreport or structured dataset. The completed result includes the working\ndocuments, sources, claim traces, limitations, and evidence pack behind the\nanswer.\n\nRun Webhound from any MCP-speaking agent. Webhound creates private, budgeted\nreports and datasets, runs as the agent's research sidecar, accepts\nnon-interrupting source-backed notes, diagnoses failures, and returns cited\noutputs with sources and claim traces.\n\nThis package is the local stdio transport. Webhound also supports hosted MCP at:\n\n```text\nhttps://api.webhound.ai/api/v2/mcp\n```\n\n## Client-native packages\n\nThis repository also packages the hosted MCP and the `webhound-research` skill\nfor GitHub Copilot, Claude Code, Cursor, and Kiro:\n\n- GitHub Copilot uses `plugin.json`, `.mcp.json`, and\n  `skills/webhound-research/SKILL.md`.\n- Claude Code uses `.claude-plugin/plugin.json`, `.mcp.json`, and the same\n  skill. The included marketplace can be tested with\n  `claude plugin marketplace add WebhoundAI/webhound-mcp`, then\n  `claude plugin install webhound@webhound`.\n- Cursor uses `.cursor-plugin/plugin.json`, `mcp.json`, and the same skill.\n- Kiro uses `POWER.md` and `mcp.json`.\n\nBoth MCP files point to Webhound's production remote endpoint and contain no\nAPI key, bearer token, static OAuth client, or shared publisher credential.\nEvery person authorizes their own Webhound account through OAuth.\nThe `oauthScopes` entry in `mcp.json` is required by Kiro so it requests\nWebhound's two supported scopes instead of Kiro's unrelated defaults. Cursor\nignores that Kiro-specific field and completes OAuth from Webhound's published\nauthorization metadata.\n\nThe shared skill teaches each client the same public contract:\n\n- Hound is Webhound's research harness, built with DeepSeek V4 Pro and GPT-5.4\n  across planning, execution, verification, and assembly.\n- The prompt defines the investigation. The dollar budget controls research\n  effort.\n- `done=true` is the completion gate. The agent then inspects the evidence pack\n  when the answer depends on the research trail.\n\nChatGPT developer mode:\n\n1. Turn on Developer mode under Settings → Security and login.\n2. Open Settings → Plugins, create an app, and use the hosted MCP URL above.\n3. Click Connect. ChatGPT opens Webhound's authorization page.\n4. Sign in to Webhound and approve the requested MCP scopes. Do not paste an API key into the OAuth flow.\n\nThe ChatGPT app can accept attachments and return normal MCP status, output, working documents, claims, and sources. Webhound deliberately does not attach a custom interactive panel beneath tool calls. Public distribution still requires plugin submission through OpenAI.\n\nReplit Agent:\n\n[![Add Webhound to Replit](https://replit.com/badge?caption=Add%20Webhound%20MCP)](https://replit.com/integrations?mcp=eyJkaXNwbGF5TmFtZSI6IldlYmhvdW5kIiwiYmFzZVVybCI6Imh0dHBzOi8vYXBpLndlYmhvdW5kLmFpL2FwaS92Mi9tY3AiLCJoZWFkZXJzIjpbXX0%3D)\n\nThe install link supplies only Webhound's hosted MCP URL. Replit discovers\nWebhound's OAuth metadata and each person authorizes their own account; the\npayload contains no API key, bearer token, OAuth client secret, or shared\npublisher credential.\n\nn8n:\n\nInstall [`n8n-nodes-webhound`](https://www.npmjs.com/package/n8n-nodes-webhound)\nthrough **Settings → Community Nodes**. It exposes native report, dataset,\nwatch/wait, output, evidence-pack, account, and help operations. Spend-bearing\nstarts require both an explicit dollar budget and a separate confirmation.\nEach n8n user or workspace supplies its own encrypted Webhound API key; the\npackage contains no shared publisher credential.\n\n## Install\n\nCreate a Webhound API key, then add the stdio server to your agent:\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"webhound\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"webhound-mcp@0.5.3\"],\n      \"env\": {\n        \"WEBHOUND_KEY\": \"wh_...\"\n      }\n    }\n  }\n}\n```\n\nClaude hosted connector:\n\n```text\nhttps://api.webhound.ai/api/v2/mcp\n```\n\nPaste the URL into Claude's custom connector flow. The hosted server exposes OAuth discovery, authorize, and token endpoints for that connect flow.\n\nSmithery:\n\n1. Add the public `webhound/webhound` server to your own Smithery toolbox.\n2. Every new Smithery connection starts in `auth_required` and opens a Webhound setup screen that asks that user for their own Webhound API key.\n3. Webhound exchanges that key for a scoped MCP token stored on that Smithery connection.\n4. Connecting another client to the same already-authorized toolbox may not prompt again; that is reuse of the same user's saved connection, not a publisher credential shared with other users.\n\nDo not distribute one user's private toolbox endpoint as if it were a shared Webhound credential. Other users should add Webhound to their own toolbox or connect to the hosted Webhound MCP URL directly.\n\nManus:\n\n```text\nOpen: https://manus.im/app/plugins\nChoose: Create → Add MCP by URL\nServer name: Webhound\nServer URL: https://api.webhound.ai/api/v2/mcp\nAdvanced settings: leave empty\n```\n\nSave, sign in to Webhound, approve the connection, then start a new Manus task\nand send:\n\n```text\nCall webhound_onboarding once with client set to hosted. Send its\nimmediate_next_message exactly once. Treat agent_playbook.conversation_flow as\nthe canonical sequence; the matching first entry is already consumed, so after\nI reply continue with the next unconsumed entry. setup_flow is reference-only\nand next_action is only the entry instruction. Do not repeatedly call\nonboarding to advance it. Continue the first run through done=true and return\nthe output with sources and provenance. If I change the subject, drop\nonboarding immediately. Do not create or edit workspace rules unless I\nexplicitly ask.\n```\n\nOther hosted clients should use the same server URL with OAuth when supported.\nOnly clients that do not support OAuth should use a manually generated Webhound\nkey in their bearer-token or `Authorization` advanced setting.\n\nClaude Code:\n\n```bash\nclaude mcp add --transport http webhound https://api.webhound.ai/api/v2/mcp\n\n# Local stdio alternative:\nclaude mcp add --transport stdio webhound --env WEBHOUND_KEY=wh_... -- npx -y webhound-mcp@0.5.3\n```\n\nCodex:\n\n```toml\n[mcp_servers.webhound]\ncommand = \"npx\"\nargs = [\"-y\", \"webhound-mcp@0.5.3\"]\n\n[mcp_servers.webhound.env]\nWEBHOUND_KEY = \"wh_...\"\n```\n\nCursor and Claude Desktop use the JSON shape above.\n\nCline CLI:\n\n```bash\ncline mcp add webhound \\\n  --transport streamable-http \\\n  --header \"Authorization: Bearer wh_...\" \\\n  --yes \\\n  https://api.webhound.ai/api/v2/mcp\n```\n\nYou can also use the local stdio JSON shape above in Cline's MCP settings.\nAfter saving local stdio config, restart the agent session or open a new one\nif the Webhound tools do not appear. Many clients load MCP servers only when a\nsession starts.\n\nVS Code:\n\n```jsonc\n{\n  \"servers\": {\n    \"webhound\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"webhound-mcp@0.5.3\"],\n      \"env\": {\n        \"WEBHOUND_KEY\": \"wh_...\"\n      }\n    }\n  }\n}\n```\n\nUse the same stdio server shape for Windsurf. Windsurf commonly stores it in\n`~/.codeium/windsurf/mcp_config.json`.\n\n## Hound\n\nHound is the research harness exposed by Webhound, not a selectable foundation\nmodel or mode. It is built with DeepSeek V4 Pro and GPT-5.4 across planning,\nexecution, verification, and assembly. It is not a direct pass-through to one\nmodel and should not be described as \"resolving\" to a single provider backend.\n\nThe prompt defines what to investigate. The user's dollar budget defines how\nmuch research effort Hound can spend searching, reading, writing, and verifying\nbefore assembly. The MCP does not expose alternate model tiers or modes.\n\n## Defaults\n\nRecommended setup defaults:\n\n- budget: `$5`\n- product: `report`\n- free run: honor the saved preference; use automatically only when enabled, or\n  after explicit one-run consent for an exact `$5` report or dataset\n\nAs a rule of thumb, `$1` buys about 15 minutes of research, so the `$5`\ndefault is about 75 minutes. Recommended starting points are `$2` quick, `$5`\nstandard, `$10` deep, and `$20` exhaustive/highest-stakes (about 300 minutes\nor five hours). These are not caps; users can choose a larger custom budget or\nsay how long they want Webhound to research, using about `$1` per 15 minutes.\n\n`webhound_onboarding` returns the client-aware guided first-run flow, including\naccount and included-run state, the budget model, setup-first versus jump-in,\nreport-versus-dataset guidance, waiting through `done=true`, provenance,\nexport, and billing follow-up. Hosted clients such as Manus receive the full\nresearch flow but no workspace-writing flow unless the user explicitly\nrequests that separate action. Starting a normal report or dataset never\ntriggers workspace-rule setup.\n\nNew users may have one non-divisible free run pass. It covers one exact `$5` report or dataset. It can be used from the Webhound UI, API, hosted MCP, or this stdio MCP package.\n\nAgents can read and update defaults with:\n\n- `webhound_onboarding`\n- `webhound_help`\n- `webhound_uninstall`\n- `webhound_get_defaults`\n- `webhound_set_defaults`\n\nIf a user explicitly requests workspace rules, the agent must show the complete\nproposed content and exact destination before writing. After approval, it reads\nthe file back and rejects empty or frontmatter-only content.\n\n## Tool Flow\n\nThe core lifecycle is detached and visible:\n\n1. Start work with `webhound_start_report` or `webhound_start_dataset`.\n2. Watch with `webhound_watch` or `webhound_wait`.\n3. While Webhound runs, keep doing useful independent work when it can improve\n   the result. If the calling agent finds a concrete source-backed note, save\n   it with `webhound_add_sidecar_notes`. This does not interrupt the current\n   Planner -> Executor -> Verifier cycle.\n4. Sidecar notes are shared state. Use `webhound_list_sidecar_notes` to inspect\n   what has already been saved and `webhound_update_sidecar_note` to correct,\n   restore, or dismiss a note without steering the session.\n5. Treat `done=true` as the authoritative finished signal.\n6. If a run is still healthy and your environment can sleep, schedule a\n   check-in, create a reminder, or run a one-time heartbeat, use\n   `runtime_estimate.recommended_next_check_seconds` and call\n   `webhound_watch` then. If it is still running, repeat using the updated\n   estimate. If only a few minutes remain, use `webhound_wait`.\n7. If a spend-bearing action returns `billing_required` or a running session\n   returns `credit_exhausted`, send the user to\n   `https://www.webhound.ai/billing` to add credits, add a card, or enable\n   auto-recharge. Ask them to ping you when done. After they reply, call\n   `webhound_account` to confirm billing is ready, then retry the original\n   start/add-budget/resume action.\n8. If `awaiting_input`, reply with `webhound_send_message` using\n   `reason=\"awaiting_input\"`; that resumes the session.\n9. Use `webhound_send_message` with `reason=\"user_guidance\"` only when the user\n   changes the objective, scope, constraints, or deliverable. Do not use\n   steering for ordinary source suggestions.\n10. Only when the user explicitly asks to reduce the remaining report scope or\n    finish with the research already gathered, call `webhound_set_budget`.\n    Read `budget_control.minimum_target_budget` from watch/session status when\n    they want to finish at the nearest safe boundary. Lowering the budget does\n    not bypass assembly: the revised budget becomes the stopping boundary, and\n    Webhound runs normal final assembly afterward. Never do this merely because\n    partial notes look sufficient or the run is taking time.\n11. When `done=true` and `output_ready=true`, call `webhound_get_session` for the complete canonical session in one response. If a terminal run has no output, treat its typed `EMPTY_OUTPUT` or `DATASET_ZERO_ROWS` alert as a failure rather than claiming success.\n12. `webhound_get_evidence_pack` returns that same complete session plus evidence-follow-up guidance. Use it when the answer depends on the research trail.\n13. Use `webhound_get_output` for the complete polished result or `webhound_export_session` when the user needs a file. Use the claims and sources tools when you need one focused surface.\n14. For datasets, inspect rows/schema plus sources; export CSV/JSON when the\n    user needs to use the data elsewhere.\n15. After reading/exporting the final output and evidence pack, use your own judgment to surface\n    a few focused threads the user could pull next. Ground them in concrete\n    things the session uncovered: unexplained entities, source gaps, paper\n    trails, contested claims, missing rows, or narrow comparisons. These should\n    be optional deeper follow-ups, not generic \"research more\" suggestions. If\n    several are independent, they can be started in parallel as separate\n    Webhound runs.\n16. If the user asks for a shareable link, use `webhound_get_shareable_link`.\n    It makes that report or dataset public to anyone with the link and returns\n    the right share URL: `/document/:id` for reports, `/dataset/:id` for\n    datasets. It is not Explore publishing and does not create a `/p/:slug`\n    publication.\n\nBudget controls depth. As a rule of thumb, `$1` buys about 15 minutes of\nresearch. A healthy run may keep searching, reading, writing, and verifying\nthrough several waits while it uses the budget. More budget means more room for\nresearch before final assembly; it is not a signal for the calling agent to\nhurry the run. Do not send finalize/wrap-up guidance or stop the session just\nbecause partial working notes look usable.\n\n### Dataset schema forms\n\nOmit `schema` to let Webhound infer a concise schema. When fields matter, use\nexactly one of these forms.\n\nNative Webhound schema:\n\n```json\n{\n  \"entity_name\": \"Company\",\n  \"attributes\": [\n    { \"name\": \"company_name\", \"type\": \"string\", \"is_primary\": true },\n    { \"name\": \"website\", \"type\": \"string\", \"standard_format\": \"url\" },\n    { \"name\": \"employee_count\", \"type\": \"number\" }\n  ]\n}\n```\n\nObject JSON Schema:\n\n```json\n{\n  \"type\": \"object\",\n  \"title\": \"Company\",\n  \"required\": [\"company_name\"],\n  \"properties\": {\n    \"company_name\": {\n      \"type\": \"string\",\n      \"description\": \"Official company name\",\n      \"x-webhound-primary\": true\n    },\n    \"website\": { \"type\": \"string\", \"format\": \"uri\" },\n    \"employee_count\": { \"type\": \"integer\" }\n  }\n}\n```\n\nNative schemas require at least one `is_primary: true` field. For JSON Schema,\n`x-webhound-primary: true` wins; otherwise the first required property, then\nthe first property, becomes the deterministic primary field. The start response\nechoes `normalized_schema` before the dataset begins.\n\n## Public Tools\n\n- `webhound_health`\n- `webhound_onboarding`\n- `webhound_help`\n- `webhound_uninstall`\n- `webhound_get_defaults`\n- `webhound_set_defaults`\n- `webhound_start_report`\n- `webhound_start_dataset`\n- `webhound_watch`\n- `webhound_wait`\n- `webhound_add_sidecar_notes`\n- `webhound_list_sidecar_notes`\n- `webhound_update_sidecar_note`\n- `webhound_send_message`\n- `webhound_stop`\n- `webhound_resume`\n- `webhound_add_budget`\n- `webhound_set_budget`\n- `webhound_get_output`\n- `webhound_export_session`\n- `webhound_get_evidence_pack`\n- `webhound_get_shareable_link`\n- `webhound_get_claims`\n- `webhound_get_sources`\n- `webhound_search_sessions`\n- `webhound_list_sessions`\n- `webhound_get_session`\n- `webhound_upload_file`\n- `webhound_account`\n- `webhound_diagnose`\n\nSupported upload formats are CSV, XLSX, PDF, DOCX, TXT, Markdown, and VTT.\nConvert legacy XLS/DOC files to XLSX/DOCX before uploading. MIME type, filename\nextension, and recognizable file bytes are checked before the upload reaches\nWebhound.\n\n## Completion And Diagnostics\n\n`webhound_watch` returns:\n\n- `done`: terminal status\n- `output_ready`: an artifact exists; wait for `done=true` before treating it as final\n- `completion_reason`: `budget_complete`, `natural_complete`, `awaiting_input`, `user_stopped`, `credit_exhausted`, `failed`, or `stuck_or_empty`\n- `alerts`: structured issues with next actions\n- `budget_control`: whether a report budget can be reduced, current spend and\n  budget, and the nearest safe lower target\n- `next_research_instruction`: guidance for the calling agent to derive focused\n  next investigations from the final output and underlying evidence pack\n\nDo not present a run as successful if `alerts` contains an error such as `empty_output`, `dataset_zero_rows`, or `credit_exhausted`. For `credit_exhausted`, use the returned `billing_url` and `user_message_template`; do not leave the user with a raw error.\n\nIf `webhound_wait` returns `still_running=true`, that is normal. Use the\nreturned runtime estimate to schedule the next check-in when the agent\nenvironment supports timers/reminders/automations, then call `webhound_watch`\nat that time. Use `webhound_add_sidecar_notes` for source-backed notes found by\nthe calling agent. Use `webhound_send_message(reason=\"awaiting_input\")` for\ncheckpoint replies and `webhound_send_message(reason=\"user_guidance\")` for\nreal user intent changes, not for normal elapsed time or source suggestions.\nUse `webhound_stop` only when the user explicitly asks to stop, pause, or\ncancel the run.\n\n## CLI\n\n```bash\nwebhound-mcp --help\nwebhound-mcp --version\nwebhound-mcp --self-test\n```\n\n`--self-test` checks that the package loads and that the launch tool list is present. Use `webhound_health` from an MCP client to verify live auth and account state.\n\n## Local Development\n\n```bash\ngit clone https://github.com/WebhoundAI/webhound-mcp.git\ncd webhound-mcp\nnpm install\nWEBHOUND_KEY=wh_... WEBHOUND_API_BASE=http://localhost:5000/api/v2 node bin/server.mjs\n```\n\nRun the package self-test without credentials:\n\n```bash\nnpm run self-test\nnpm test\nnpm run release:check\n```\n\nBefore publishing, compare this checkout with the canonical `webhound-server/mcp`\nruntime:\n\n```bash\nnpm run parity:compare -- /absolute/path/to/webhound-server/mcp\n```\n\n## License\n\nMIT",
  "bytes": 18529,
  "sha": "fb68470d47bc840a89e819b2f1f1c584458b545637daba838058ab1c292e0fd7",
  "repo_slug": "webhoundai/webhound-mcp",
  "fonte": "npm",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_webhound_webhound_ef52ad5a/readme"
}