Headless Onboarding

Initialize MCP session

Every MCP session requires initialization. The server returns a session ID for subsequent requests.

curl -s -i https://mcp.doow.co/mcp/onboarding \-H "Authorization: Bearer <mcp_token>" \-H "Accept: application/json, text/event-stream" \-H "Content-Type: application/json" \-d '{  "jsonrpc": "2.0",  "id": 1,  "method": "initialize",  "params": {    "protocolVersion": "2025-03-26",    "capabilities": {},    "clientInfo": {"name": "my-agent", "version": "1.0"}  }}'

Response headers:

Mcp-Session-Id: 3ab45ea9-367e-4e6c-86ee-fc8984ccaa4d

Save the Mcp-Session-Id header. All subsequent calls need it.

Check onboarding status

{"jsonrpc": "2.0","id": 2,"method": "tools/call","params": {  "name": "onboarding_status",  "arguments": {}}}

Include headers:

Authorization: Bearer <mcp_token>Mcp-Session-Id: <session_id>Accept: application/json, text/event-stream

Response:

{"stages": ["LANDING"],"business_name": "Acme Inc","missing_steps": ["IdP", "ACCOUNTING", "BANKING", "HRIS", "WORKSPACE"],"next_step": "IdP","browser_required": true}

The response also carries the other workspace fields once they are set: website_url, trade_name (the name the business trades under, which can differ from business_name), country_of_incorporation, default_spending_currency, financial_year_start, and inactivity_period (a number of days). A field with no value is left out of the response rather than returned as null.

Connect providers

For each provider, the agent starts a connection and the user completes OAuth in the browser.

Start connection:

{"jsonrpc": "2.0","id": 3,"method": "tools/call","params": {  "name": "onboarding_start_connection",  "arguments": {    "provider": "google"  }}}

Response:

{"provider": "google","state": "PENDING","browser_required": true,"handoff_ref": "hs_onboarding_abc123","expires_at": "2026-09-21T14:30:00Z"}

Open browser for user:

open "https://app.doow.co/onboarding#headless_handoff=hs_onboarding_abc123"

What the browser does with handoff_ref

The browser client reads headless_handoff from the URL fragment and spends the token once:

POST /v1/auth/headless/onboarding/handoff/exchangeContent-Type: application/json{ "handoff_token": "hs_onboarding_abc123" }

Response:

{"provider": "google","expires_at": "2026-09-21T14:30:00Z"}

The exchange returns only provider and expires_at: never a browser URL, organization ID, or member ID. The token is single-use and short-lived:

• handoff_ref is valid for 30 minutes from issue.
• A successful exchange moves the handoff from ISSUED to SUCCEEDED. Exchanging the same token again returns 401.
• If the user abandons the browser step, call onboarding_start_connection again to issue a fresh handoff_ref.

Poll connection status every 2-3 seconds while the user is in the browser:

{"jsonrpc": "2.0","id": 4,"method": "tools/call","params": {  "name": "onboarding_connection_status",  "arguments": {    "provider": "google"  }}}

Response:

{"providers": [  {    "provider": "google",    "state": "CONFIRMED"  }]}

Configure workspace

Save company metadata with onboarding_workspace_draft:

{"jsonrpc": "2.0","id": 5,"method": "tools/call","params": {  "name": "onboarding_workspace_draft",  "arguments": {    "business_name": "Acme Inc",    "website_url": "https://acme.com",    "country_of_incorporation": "US",    "default_spending_currency": "USD",    "financial_year_start": "January"  }}}

Response:

{"business_name": "Acme Inc","website_url": "https://acme.com","country_of_incorporation": "US","default_spending_currency": "USD","financial_year_start": "January","stages": ["LANDING"]}

The response echoes the stored metadata and adds stages, the same array onboarding_status returns. Fields you do not set stay omitted, which is why trade_name and inactivity_period do not appear above.

Advance stages

After each step completes, advance the stage:

{"jsonrpc": "2.0","id": 6,"method": "tools/call","params": {  "name": "onboarding_stage_advance",  "arguments": {    "stage": "IdP"  }}}

Valid stages: IdP, ACCOUNTING, BANKING, HRIS, WORKSPACE. Send exactly one stage per call, because the server rejects a request that carries more or fewer.

The call only succeeds when the organization already has an active integration whose onboarding_step matches the stage you are advancing, so connect the provider and let the browser step finish first. The server rejects COMPLETED outright, since it sets that stage itself once every requirement is met. A call made before any connection exists fails as well, and the client sees the generic SERVICE_UNAVAILABLE rather than a code that names the missing connection.

Response:

{"stages": ["LANDING", "IdP"]}

Complete KYC

Check KYC requirements and status:

{"jsonrpc": "2.0","id": 7,"method": "tools/call","params": {  "name": "onboarding_kyc_status",  "arguments": {}}}

Response:

{"status": "NOT_STARTED", "has_kyc": false}

Start KYC:

{"jsonrpc": "2.0","id": 8,"method": "tools/call","params": {  "name": "onboarding_start_kyc",  "arguments": {}}}

Response:

{"kyc_url": "https://app.doow.co/onboarding/kyc","browser_required": true,"status": "NOT_STARTED"}

KYC returns a direct kyc_url (no exchange needed), so open it for the user and poll onboarding_kyc_status until PENDING or APPROVED.

Complete onboarding

Read onboarding_status and onboarding_kyc_status, check them against the requirements below, then call:

{"jsonrpc": "2.0","id": 9,"method": "tools/call","params": {  "name": "onboarding_complete",  "arguments": {}}}

onboarding_complete requires:

• stages to include IdP, WORKSPACE, and at least one of ACCOUNTING or BANKING
• onboarding_kyc_status to report has_kyc: true with status PENDING or APPROVED, unless the user reached the browser-skip path below

Response:

{"status": "COMPLETED","stages": ["LANDING", "IdP", "ACCOUNTING", "WORKSPACE", "COMPLETED"]}

A successful call returns only status and stages. It carries no completion_source and no kyc_verified field.

Do not gate on missing_steps: it is computed over every possible stage, so it reports HRIS even though HRIS is optional and onboarding_complete does not require it.

Browser skip is the one exception. When the organization's stages already include COMPLETED and KYC status is NOT_STARTED, the user finished onboarding in the browser, and the call returns the skip details alongside the same status:

{"status": "COMPLETED","completion_source": "BROWSER_SKIP","kyc_status": "NOT_STARTED","kyc_verified": false,"stages": ["LANDING", "IdP", "ACCOUNTING", "WORKSPACE", "COMPLETED"]}

Any other KYC state (REJECTED, REQUIRES_ACTION, or UNKNOWN) fails, as does a missing KYC record when the stages do not already include COMPLETED. An agent that starts KYC and then abandons it leaves the flow in a state that onboarding_complete rejects.

Plan selection is not part of onboarding_complete, so drive straight into it once the call succeeds (see Plan selection).

IdP (Identity Provider)

Accounting

Banking

HRIS