Skip to main content

External AI Clients

Hunch can expose one website's grounded knowledge and normalized actions to external AI clients through a tenant-scoped MCP server.

This lets a connected client such as ChatGPT or Claude use the same Hunch capability layer that powers the website widget, channels, and handoff system.

How it works​

For each website:

  1. Hunch exposes a website-scoped MCP endpoint.
  2. A remote AI client connects through the Hunch OAuth install flow.
  3. Hunch exposes grounded reads, normalized site actions, and approved resources for that website.
  4. Every request is checked against plan entitlements, capability policies, rate limits, and billing rules.
  5. Every tool call writes through the same audit model used by the rest of Hunch.

What is exposed​

The external AI client can access:

  • grounded site reads such as site.ask and site.search
  • normalized site-derived actions such as site.action.*
  • multi-turn action follow-up tools such as action.reply, action.confirm, and action.cancel
  • handoff export when a human should take over

Hunch does not expose raw DOM-discovered tools one-to-one.

Site-discovered actions are normalized first and then filtered through policy controls before they become externally callable.

Dashboard controls​

Each website has an MCP tab that shows:

  • the endpoint URL
  • the authorization server metadata URL
  • the protected resource metadata URL
  • supported scopes
  • current installations
  • usage and credit spend
  • capability policies

Use the Capability Policies table to decide:

  • whether a normalized capability is exposed externally at all
  • whether an eligible public-site capability may run through public browser execution

Scopes​

Hunch currently supports these scopes:

  • mcp:read for reading resources and grounded site context
  • mcp:tools for calling Hunch tools
  • mcp:live for claimed live browser/session bridge access

mcp:live is the highest-risk scope and should be granted only when you need it.

Plan limits​

Current Hunch MCP entitlements are:

Free​

  • external MCP access disabled

Starter​

  • external MCP access enabled
  • up to 2 active external installations per website
  • up to 90 requests per minute per connection
  • up to 10 operations in one request batch
  • no live browser/session scope

Professional​

  • external MCP access enabled
  • up to 10 active external installations per website
  • up to 240 requests per minute per connection
  • up to 25 operations in one request batch
  • live browser/session scope available

Billing behavior​

External MCP usage is metered through the same Hunch credit ledger.

Successful billable MCP operations consume credits. Failed billable MCP operations are refunded.

In practice, that includes successful calls such as:

  • site.ask
  • site.search
  • site.action.*
  • action.reply
  • action.confirm
  • action.export_handoff
  • bridge.live.run

See also:

Safety model​

Hunch is strict about how external AI clients interact with your website:

  • website embed API keys are never used as MCP credentials
  • external clients connect through a separate OAuth installation flow
  • raw DOM click tools are not exposed directly
  • only normalized and policy-approved capabilities are callable
  • live browser/session actions require explicit visitor consent through a claim flow
  • installations can be revoked per website at any time

Live browser/session bridge​

If your plan and installation allow mcp:live, Hunch can expose a claimed live-session bridge.

Important constraints:

  • a real visitor must explicitly connect their current widget session
  • the external AI client must have been granted mcp:live
  • only allowlisted live tools are available
  • the bridge expires and can be revoked

Use live scope only when you truly need an external client to work against a real in-browser session.

  1. Start with one website.
  2. Expose only low-risk, high-value capabilities.
  3. Connect one external AI client.
  4. Validate grounded reads and one or two multi-turn actions.
  5. Review audit logs, usage, and credit spend.
  6. Add live scope only if there is a real need for claimed browser-session workflows.