VYG Docs
Tools

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_start returns the resume_token. Every later onboarding tool requires it.
  • It is valid for 24 hours. After that, call onboarding_start again 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 to https://api.vyg.app/mcp with the returned mcp_api_key as an Authorization: Bearer header. 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

InputTypeRequiredDescription
emailstringYesEmail of the person signing up
company_namestringYesBrand or company name
website_urlstringYesBrand website or store URL; ask the user for it. Normalized to https://
industrystringNoIndustry 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
platformstringNoStore or commerce platform, for example shopify, woocommerce, bigcommerce, or other
first_namestringNo
last_namestringNo
support_phonestringNoCustomer support phone number
agent"claude" | "chatgpt" | "grok" | "codex" | "claude-code" | "other"NoThe AI agent running this signup; defaults to other
source_refstringNoReferral 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

InputTypeRequiredDescription
resume_tokenstringNoresume_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

InputTypeRequiredDescription
resume_tokenstringYesresume_token returned by onboarding_start
passwordstringYesPassword 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

InputTypeRequiredDescription
resume_tokenstringYesresume_token returned by onboarding_start
platform"shopify" | "woocommerce" | "custom"NoStore platform
store_urlstringNoshopify: the store domain, for example mystore.myshopify.com
site_urlstringNowoocommerce: the WordPress site URL
website_urlstringNocustom: the website that will run the VYG pixel
skipbooleanNotrue 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

InputTypeRequiredDescription
resume_tokenstringYesresume_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

InputTypeRequiredDescription
resume_tokenstringYesresume_token returned by onboarding_start
codestringYesThe 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

InputTypeRequiredDescription
resume_tokenstringYesresume_token returned by onboarding_start
codestringNoThe 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

On this page