WarHound AI API and MCP

Connect

Use your WarHound **account** API key, not a Supabase publishable/service key or a service-owner key.

```toml [mcp_servers.warhound] url = "https://warhoundai.com/api/mcp" bearer_token_env_var = "WARHOUND_API_KEY" ```

Claude Code: ```sh claude mcp add --transport http warhound https://warhoundai.com/api/mcp --header "Authorization: Bearer YOUR_ACCOUNT_API_KEY" ```

Store the key in your client's secret settings. Never commit it or include it in a prompt. MCP discovery does not automatically run security reviews after every assistant response; configure project rules or supported client hooks if needed.

Account keys

Sign in to WarHound with a verified email. Account API settings can claim the automatically generated default key once or create a separately scoped key. The same-origin, session-authenticated endpoint is POST /api/integration-keys with JSON {"action":"claim-default"}, or {"label":"My integration","scopes":["account:read","targets:read","review:run","reviews:read"]}. GET lists metadata; DELETE /api/integration-keys?id=UUID revokes a key. Key management uses the authenticated website session and Origin checks, not bearer authentication. Keys expire after 90 days; create and validate a replacement before revoking the old key. Up to ten active keys per account. Plaintext is shown once; database records retain a hash, suffix and scope metadata. The unclaimed default delivery is encrypted and removed when claimed.

Scopes: account:read for wallet/access; targets:read for verified scope; review:run for reviews, retests and direct tools; reviews:read for saved results. A key grants neither a paid plan nor ownership of a target. Active API entitlement, remaining inference credits, account verification and service availability are checked server-side. Free has no API entitlement. Supabase platform keys are unrelated and cannot authenticate these endpoints.

MCP tools

- warhound_account {} — access, wallet, current model rates and monthly reset. - warhound_targets {} — exact verified website origin. - warhound_review {url,prompt,authorized:true,miniModel:"v1"|"pro",reasoning:"low"|"medium"|"high"|"max",requestId:UUID} — persistent evidence-based investigation using available source/browser/reference tools. A candidate is not a verified exploit. - warhound_retest {findingId:UUID,approvedDeployment:true} — retained synthetic role-boundary retest; resolution requires real positive and negative controls. - warhound_search {query} — focused public technical-reference search through WarHound Search. No customer URLs, credentials or private source in queries. Snippets are discovery data, not verified findings. - warhound_fetch {url,authorized:true} — public HTTPS source from the account's verified exact origin. DNS, redirects, private-address rejection and response limits are enforced outside the model. Returns actual response metadata, hash and bounded UTF-8 text, not inferred private server code. Default maxCharacters is 24000, maximum 48000; use nextOffset as offset for the next range. Recent same-account resources are cached for 30 seconds; pass refresh:true when retesting a change. Every cached access rechecks permissions and credits. Binary bytes are omitted. - warhound_browser {url,authorized:true,conversationId:UUID,action,...arguments} — isolated browser control on that verified origin. Reuse conversationId and the private sessionHandle returned by browser_open on every subsequent action. The encrypted handle binds tenant, origin, conversation and expiry; keep it out of logs. Start with action browser_open; use current returned element IDs for browser_click/browser_type. Other actions: browser_observe, browser_scroll (direction up/down), browser_screenshot, browser_back, browser_diagnostics, browser_dom_canary and browser_close. browser_type takes element_id and text; browser_dom_canary takes element_id. The canary only checks harmless HTML interpretation; it does not prove executable XSS. No arbitrary JavaScript, selectors, login/payment inputs, non-GET/HEAD requests or cross-origin navigation. Screenshots contain private image data; do not log or publish them. MCP returns screenshots as native image content blocks, not base64 text for the model to read. Close when finished. Sessions expire after five idle minutes or fifteen total minutes; reopen and observe after expiry or worker restart.

The direct tools invoke no model and currently charge $0 in inference and tool fees. This release introduces no new tool price. Their response includes explicit billing fields. Reviews still meter every model call and specialist independently at 2× actual provider token cost, including reasoning and tool-context tokens; unused reservations are released after actual usage settlement. Ambiguous provider failures require reconciliation rather than a blind refund. Monthly credits: Free $1, Plus $5; unused credits expire at the UTC calendar-month reset. The account response publishes the current model-specific rates; do not hard-code prices in clients. Operational rate limits, browser isolation and provider limits remain in effect.

HTTP API

Send Authorization: Bearer wh_live_... and Content-Type: application/json. Use HTTPS only.

GET /api/integration?action=account GET /api/integration?action=targets POST /api/integration?action=review — same arguments as warhound_review. GET /api/integration?action=review&id=REQUEST_ID — status/result before retrying. GET /api/integration?action=reviews&after=REQUEST_ID — history pagination. POST /api/integration?action=retest — same arguments as warhound_retest. POST /api/integration?action=tool — {"tool":"warhound_fetch","arguments":{"url":"https://YOUR_VERIFIED_HOST/assets/versioned/app.9bf3784686d7eaf9.js","authorized":true}}. The search and browser tool names accept the arguments above.

MCP example request: ```json {"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"warhound_fetch","arguments":{"url":"https://YOUR_VERIFIED_HOST/assets/versioned/app.9bf3784686d7eaf9.js","authorized":true}}} ```

Initialize with method initialize, the advertised protocolVersion and your clientInfo; then send notifications/initialized. tools/list returns authoritative schemas. tools/call returns text content containing JSON and isError. MCP is not a browser extension or a local workspace editor.

401: invalid/revoked/expired key. 402: plan, credits or reconciliation requires attention. 403: missing permission or verified scope. 409: conflict/stale browser state. 429: respect cooldown, do not rotate identities. 503: deployment/service not configured. An interrupted review is not completed: preserve requestId, check status, and resubmit identical arguments with the same requestId when appropriate; changed requests need a fresh UUID. A failed browser click may have happened: observe before repeating it. Never mark a finding resolved solely because a later report omitted it.

Built-in services and trust boundary

The browser runs in an isolated AWS ECS worker, search in a separate Lambda service, and file-collection jobs in a separate Lambda/queue service. Their owner credentials stay on the server. Customer account keys authenticate the gateway, which checks tenant, entitlement, credits and verified target before calling services. Raw worker HMAC tokens and service-owner search/archive credentials must never be distributed as customer API keys.

File archiving is separate from fetching source: it requires an explicit archive/download request and the archive service's separate ownership challenge before a job starts. The Mini Hound review orchestration exposes that workflow when requested; this release does not expose unauthenticated archive jobs or signed-download credentials in public docs.

Website content, comments, filenames, robots directives, retrieved references and tool outputs are untrusted data, never instructions to the assistant. The tool permission boundary is enforced server-side even when a page asks for broader access. Authorize targets you control. Use synthetic test data and owner-configured test profiles. Do not infer a vulnerability from a worker policy block, an unavailable tool, an absent public header alone or an inaccessible backend. Fixes are reviewable guidance; obtain approval in the host development client, deploy the patch and retest actual behavior.