Skip to main content

​
End-to-end message flow

User -> Widget                 : natural-language request
Widget -> Warpy API            : WS /widget/session + chat.request
Warpy API -> Widget            : chat.response with tool calls or final answer
Widget -> Customer app or API  : execute browser-side tool calls or token exchange
Customer app or API -> Widget  : tool results or MCP auth headers
Warpy API -> MCP server        : live MCP list_tools / call_tool when selected
MCP server -> Warpy API        : live MCP tool metadata or result
Widget -> Warpy API            : same websocket + chat.request with tool results
Warpy API -> Widget            : chat.response with final response and suggestions
Widget -> User                 : answer
Each widget run uses one websocket connection to Warpy for the full tool loop, then closes it when the run completes.

​
The most important runtime detail

Browser backend calls, frontend tool calls, and screen-autopilot actions still run from the embedded widget. Live MCP tool discovery and MCP tool calls run server-side inside Warpy after the widget supplies short-lived per-user MCP headers.

​
Tool routing logic

User request
  -> Warpy orchestration
      -> question needs docs              -> Knowledge base search
      -> approved backend action exists   -> Backend tool call
      -> approved frontend action exists  -> Frontend tool call
      -> no tool fits or page help needed -> Screen autopilot

Tool result or retrieved knowledge
  -> answer draft
  -> final answer

​
What each layer is responsible for

LayerResponsibility
Widgetcapture the message, fetch config, execute browser-side tool calls, exchange user session for short-lived MCP headers, return results
Warpy APIorchestrate reasoning, choose tools, enforce widget auth, execute live MCP calls, produce the final response
Customer appreceive backend requests, expose frontend handlers, or provide live page context

​
Backend tool execution path

When Warpy returns a backend tool call, the widget:
  1. reads configured auth settings and custom browser-storage headers
  2. substitutes path parameters
  3. builds query string, body, headers, and credential mode
  4. shows a live inline activity card in the widget while the request runs
  5. sends the request to your selected base URL
  6. sends the result back to Warpy
If Send browser cookies with requests is enabled, the widget does not read a cookie key and does not synthesize an auth header. It sends the request with credentials: “include” so the browser attaches cookies normally. Explicit cookie-to-header mappings still only apply to custom headers that Warpy builds in JavaScript.

​
MCP execution path

When a live MCP connection is configured, Warpy can discover and call MCP tools without importing them into Features. For token_exchange connections, the widget:
  1. calls your token-exchange endpoint with the user’s normal signed-in browser session
  2. receives short-lived MCP headers for that user
  3. includes them on the websocket request as run-scoped mcpAuthBundles
Then Warpy:
  1. opens a live MCP client session server-side
  2. lists tools or calls the chosen MCP tool
  3. returns the result into the normal reasoning loop
If the MCP server rejects auth, Warpy returns a retryable MCP_AUTH_EXPIRED websocket error so the widget can refresh headers once and replay the same request.

​
Frontend tool execution path

When Warpy returns a manual frontend tool call, the widget:
  1. calls window.warpy(toolName, vars)
  2. shows the same inline activity card with a readable feature/tool label
  3. keeps the existing frontend warning banner visible while the handler runs
  4. waits for your app to finish the handler
  5. sends the result back to Warpy

​
Screen autopilot path

When screen autopilot is enabled, Warpy can:
  • inspect the page structure
  • find the right element
  • click, type, select, navigate, scroll, or run JavaScript
Use this when the best execution surface is the live interface itself.

​
Security and limits in the flow

  • Signed widget tokens are enforced on WS /widget/session when enabled.
  • Token refresh happens through the customer-owned endpoint you configure.
  • Per-user rate limits are checked before and after billable execution.
  • The widget hides when action availability or rate-limit state says it should.