# Sumsub MCP

> Sumsub integrates identity verification (KYC/AML) directly into your AI workflow. Use this server to create new applicants, upload required documents like passports or IDs, and track verification status—all without leaving your agent's chat window. It handles the technical heavy lifting of compliance checks so you can focus on onboarding.

## Overview
- **Category:** security-compliance
- **Price:** Free
- **Tags:** kyc, aml, identity-verification, compliance, onboarding

## Description

You’re connecting your Sumsub account so your AI client can handle identity verification and compliance checks right in the chat window. Forget logging into a separate dashboard; you manage entire KYC/AML flows using natural language commands. This server handles all the technical heavy lifting required for onboarding, letting you focus on what matters.

When you need to get started with a new user, you'll use `create_applicant`. This tool registers a brand-new profile in Sumsub and lets you define the specific KYC or AML verification level that’s required. If you already have an applicant ID, you can check their current compliance status instantly by calling `get_applicant_status`. You immediately know if they're pending review, if documents are missing, or if a requirement failed.

To get the full picture of any user, you fetch all available profile data using `get_applicant` with the existing Sumsub ID. This gives your agent everything it needs to move forward. If that isn’t enough, you'll use `add_document`. This tool uploads required identity proofs—like passports or driver's licenses—and attaches them directly to a specific applicant's profile using base64 encoding.

For building out external client applications, you need secure credentials. You generate these by calling `generate_access_token`, which creates a time-limited WebSDK access token. This is what your end-users use to initialize the Sumsub client directly within their own web app environment.

Essentially, this server gives your agent control over the entire identity verification lifecycle: creating the record, uploading all necessary documents, pulling the full profile data, checking the real-time compliance status, and even generating tokens so you can build out seamless integration into other systems. You've got everything needed to manage complex regulatory requirements without leaving your chat session.

## Tools

### add_document
Uploads a document (like an ID or passport) to an existing applicant's profile.

### create_applicant
Creates and registers a brand new Sumsub applicant, defining the required KYC/AML level.

### generate_access_token
Generates a secure WebSDK access token for your users to integrate Sumsub into their own web apps.

### get_applicant_status
Checks the real-time verification status of a specific applicant against compliance requirements.

### get_applicant
Retrieves all available profile data for an existing applicant ID.

## Prompt Examples

**Prompt:** 
```
Create a new Sumsub applicant for user 'ext_user_99' at the 'basic-kyc' level.
```

**Response:** 
```
I've created the applicant. The Sumsub Applicant ID is '65b2f...a1'. You can now proceed with document uploads or status checks for this user.
```

**Prompt:** 
```
Check the verification status for applicant ID 65b2f8e9c1234567890.
```

**Response:** 
```
The applicant '65b2f8e9c1234567890' is currently in the 'pending' state. Sumsub is reviewing the submitted documents.
```

**Prompt:** 
```
Generate a WebSDK access token for user 'user_456' at the 'advanced-verification' level.
```

**Response:** 
```
Generated token: 'sb:eyJhbG...'. You can use this token to initialize the Sumsub WebSDK for 'user_456'.
```

## Capabilities

### Create Applicant Record
Starts a new applicant profile in Sumsub, specifying the required KYC or AML verification level.

### Check Verification Status
Retrieves the current compliance status of an applicant based on their unique ID.

### Upload Identity Documents
Attaches identity documents (e.g., passports, IDs) to a specific applicant profile using base64 encoding.

### Retrieve Applicant Profile
Fetches the full profile data for an existing Sumsub applicant ID.

### Generate WebSDK Token
Creates a secure, time-limited access token necessary for integrating Sumsub's web SDK into client applications.

## Use Cases

### Onboarding a New Client
A new user signs up. Your agent first calls `create_applicant` for the correct KYC level. Then, it prompts the user to upload their ID using `add_document`. Finally, it runs `get_applicant_status` repeatedly until Sumsub confirms approval.

