> ## Documentation Index > Fetch the complete documentation index at: https://docs.facesign.run/llms.txt > Use this file to discover all available pages before exploring further. # Build with AI > Connect FaceSign to your AI coding tool and ship a working verification integration in minutes. FaceSign exposes a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that lets AI assistants create, test, and export verification sessions through natural language. Instead of manually wiring nodes and writing integration code, you describe what you need — the MCP builds the verification flow, previews it locally, and exports a production-ready application. **Privacy posture** Video is processed in memory and discarded at session end. No raw biometric data is retained by default. FaceSign operates as a **data processor**; you are the data controller. GDPR, CCPA, BIPA aligned; SOC 2 Type II in progress. See [Security](/docs/security/architecture) for details. ## What is FaceSign? FaceSign is a **step-up authentication platform** for high-risk moments. When a user triggers a sensitive action — a wire transfer, account recovery, payment above a threshold — FaceSign conducts a short, AI-led conversational verification in 10-20 seconds on the happy path. FaceSign is **not KYC or onboarding identity verification**. It's post-login step-up authentication — confirming the right person is performing the right action, right now. ### The problem FaceSign solves Two tools dominate high-risk transaction verification today, and both are failing: * **SMS OTP** — vulnerable to SIM swap, social engineering, and account takeover. Attackers intercept codes routinely. * **Call centers** — cost \$4-70 per verification, take 5-15 minutes, can't detect coercion, and don't scale. Neither can answer the question that matters: **Is this the right person, acting freely, right now?** ### How FaceSign works A FaceSign session is a short real-time conversation between the user and an AI avatar. Several models run **in parallel** and produce independent signals: | Model | What it detects | | ------------------------------- | -------------------------------------------------------------------- | | **Liveness detection** | Deepfakes, pre-recorded video, face spoofing (blocks replay attacks) | | **Facial recognition** | Matches against hashed biometric fingerprints from prior sessions | | **Conversational verification** | Spoken knowledge-based questions, OTPs, secret phrases | | **Coercion and intent signals** | Duress, secondary voices, scripted responses, inebriation | | **Video AI analysis** | Post-session review of behavioral and environmental anomalies | | **Predictive risk** | Device fingerprint, IP, geo, time-of-day, interaction history | The design philosophy is **defense in depth**. No single signal gates the outcome. You compose layers that match your risk tolerance, and the session reports per-layer results that you consume in your backend. The result: FaceSign verifies both the **person** (are they who they claim to be?) and their **state of mind** (are they acting freely, or under duress?). No other authentication product does both. ### Session anatomy FaceSign is a fully managed platform. The lifecycle is three steps: 1. **Create a session.** Your backend sends a flow definition to the FaceSign API (or MCP). You receive a session ID and a single-use client secret URL. 2. **User completes verification.** Redirect the user to the hosted widget. The AI avatar runs the conversation, liveness checks, recognition, document scans, and OTPs — whatever your flow specifies. 3. **Receive results.** FaceSign delivers results via webhook or polling. Your app never touches raw biometric data — video is processed in memory and discarded at session end. You are the data controller; FaceSign is the data processor. ### When to use FaceSign FaceSign is designed for the moments where OTP and passwords aren't enough: * **Wire transfers and high-value payments** — confirm the account holder before authorizing * **Account recovery** — verify identity without passwords or security questions * **Payee and beneficiary changes** — prevent social engineering attacks * **Device changes and credential resets** — step-up before sensitive account modifications * **Regulatory compliance (PSD3)** — meet Strong Customer Authentication requirements for coached transfer liability ## Why MCP for step-up authentication? | Traditional integration | MCP integration | | ------------------------------------------------- | ---------------------------------------------- | | Read docs, learn node types, write flow JSON | Describe the use case in plain English | | Build frontend, configure webhooks, handle errors | MCP generates the full app with error handling | | Days to first working session | Minutes to first working session | | Changes require code edits and redeployment | Describe the change, MCP rebuilds | *** ## Quickstart By the end of this section, you'll have a working FaceSign verification session running from your AI assistant. ### Prerequisites You need two things: **1. An API key.** | Environment | Key prefix | What it's for | | ----------- | ------------- | -------------------------------------------------------------- | | Sandbox | `sk_test_...` | Free development sessions, full feature parity with production | | Production | `sk_live_...` | Real user verification, per-contract limits | If you don't have a key yet, email [developers@facesign.ai](mailto:developers@facesign.ai) with your company name and intended use case. Sandbox keys are free. **API keys are server-side only.** Never embed them in client code, public repos, or browser environments. For frontend integration, create sessions on your backend and pass only the single-use `clientSecret.url` to the user. Full reference in [Authentication](/docs/reference/authentication). **2. An MCP-compatible client.** Claude Code, Claude Desktop, Cursor, or any client that supports the [Model Context Protocol](https://modelcontextprotocol.io) over Streamable HTTP. ### Step 1: Add FaceSign to your MCP config Add the FaceSign server to your client's MCP configuration: ```json title=".mcp.json" wrap theme={null} { "mcpServers": { "facesign": { "type": "http", "url": "https://mcp.facesign.ai/mcp" } } } ``` For Claude Code, add this to `.mcp.json` in your project root. For Claude Desktop, add it to `claude_desktop_config.json`. For Cursor, add it to `.cursor/mcp.json`. See [Supported clients](#supported-clients) below for exact paths. ### Step 2: Set your API key Once connected, the MCP needs your API key to authenticate with FaceSign: ``` Tell the MCP: "Set my FaceSign API key to sk_test_your_key_here" ``` The MCP calls `set_api_key`, loads the available avatars and languages, and confirms the connection. ### Step 3: Describe what you want to build Tell your AI assistant what verification flow you need. Be specific about the use case: ``` "Build a step-up verification for wire transfers. It should check liveness, ask a security question about the transaction, and send an email OTP." ``` The MCP will: 1. Ask you clarifying questions (avatar choice, failure handling, etc.) 2. Assemble the verification flow from your answers 3. Validate the flow structure ### Step 4: Preview locally Once the flow is built, the MCP opens a browser preview: ``` "Launch a preview so I can test this flow" ``` This calls `launch_session_ui`, which opens a local web page. Click **Start Session** to run through the verification with your camera and microphone. ### Step 5: Export for production When the flow looks right, export it as a deployable Next.js application: ``` "Export this as a Next.js app" ``` This calls `export_app`, which generates a complete project — React frontend, API routes for session creation, `.env.local` template, and a README with deployment instructions. Set `FACESIGN_API_KEY` in your environment and deploy to any Node.js host (Vercel, Railway, Fly). **Why Next.js?** Session creation goes through the `@facesignai/api` package, which is server-side only — it uses your `FACESIGN_API_KEY`, which must never be exposed to the browser. Next.js gives us a runtime where the key stays on the server (API routes / server actions) while the verification UI runs in the client. That's why the export target is Next.js, not a static bundle. *** ## Supported clients FaceSign MCP works with any client that supports the Model Context Protocol. Pick yours: Add FaceSign to your project config. Claude Code has full tool support with interactive prompts. ```json title=".mcp.json" wrap theme={null} { "mcpServers": { "facesign": { "type": "http", "url": "https://mcp.facesign.ai/mcp" } } } ``` Or add it globally at `~/.claude.json` to make it available in all projects. Add FaceSign to your Claude Desktop configuration. ```json title="claude_desktop_config.json" wrap theme={null} { "mcpServers": { "facesign": { "type": "http", "url": "https://mcp.facesign.ai/mcp" } } } ``` Config file location: * **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` * **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` Add FaceSign to your Cursor MCP settings. ```json title=".cursor/mcp.json" wrap theme={null} { "mcpServers": { "facesign": { "type": "http", "url": "https://mcp.facesign.ai/mcp" } } } ``` Any MCP client that supports Streamable HTTP transport can connect to FaceSign at: ``` https://mcp.facesign.ai/mcp ``` The server is unauthenticated at the transport layer — the first tool call should be `set_api_key` to initialize the session with your FaceSign API key. *** ## Tools The FaceSign MCP server exposes five tools for building and managing verification sessions: | Tool | Purpose | | ------------------- | ---------------------------------------------------- | | `set_api_key` | Authenticate with FaceSign | | `launch_session_ui` | Preview a verification flow in a local browser | | `export_app` | Generate a deployable Next.js application | | `get_session` | Retrieve results for a specific verification session | | `list_sessions` | Query past sessions with filters | ### set\_api\_key Authenticates the MCP server with your FaceSign API key. Must be called before any other tool. `sk_test_` keys connect to the sandbox, `sk_live_` keys connect to production. On success the server loads the available avatars and languages. ``` "Set my FaceSign API key to sk_test_abc123" ``` ### launch\_session\_ui Opens a local web page where you can run through a verification session interactively. A new session is created each time you click **Start Session**, so page refreshes work correctly. ``` "Launch a preview with a liveness check followed by a security question" ``` Flows must be linear with no loops or cycles. A node must never navigate back to a previous node. All paths move forward toward an END node. ### export\_app Generates a standalone Next.js application from the current flow, ready for deployment. The exported project includes the frontend, API routes for session creation, an `.env.local` template, and a README. Set `FACESIGN_API_KEY` in your environment and deploy to any Node.js host. ``` "Export this flow as a Next.js app" ``` ### get\_session Retrieves the full results of a verification session — transcript, AI analysis, node reports, and media references. ``` "Show me the results of session " ``` ### list\_sessions Queries past verification sessions with optional filtering by status, date range, client reference, or free-text search. Returns a cursor-paginated list. ``` "Show me the last 10 completed sessions" ``` ## Node types available in flows FaceSign flows are assembled from these 13 node types: | Node type | Purpose | | -------------------- | ------------------------------------------------------------------------------------- | | `START` | Entry point for every flow | | `END` | Terminal node — session ends here | | `PERMISSIONS` | Request camera and/or microphone access with a custom prompt or branch | | `CONVERSATION` | AI-led conversational turn with custom prompts and conditional outcomes | | `LIVENESS_DETECTION` | Deepfake and liveness check on the live video feed | | `FACE_SCAN` | High-quality face capture with an oval overlay | | `FACE_COMPARE` | Compare two face images (session video, face scan, document photo, or provided image) | | `RECOGNITION` | Match the user's face against previously registered faces | | `DOCUMENT_SCAN` | Capture and extract data from identity documents | | `ENTER_EMAIL` | Collect the user's email address without sending an OTP | | `TWO_FACTOR_EMAIL` | Send and verify an email one-time passcode | | `TWO_FACTOR_SMS` | Send and verify an SMS one-time passcode | | `DATA_VALIDATION` | Validate collected data and branch the flow on the result | *** ## Recipes Each recipe shows a natural-language prompt you give your AI assistant and what the MCP does behind the scenes. Pick one to see the full pattern. **Wire transfer with coercion detection.** The most common FaceSign use case: verify the account holder before a high-value transfer, and detect if they are acting under duress. **Prompt:** ``` Build a step-up verification for wire transfers over $5,000. Start with liveness detection, then ask the user to confirm the transfer details in a conversation. Include coercion detection. Send an email OTP as the final step. ``` **What the MCP builds:** Initializes the verification session. Interactive deepfake check. The avatar asks the user to perform randomized actions to confirm a live human. The avatar asks the user to confirm the recipient, amount, and purpose. Six AI models run in parallel: coercion detection analyzes vocal stress, gaze patterns, and response timing throughout. Sends a one-time passcode to the user's email for a second authentication factor. Session completes. Results are available via webhook or `get_session`. Coercion detection runs across every node, not as a separate step. The conversational node gives it the richest signal because the user is speaking freely. **Account recovery without passwords.** Replace security questions with a face-based recovery flow. The user proves identity through biometric recognition instead of knowledge-based answers. **Prompt:** ``` Build an account recovery flow. Collect the user's email, verify their face against our stored biometric, then do a liveness check. If everything passes, let them proceed to password reset. ``` **What the MCP builds:** Initializes the session. Collects the user's email address to look up their account. Compares the live face against the stored biometric fingerprint for that account. Confirms the person is physically present (not a photo or deepfake). Session completes. Your app receives the verification result and can proceed with the password reset. **KYC-style onboarding with document scan.** While FaceSign is designed for post-login step-up, you can build a first-time identity enrollment flow that captures a document and creates a biometric fingerprint for future recognition. **Prompt:** ``` Build an onboarding flow for new users. Capture their government ID, scan their face, do a liveness check, then have the avatar welcome them and explain how future verifications will work. ``` **What the MCP builds:** Initializes the session. Captures and validates the user's government-issued ID. Captures the user's face and creates a biometric fingerprint for future recognition. Confirms a live human is present. The avatar welcomes the user and explains what to expect in future verification sessions. Session completes. The biometric fingerprint is stored for future `RECOGNITION` nodes. **Export and deploy to production.** After building and testing any flow, export it as a production-ready application. **Prompt:** ``` Export this flow as a Next.js app. I want to deploy it to Vercel. ``` **What the MCP does:** 1. Calls `export_app` with the current flow. 2. Generates a complete Next.js project containing the React frontend component with the FaceSign widget, API routes for creating and managing sessions, an `.env.local` template, and deployment-ready configuration. **Deploy steps:** ```bash wrap theme={null} cd exported-app npm install echo "FACESIGN_API_KEY=sk_live_your_key" > .env.local vercel deploy ``` *** ## Troubleshooting If something isn't working with the FaceSign MCP, start here. Each section covers a specific failure mode with symptoms and fixes. **Symptoms:** Tools return "API key not set" or "Unauthorized" errors. `launch_session_ui` and `get_session` fail immediately. **Cause:** The MCP requires `set_api_key` to be called before any other tool. The server does not read credentials from transport headers — the key lives per-session and must be supplied via the tool. **Fix:** 1. Verify your key starts with `sk_test_` (sandbox) or `sk_live_` (production). 2. Ask your assistant to call `set_api_key` explicitly: ``` "Set my FaceSign API key to sk_test_your_key_here" ``` 3. If the key is rejected, confirm it hasn't been revoked or rotated. Contact [developers@facesign.ai](mailto:developers@facesign.ai) if you need a new key. **Symptoms:** Sessions created in sandbox don't appear in your production dashboard, or vice versa. Biometric fingerprints from test sessions aren't found in production. **Cause:** Your API key determines the environment. `sk_test_` keys always connect to sandbox; `sk_live_` keys always connect to production. There is no separate environment toggle. **Fix:** 1. Check which key you configured. Run: ``` "What API key is currently set?" ``` 2. If you are testing, use a `sk_test_` key. If you are deploying, switch to `sk_live_`. 3. Sandbox and production environments are completely isolated. Sessions, biometric fingerprints, and flow data do not cross between them. **Symptoms:** `launch_session_ui` or `export_app` rejects the flow with a validation error like "flow contains a cycle" or "missing END node." **Cause:** FaceSign flows must be linear directed graphs. Common mistakes include: * Missing a `START` or `END` node * Creating a loop (a node that navigates back to a previous node) * Using `condition: "default"` on node outcomes (causes double-speak) * Referencing a node ID that doesn't exist in the flow **Fix:** 1. Verify the flow starts with exactly one `START` node and ends with at least one `END` node. 2. Check that every node's outcome points forward (higher in the sequence), never backward. 3. Remove any `condition: "default"` from outcome definitions. 4. Ask your assistant to validate the flow: ``` "Validate this flow and show me any structural issues" ``` **Symptoms:** Your AI client reports "MCP server unreachable," "connection refused," or the tool list is empty. **Cause:** The FaceSign MCP server uses Streamable HTTP transport at `https://mcp.facesign.ai/mcp`. Connection failures are typically caused by: * Incorrect URL in the config * Network or firewall blocking outbound HTTPS * Client configured for stdio transport instead of HTTP **Fix:** 1. Verify the URL is exactly `https://mcp.facesign.ai/mcp` (no trailing slash, no path variations). 2. Confirm your client supports HTTP-based MCP servers. FaceSign does not use stdio transport — there is no local binary. 3. Check that your network allows outbound HTTPS to `mcp.facesign.ai`. 4. Restart your MCP client after changing the configuration. Most clients require a restart to pick up config changes. **Symptoms:** After configuring the MCP, your assistant does not list FaceSign tools and does not respond to FaceSign-related prompts. **Cause:** The client either failed to load the MCP config or does not support Streamable HTTP transport. **Fix:** 1. Check the config file location for your client (Claude Code, Claude Desktop, or Cursor — see [Supported clients](#supported-clients) above). 2. Verify the JSON is valid (no trailing commas, matching braces). 3. Restart the client completely — not all clients hot-reload MCP configurations. 4. Ask your assistant to list available tools. If FaceSign appears but tools are missing, the connection succeeded but authentication may have failed. See the "API key not set" section above. **Symptoms:** The browser preview opens, but clicking **Start Session** shows an error or spinner that never resolves. **Cause:** The local preview needs camera and microphone access to run a verification session. The browser may be blocking these permissions. **Fix:** 1. When the browser prompts for camera and microphone access, allow both. 2. If you previously denied permissions, open the browser's site settings and re-enable camera and microphone for `localhost`. 3. Verify your camera is not in use by another application. 4. Check the browser console for error messages — network errors suggest an API key or connectivity issue. **Symptoms:** The exported Next.js app builds and runs, but creating a verification session returns a 401 or 500 error. **Cause:** The exported app reads `FACESIGN_API_KEY` from environment variables. If the variable is missing or set to a sandbox key in production, session creation fails. **Fix:** 1. Confirm `FACESIGN_API_KEY` is set in your deployment environment (not only in `.env.local`). 2. Use a `sk_live_` key for production deployments. 3. Check your hosting provider's environment variable configuration — Vercel, Railway, and similar platforms have their own environment variable UI. ### Still stuck? Contact [developers@facesign.ai](mailto:developers@facesign.ai) with your client name and version, the error message or unexpected behavior, and your MCP config (with the API key redacted). *** ## When to use MCP vs. the API | Use MCP when... | Use the API when... | | -------------------------------------------- | --------------------------------------------- | | You want to build a flow from a description | You have an exact flow spec already | | You're prototyping or iterating quickly | You're integrating into an existing codebase | | You want a full exported app | You need fine-grained control over every step | | Your team uses AI assistants for development | Your team prefers traditional SDK integration | Both paths produce the same result — a verification session powered by the same API. MCP is faster for getting started; the [REST API](/docs/api-reference/createSession) gives you full control. *** ## What's next? You've got sandbox working. Email us to move to `sk_live_` keys with your contract terms, rate limits, and data residency zone. Tokenization, retention model, and compliance posture. Self-contained pages you can forward to InfoSec. Battle-tested flow patterns for wire transfers, account recovery, anomaly step-up, and payment authentication.
Last updated: 2026-04-17 · MCP server: 2.8.0 · Changelog