Headless Flows

Let agents guide users through Doow signup and onboarding while sensitive actions stay in the browser.

2 min readUpdated 2026-09-21

Headless flows let an MCP agent coordinate Doow signup and onboarding while keeping sensitive operations (OAuth, identity verification, payment) in secure browser handoffs. The agent never sees passwords, OAuth tokens, or provider secrets.

How it works

The agent directs the flow by calling MCP tools, while the user handles identity and consent steps in their browser. The agent polls for status changes and guides the user to completion.

Tool summary

Flow	Endpoint	Tools	Auth
Signup	`/mcp/signup`	`signup_begin`, `signup_status`, `signup_save_profile`, `signup_open_handoff`, `signup_join_request`, `signup_claim_tokens`	Flow capability (`hs_cap_*`)
Onboarding	`/mcp/onboarding`	`onboarding_status`, `onboarding_next_step`, `onboarding_start_connection`, `onboarding_connection_status`, `onboarding_workspace_draft`, `onboarding_kyc_status`, `onboarding_kyc_requirements`, `onboarding_start_kyc`, `onboarding_stage_advance`, `onboarding_complete`, `onboarding_plan_status`, `onboarding_plan_options`, `onboarding_start_plan_selection`, `onboarding_contact_sales`	MCP OAuth (`mcp:read`/`mcp:write`)

The signup flow uses a flow capability token returned by signup_begin, while the onboarding flow uses standard MCP OAuth tokens or API keys.

Agent-directed journey

A complete agent-directed journey looks like:

Signup — Agent calls signup_begin, user completes OAuth and profile in browser, agent polls status
Token claim — Agent calls signup_claim_tokens to get MCP tokens for onboarding
Onboarding — Agent guides through integrations (IdP, expense, HRIS), workspace setup, and KYC
Complete — Agent calls onboarding_complete when required stages are done

Authentication

Signup and onboarding use different authentication models:

Flow	First call	Subsequent calls
Signup	Unauthenticated	`Authorization: Flow hs_cap_...`
Onboarding	MCP OAuth	`Authorization: Bearer <jwt>`

After signup completes, calling signup_claim_tokens returns MCP tokens that authenticate onboarding requests.

Browser handoffs

Both flows use browser handoffs for sensitive operations. The agent opens the URL directly, and the browser client handles any token exchange internally.

Signup returns handoff_url

A direct URL the agent opens for the user:
text
```
https://app.doow.co/signup#headless_handoff=hs_handoff_...
```
Onboarding returns handoff_ref

A reference the agent uses to construct the browser URL:
text
```
https://app.doow.co/onboarding#headless_handoff=hs_onboarding_...
```

The browser client performs any necessary token exchange internally.

Polling

Agents must poll status during browser operations:

Flow	Tool	Interval
Signup	`signup_status`	Every 2-3 seconds
Onboarding	`onboarding_connection_status`	Every 2-3 seconds

Stop polling when you reach a terminal state (COMPLETED, FAILED, EXPIRED) or when the connection succeeds.

Was this page helpful?