webhound-mcp

Run Webhound from any MCP-speaking agent. Webhound creates private, budgeted reports and datasets, runs as the agent's research sidecar, accepts non-interrupting source-backed notes, diagnoses failures, and returns cited outputs with sources and claim traces.

This package is the local stdio transport. Webhound also supports hosted MCP at:

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

Install

Create a Webhound API key, then add the stdio server to your agent:

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

Claude hosted connector:

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

Paste the URL into Claude's custom connector flow. The hosted server exposes OAuth discovery, authorize, and token endpoints for that connect flow.

Manus or generic hosted MCP:

Server URL: https://api.webhound.ai/api/v2/mcp
Auth type: HTTP header
Header name: Authorization
Header value: Bearer wh_...

If the MCP app has a dedicated bearer-token field that automatically adds
`Bearer`, paste only `wh_...` in that token field.

Claude Code:

claude mcp add --transport http webhound https://api.webhound.ai/api/v2/mcp --header "Authorization: Bearer wh_..."

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

Codex:

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

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

Cursor and Claude Desktop use the JSON shape above.

After saving local stdio config, restart the agent session or open a new one if the Webhound tools do not appear. Many clients load MCP servers only when a session starts.

VS Code:

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

Use the same stdio server shape for Windsurf, Cline, and Roo Code. Windsurf commonly stores it in ~/.codeium/windsurf/mcp_config.json; Roo Code supports global MCP settings or project-level .roo/mcp.json.

Defaults

Recommended setup defaults:

• budget: $5
• product: report
• free run: enabled when available

Onboarding can also help the calling agent save a local budget policy. The recommended lightweight policy is $2 for quick scouting, $5 for normal cited research, and $10 for deeper or decision-driving work. The agent should ask where those rules should apply before writing anything: the current project, another accessible project, all relevant accessible projects with per-project rules, or global agent rules. It should not silently write Webhound rules into a temporary onboarding chat directory. Webhound itself still stores a single account default budget.

New 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.

Agents can read and update defaults with:

• webhound_onboarding
• webhound_help
• webhound_uninstall
• webhound_get_defaults
• webhound_set_defaults

During onboarding, agents should mention webhound_help for future questions about Webhound and webhound_uninstall if the user later wants to remove the MCP setup and local Webhound rules.

Onboarding should ask one setup-timing question before the first run:

• Set up this workspace first: ask where rules should apply, inspect only the approved local context, propose Webhound usage rules plus a short budget policy, save only approved rules, then start the first report or dataset.
• Jump right in: ask what the user wants researched or extracted, start the first report or dataset, then offer the same local setup pass while Webhound works in the background.

In both branches, onboarding should still walk the user all the way through starting the first Webhound session. After a first session starts, do not fall into a visible polling loop before handling the setup choice or scheduling a later check-in.

Tool Flow

The core lifecycle is detached and visible:

1. Start work with webhound_start_report or webhound_start_dataset.
2. Watch with webhound_watch or webhound_wait.
3. While Webhound runs, keep doing useful independent work when it can improve the result. If the calling agent finds a concrete source-backed note, save it with webhound_add_sidecar_notes. This does not interrupt the current Planner -> Executor -> Verifier cycle.
4. Sidecar notes are shared state. Use webhound_list_sidecar_notes to inspect what has already been saved and webhound_update_sidecar_note to correct, restore, or dismiss a note without steering the session.
5. Treat done=true as the authoritative finished signal.
6. If a run is still healthy and your environment can sleep, schedule a check-in, create a reminder, or run a one-time heartbeat, use runtime_estimate.recommended_next_check_seconds and call webhound_watch then. If it is still running, repeat using the updated estimate. If only a few minutes remain, use webhound_wait.
7. If awaiting_input, reply with webhound_send_message using reason="awaiting_input"; that resumes the session.
8. Use webhound_send_message with reason="user_guidance" only when the user changes the objective, scope, constraints, or deliverable. Do not use steering for ordinary source suggestions.
9. When done=true and output_ready=true, read with webhound_get_output or download an artifact with webhound_export_session.
10. Use the full evidence pack before giving serious answers: inspect provenance with webhound_get_claims, inspect source coverage with webhound_get_sources, and read working docs when depth matters. For reports, use webhound_export_session(select="all", format="md") or webhound_get_output(select="working") for follow-up analysis, story pitches, critique, diligence, or investigations. The final output is the synthesis entry point, not the whole information payload.
11. For datasets, inspect rows/schema plus sources; export CSV/JSON when the user needs to use the data elsewhere.
12. After reading/exporting the final output and evidence pack, use your own judgment to surface a few focused threads the user could pull next. Ground them in concrete things the session uncovered: unexplained entities, source gaps, paper trails, contested claims, missing rows, or narrow comparisons. These should be optional deeper follow-ups, not generic "research more" suggestions. If several are independent, they can be started in parallel as separate Webhound runs.

Budget controls depth. As a rule of thumb, $1 buys about 15 minutes of research. A healthy run may keep searching, reading, writing, and verifying through several waits while it uses the budget. More budget means more room for research before final assembly; it is not a signal for the calling agent to hurry the run. Do not send finalize/wrap-up guidance or stop the session just because partial working notes look usable.

Public Tools

• 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_get_output
• webhound_export_session
• webhound_get_claims
• webhound_get_sources
• webhound_search_sessions
• webhound_list_sessions
• webhound_get_session
• webhound_upload_file
• webhound_account
• webhound_diagnose

Completion And Diagnostics

webhound_watch returns:

• done: terminal status
• output_ready: an artifact exists; wait for done=true before treating it as final
• completion_reason: budget_complete, natural_complete, awaiting_input, user_stopped, credit_exhausted, failed, or stuck_or_empty
• alerts: structured issues with next actions
• next_research_instruction: guidance for the calling agent to derive focused next investigations from the final output and underlying evidence pack

Do not present a run as successful if alerts contains an error such as empty_output, dataset_zero_rows, or credit_exhausted.

If webhound_wait returns still_running=true, that is normal. Use the returned runtime estimate to schedule the next check-in when the agent environment supports timers/reminders/automations, then call webhound_watch at that time. Use webhound_add_sidecar_notes for source-backed notes found by the calling agent. Use webhound_send_message(reason="awaiting_input") for checkpoint replies and webhound_send_message(reason="user_guidance") for real user intent changes, not for normal elapsed time or source suggestions. Use webhound_stop only when the user explicitly asks to stop, pause, or cancel the run.

CLI

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

--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.

Local Development

cd webhound-server/mcp
npm install
WEBHOUND_KEY=wh_... WEBHOUND_API_BASE=http://localhost:5000/api/v2 node bin/server.mjs

No npm publish is performed by this repo change. Publish only after the production server and docs are approved.