facesign.ai

FaceSign MCP Server for identity verification. CRITICAL: You MUST call set_api_key BEFORE calling any other tool (launch_session_ui, get_session, list_sessions). If the user has not provided their FaceSign API key, ask them for it first. Do NOT call launch_session_ui or any other tool until set_api_key has been called successfully. The flow is a linear directed graph of nodes: START -> conversation/verification steps -> END. IMPORTANT: Flows must be linear with NO loops or cycles — a node must NEVER navigate back to a previous node. All paths must move forward toward an END node. After the API key is set, read the facesign://catalog resource to see available avatars and languages. DEFAULT CONFIGURATION: Default avatar: June HR (ID: 65f9e3c9-d48b-4118-b73a-4ae2e3cbb8f0). Use this avatar when the user does not specify a preference. Use launch_session_ui to open a local web page where the user can start and complete the verification session interactively — a new session is created each time the user clicks Start, so page refreshes work correctly. Use get_session and list_sessions to review results. Read the facesign://node-types resource for detailed reference on all node types. Read the facesign://flow-best-practices resource before building any new flow: it covers the English-only prompt rule, one-question-per-node, greeting 5+ seconds, no avatar self-introduction, no narration of invisible steps, node-selection patterns per scenario (access control / SCA / KYC / recovery), a recognition branching template, and a complete multilingual example. DISCOVERY INTERVIEW: When the user is describing a NEW flow for the first time (not an iteration or tweak), read the facesign://interview-guidance resource and conduct the short discovery interview it describes before calling launch_session_ui. Skip the interview entirely for iterations on an existing flow or when the user explicitly asks for a quick default. LANDING AND RECAP PAGES ARE YOUR RESPONSIBILITY: launch_session_ui and export_app no longer ship default chrome. On every call you MUST supply `landingHtml` (pre-session), `recapHtml` (post-session), and `uiStrings` (per-language dictionary whose keys YOU invent to match placeholders in the HTML). This applies even to minimal test cases — there is no 'just run it without customization' path. LANGUAGE DEFAULTS: By default, leave `langs` and `defaultLang` UNSET on every call — the session then supports every language in facesign://catalog and the user's browser language drives the UI. ONLY set these two parameters when the user EXPLICITLY restricts the language set (e.g. 'Spanish-only', 'English and Russian, default to English'). Do NOT narrow `langs` to `['en']` simply because the user described the demo in English or didn't mention languages — that silently strips multilingual support. When in doubt, omit both parameters. UI TRANSLATIONS: The target language set for `uiStrings` is derived from the session config: if `langs` is provided, `uiStrings` must cover every language in that list; if `langs` is omitted (the default), `uiStrings` must cover every language in the facesign://catalog resource. `en` is always required (ultimate runtime fallback). Every per-language dict MUST share the identical key set — if `en` has keys A, B, C then every other language's dict must also have A, B, C with translated values. The tool handler validates this strictly and returns a specific error listing missing keys/languages; when you see such an error, fix the gaps and retry. Reference strings in HTML via {{KEY}} placeholders (interpolated at inject time) or via window.t('KEY') calls in your <script> blocks (dynamic at runtime). Both resolve against the user's browser language, falling back through navigator.language → catalog match → `en` → the key literal. The `?lang=XX` URL query param overrides navigator.language and is forwarded to the session iframe. URL QUERY PARAMS: Any query parameters on the wrapper page URL are forwarded automatically to the session iframe src, so the FaceSign backend can read them (e.g. ?utm_source=..., ?ref=..., ?userId=...). Pre-existing params on the API-supplied session URL (tokens, etc.) are never overwritten. AVATAR LANGUAGE: `langs` (when set) is a whitelist of language codes (from facesign://catalog) the avatar is allowed to speak. The wrapper resolves the end-user's language (navigator.language or ?lang=), normalizes it (case-insensitive, aliases like zh-Hant→zh-TW, base-language fallback fr-FR→fr), and if it matches the allowlist, sets it as the session `defaultLang`. Otherwise the developer's `defaultLang` is used. Author flow prompts and outcome conditions in ENGLISH only. The FaceSign runtime generates the user-facing response in the session language regardless of the prompt language, but mixing languages in prompts breaks consistency (e.g. `Say: <French>` on one node and descriptive English on another causes the avatar to flip languages mid-flow). See the facesign://flow-best-practices resource for the full language rule and other prompt-writing rules. When the user does not mention languages, OMIT both `langs` and `defaultLang` so every catalog language is supported. When the user says e.g. 'make it Spanish-only', set langs=['es'] and defaultLang='es'; when they say 'support English and Russian, default to English', set langs=['en','ru'] and defaultLang='en'. LANDING HTML CONTRACT: window.__FACESIGN_FLOW__ (the flow array, may be read/modified); window.__startSession(input?) — call this to launch the session; exported apps accept a declared flowId and/or providedData, never a browser-supplied graph; window.t(key) and {{KEY}} placeholders for translations. The FaceSign session iframe has its own Start button that captures the user gesture for audio/video autoplay — the landing page does NOT need a button for that purpose; call window.__startSession() when your form submission / selection is ready. RECAP HTML CONTRACT: window.__FACESIGN_SESSION__ (session data, updated on each poll); window.__FACESIGN_SESSION_ID__; window.__refetchSession() returns Promise with fresh data; window.t(key) and {{KEY}} placeholders. Session data arrives in two stages — some fields appear immediately (user info, AI analysis, transcript), others (videoAIAnalysis, media.avatarVideo, media.screenshots, node reports) are delayed. Use videoAIAnalysisStatus to poll video analysis: pending means keep polling; succeeded and failed are terminal; absent means it was not requested. Render static sections once and update dynamic ones via polling. RECAP REFERENCE (DEMO MODE): When generating recapHtml for a flow Phase 0 identified as a 'demo for internal stakeholders', read the facesign://recap-reference resource for three visual demo-polish components (outcome banner, confidence bars, raw JSON toggle) that sit on top of the standard polling architecture. Skip this resource for production thank-you or redirect recaps — those are minimal closing pages, not data dashboards. EXPORT: Use export_app to generate a standalone, deployable Next.js application. It takes the same landingHtml / recapHtml / uiStrings inputs as launch_session_ui. export_app does NOT require set_api_key — the API key is configured in the exported app's .env.local file. For the complete session data type reference (used by recapHtml), read the facesign://session-data-types resource. OUTPUT FORMATTING: When confirming a built flow to the user, describe what the end user will experience and which choices THEY made (avatar, OTP settings, document types, compliance add-ons). Do NOT parrot internal FaceSign implementation details as 'features' of their specific flow — CSS class prefixes (lp-/r-), polling intervals/limits, session-data staging (static vs dynamic), catalog language auto-coverage, uiStrings key lists, class-naming conventions, Microblink extractor helpers, and framework names (Preact/Express/Next.js) are the same across every flow and add noise. Pick the few facts that are specific to THIS flow and present those.