### Troubleshooting a Failed Check
An applicant's status is 'pending'. Instead of waiting for an email, your agent calls `get_applicant` to pull the full profile. This reveals which specific document (e.g., utility bill) was missing or flagged, allowing immediate follow-up.

### Integrating into a Web App
Your development team needs Sumsub verification in a client portal. The agent runs `generate_access_token` to get the secure key, which they plug directly into their code base—no manual secret management needed.

### Bulk Compliance Audit
The compliance team needs to audit 20 users. Instead of running 20 dashboard reports, your agent uses `get_applicant_status` iteratively for each ID, summarizing the entire group's compliance health in minutes.

## Benefits

- Checks status instantly. Instead of manually logging into the Sumsub dashboard, you can call `get_applicant_status` and get the real-time compliance state right in your agent's response.
- Automates document collection. Use `add_document` to upload passports or IDs directly from your workflow, associating them immediately with a specific applicant ID.
- Builds client integrations faster. The `generate_access_token` tool gives you the necessary WebSDK token without any manual API playground steps.
- Manages user records cleanly. Start profiles using `create_applicant` and retrieve everything later by calling `get_applicant`, all in one conversation thread.
- Stops redundant checks. You don't need multiple tools for basic data; `get_applicant` gives you the full profile, saving time compared to piecing together separate pieces of data.

## How It Works

The bottom line is: your AI client acts like an internal compliance assistant that executes complex API calls without you needing to touch a web dashboard.

1. First, subscribe to this server and provide your Sumsub App Token and Secret Key credentials.
2. Next, prompt your AI agent with a specific task (e.g., 'Check status for ID 123').
3. The agent runs the required tool, sends the data to the Sumsub API, and reports the result back directly.

## Frequently Asked Questions

**How do I use Sumsub MCP Server to create a new applicant?**
You run `create_applicant` and specify the user details and the required KYC/AML level. The server returns the unique Sumsub Applicant ID, which you need for all subsequent steps.

**Does `get_applicant_status` show if my documents were uploaded?**
It shows the *verification* status (e.g., 'pending' or 'approved'). To confirm document upload, use `add_document` first and then verify the record using `get_applicant`.

**What is the best way to integrate Sumsub into my custom app?**
You must run `generate_access_token`. This tool creates a secure WebSDK token that your developers can safely embed in their code, rather than handling raw credentials.

**Which tool should I use to get all data on an applicant?**
Use `get_applicant`. It pulls the full profile record and is better than calling multiple smaller tools because it gathers comprehensive data in one go.

**How does using the `generate_access_token` tool handle security for my client calls?**
The token acts as a scoped key. You must generate this specific access token first, then pass it to other tools like `get_applicant`. This limits what your agent can do if any single endpoint is compromised.

**What format must I use when calling the `add_document` tool?**
You need to provide the document data as a base64 encoded string. The tool requires this specific encoding for all identity documents, including passports and ID cards.

**If I use `get_applicant_status`, what should I do if the status indicates an error?**
The response payload includes a dedicated error code. Your agent must read this specific code (e.g., INVALID_KYC) to know exactly why verification failed or what data is missing.

**Does `get_applicant` support fetching multiple records at once, or am I limited?**
The tool supports pagination for large datasets. If your request exceeds the default batch size, you must pass a cursor or page number in subsequent calls to retrieve all applicant data.

**Can I check if a specific user has passed their KYC verification?**
Yes. Use the `get_applicant_status` tool with the Applicant ID. The AI will return the current verification stage and whether they are approved, pending, or rejected.

**How do I provide a verification link to my users?**
You can use the `generate_access_token` tool. It provides the necessary token to initialize the Sumsub WebSDK for a specific User ID and verification level.

**Is it possible to upload a user's ID document directly through the agent?**
Yes, by using the `add_document` tool. You will need the Applicant ID, the document type (like PASSPORT), the country code, and the base64 encoded content of the file.