Skip to main content

Live Bridge

The live bridge connects an external MCP client (ChatGPT, Claude, or a terminal tool) to a visitor's real browser session on your website. This lets the AI agent perform actions using the visitor's actual cookies, cart, and login state.

How it works​

  1. A visitor opens the Hunch widget on your site. The widget calls POST /bridge/live/init to create a bridge.
  2. Hunch returns a claim code (e.g., HUNCH-K7M3XPQR) and a bridge token.
  3. The claim code is shared with the workspace operator (shown in the widget or dashboard).
  4. An MCP client calls bridge.live.claim with the claim code to connect to the visitor's session.
  5. The MCP client can now run tools in the visitor's browser via bridge.live.run.
  6. Commands are queued by Hunch, picked up by the widget on its next heartbeat (every 5 seconds), executed locally, and results posted back.

Available MCP tools​

ToolDescription
bridge.live.claimClaim a bridge using a claim code
bridge.live.list_toolsList available tools in the visitor's browser session
bridge.live.snapshotGet the current page state (URL, title, text preview)
bridge.live.runExecute a tool in the visitor's browser
bridge.live.releaseRelease the bridge and end the session

Security​

  • Bridge tokens and claim codes are hashed before storage. Hunch never stores plaintext credentials.
  • Claim codes expire after 10 minutes.
  • Bridges expire after 30 minutes of inactivity. Heartbeats from the widget extend the TTL.
  • Only workspace users with sessions:manage or websites:manage permissions can claim bridges.
  • Individual tool executions can require operator approval via playbook rules.

When to use the live bridge​

  • Authenticated purchase flows: The visitor is logged in and has items in their cart. The AI agent needs to help them complete checkout.
  • Multi-step workflows: Flows that require page navigation, form filling across multiple pages, or state that persists across interactions.
  • Any action that requires the visitor's cookies or login state.

When NOT to use the live bridge​

  • Simple one-shot form submissions (contact forms, quote requests): Use browser_public mode instead.
  • Read-only questions: Use site.ask or site.search.
  • When no visitor is present: The live bridge requires an active widget session.

Example flow​

> bridge.live.claim({claim_code: "HUNCH-K7M3XPQR"})
✓ Bridge claimed · visitor on acme-store.com/products

> bridge.live.run({bridge_id: "blv_a8f2", tool_name: "add_to_cart", args: {product: "summer-dress", size: "M"}})
✓ Added to cart in visitor's browser

> bridge.live.run({bridge_id: "blv_a8f2", tool_name: "begin_checkout"})
✓ Checkout opened in visitor's browser

> bridge.live.release({bridge_id: "blv_a8f2"})
✓ Bridge released