Onboarding tools
The public onboarding_* tools an AI agent uses to sign a new brand up for VYG.
A person without a VYG account can ask their AI agent to sign them up. The agent connects to
https://api.vyg.app/mcp/start, which serves only the onboarding_* tools below and needs no sign-in or
API key. The signup steps are: start, set a password, connect the store platform, verify the email code,
then provision the account. Setup commands for each agent are in
Connect from your agent.
Existing accounts connect to https://api.vyg.app/mcp with OAuth or an API key and do not see these tools.
Served on POST https://api.vyg.app/mcp/start. Auth: none. No account, OAuth sign-in or API key is needed; calls are rate limited. Every tool except onboarding_start (and onboarding_status without a token) also needs the resume_token.
resume_token lifecycle
onboarding_startreturns theresume_token. Every later onboarding tool requires it.- It is valid for 24 hours. After that, call
onboarding_startagain with the same email. - It is purpose-scoped: it is signed only for MCP onboarding and is not accepted as a VYG sign-in or API key.
- It is bound to a single signup lead (
lead_id). It cannot read or change any other lead. - After
onboarding_provision_account, stop using it. Reconnect tohttps://api.vyg.app/mcpwith the returnedmcp_api_keyas anAuthorization: Bearerheader. The key is returned once.
onboarding_start
Start a LiveRecover signup for a new brand. Creates a signup lead and returns lead_id, a resume_token (valid 24 hours, required by every later onboarding tool) and next_step. If the email already has an account, returns is_existing_email: true and next_step "login" without creating a lead.
Auth: none
| Input | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Email of the person signing up |
company_name | string | Yes | Brand or company name |
website_url | string | Yes | Brand website or store URL; ask the user for it. Normalized to https:// |
industry | string | No | Industry as free text or one of: auto-dealers, auto-service, b2b, courses-and-coaching, ecommerce, financial-services, government, healthcare, home-services, hotels, insurance, legal, military, political, restaurants, tours-and-experiences |
platform | string | No | Store or commerce platform, for example shopify, woocommerce, bigcommerce, or other |
first_name | string | No | |
last_name | string | No | |
support_phone | string | No | Customer support phone number |
agent | "claude" | "chatgpt" | "grok" | "codex" | "claude-code" | "other" | No | The AI agent running this signup; defaults to other |
source_ref | string | No | Referral or campaign reference to attribute the signup to |
Returns: lead_id, resume_token, is_existing_email, next_step, summary
onboarding_status
Check where a LiveRecover signup stands. Pass the resume_token from onboarding_start. Returns completed steps, next_step, the email verification state and a short summary. Without a token it explains how to start.
Auth: none + resume_token
| Input | Type | Required | Description |
|---|---|---|---|
resume_token | string | No | resume_token returned by onboarding_start |
Returns: status, lead_id, brand_id, completed_steps, next_step, platform, verification, summary
onboarding_set_password
Set the password for a LiveRecover signup. Pass the resume_token from onboarding_start and the password the user chose. Password rule: Must contain at least one number and be at least 6 characters or longer. The password is never returned.
Auth: none + resume_token
| Input | Type | Required | Description |
|---|---|---|---|
resume_token | string | Yes | resume_token returned by onboarding_start |
password | string | Yes | Password the user chose. Must contain at least one number and be at least 6 characters or longer |
Returns: success, lead_id, next_step, summary
onboarding_connect_platform
Connect the brand's store platform during a LiveRecover signup, or skip it. Platforms: shopify (Shopify; pass store_url), woocommerce (WooCommerce; pass site_url), custom (Custom site (pixel / CDP only); pass website_url). Pass either platform with its URL field, or skip: true. For shopify the result has an install_url: show it to the user, who opens it to install the app, then check onboarding_status. woocommerce and custom record the URL and complete the step.
Auth: none + resume_token
| Input | Type | Required | Description |
|---|---|---|---|
resume_token | string | Yes | resume_token returned by onboarding_start |
platform | "shopify" | "woocommerce" | "custom" | No | Store platform |
store_url | string | No | shopify: the store domain, for example mystore.myshopify.com |
site_url | string | No | woocommerce: the WordPress site URL |
website_url | string | No | custom: the website that will run the VYG pixel |
skip | boolean | No | true to skip connecting a platform for now |
Returns: success, lead_id, platform, install_url, next_step, summary
onboarding_send_verification
Email a 6-digit verification code to the signup email. Pass the resume_token from onboarding_start. The code expires in 15 minutes; up to 3 emails per address per hour. Then ask the user for the code and call onboarding_verify_code.
Auth: none + resume_token
| Input | Type | Required | Description |
|---|---|---|---|
resume_token | string | Yes | resume_token returned by onboarding_start |
Returns: sent, email_verified, message_id, expires_at, next_step, summary
onboarding_verify_code
Check the 6-digit code the user received by email. Pass the resume_token and the code. After 5 wrong attempts the code is invalidated and a new one must be requested with onboarding_send_verification.
Auth: none + resume_token
| Input | Type | Required | Description |
|---|---|---|---|
resume_token | string | Yes | resume_token returned by onboarding_start |
code | string | Yes | The 6-digit code from the verification email |
Returns: email_verified, email_verified_at, next_step, summary
onboarding_provision_account
Create the LiveRecover account once the email is verified and a password is set. Pass the resume_token from onboarding_start, and the 6-digit code if onboarding_verify_code was not called yet. Creates the brand, the default abandoned-checkout workflow and free CDP access, and returns an API key once as mcp_api_key for https://api.vyg.app/mcp. Show the key to the user and tell them to store it; it cannot be retrieved again. Calling again returns the existing account without a key.
Auth: none + resume_token
| Input | Type | Required | Description |
|---|---|---|---|
resume_token | string | Yes | resume_token returned by onboarding_start |
code | string | No | The 6-digit email code, only if onboarding_verify_code was not called yet |
Returns: success, already_provisioned, brand_id, login_url, mcp_url, mcp_api_key, mcp_api_key_prefix, mcp_api_key_scopes, next_step, summary