npm package: @incodetech/incode-idv-mcp
Description: An MCP server implementation that integrates with the Incode IDV service, providing identity verification tools for AI assistants.
Author: Incode
Latest version: 1.0.5

<div align="center">

# <img src="docs/assets/favicon.png" alt="Incode" width="24" /> Incode IDV MCP Server

<br>

<img src="docs/assets/incode.svg" alt="Incode" width="140" />

<br>
<br>

[![npm version](https://img.shields.io/npm/v/@incodetech/incode-idv-mcp?style=flat-square&color=00B2A9)](https://www.npmjs.com/package/@incodetech/incode-idv-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-Compatible-blue?style=flat-square)](https://modelcontextprotocol.io)

**Powered by [Incode Technologies](https://incode.com)** — Global Leader in Identity Verification

---

> **Brand notice:** The Incode name and logo are trademarks of Incode.  
> © Incode. All rights reserved. Not covered by this project's open-source license.

</div>

## About

An MCP (Model Context Protocol) server that integrates **Incode's identity verification** into AI assistants like Claude. Enable your AI to generate verification links, check session status, retrieve scores, and manage authentication tokens — all through natural language.

---

## 🛠️ Available Tools

The server provides five powerful tools for complete identity verification workflows:

| Tool | Description | Key Parameters | Returns |
|------|-------------|----------------|---------|
| **generate_interview_link** | Create a new verification session | None (backend configured) | Interview ID & URL |
| **get_interview_status** | Check session progress | `interviewId` | Status & progress info |
| **get_interview_score** | Get verification results | `interviewId` | Score & detailed results |
| **get_interview_token** | Get JWT token on successful interview (15 min TTL) | `interviewId` | JWT access token |
| **validate_token** | Verify token validity | `token` | Validation result & claims |

<details>
<summary><b>📖 View Detailed Tool Specifications</b></summary>

### 🔗 generate_interview_link
Create a new identity verification session.
- **Inputs:** None (all values are configured on the backend)
- **Returns:** Interview ID and verification URL

### 📍 get_interview_status
Check the current status of an identity verification session.
- **Inputs:** 
  - `interviewId` (string): The interview ID returned from `generate_interview_link`
- **Returns:** Current status and progress information

### 📊 get_interview_score
Retrieve verification results and score for a completed session.
- **Inputs:**
  - `interviewId` (string): The interview ID returned from `generate_interview_link`
- **Returns:** Verification result, score, and detailed information

### 🔑 get_interview_token
Get JWT token directly for successfully completed interviews (15-minute TTL).
- **Inputs:**
  - `interviewId` (string): The interview ID returned from `generate_interview_link`
- **Returns:** JWT access token and metadata

### ✅ validate_token
Validate JWT token and return claims.
- **Inputs:**
  - `token` (string): JWT token to validate
- **Returns:** Validation result and token claims if valid

</details>

---

## 🔄 Verification Workflow

The typical identity verification workflow is straightforward and powerful:

```mermaid
graph LR
    A[🔗 Generate Link] --> B[📍 Check Status]
    B --> C[📊 Get Score]
    C --> D[🔑 Get JWT Token]
    D --> E[✅ Validate Token]
    style B stroke-dasharray: 5 5
    style C stroke-dasharray: 5 5
```

### Step-by-Step Process

| Step | Action | Tool | Purpose |
|------|--------|------|---------|
| 1️⃣ | **Generate Link** | `generate_interview_link` | Create verification URL for user |
| 2️⃣ | **Check Status** | `get_interview_status` | Monitor completion progress |
| 3️⃣ | **Get Score** | `get_interview_score` | Retrieve verification results |
| 4️⃣ | **Get Interview JWT Token** | `get_interview_token` | Obtain JWT token when succesful interview with results (15 min TTL) |
| 5️⃣ | **Validate Token** | `validate_token` | Verify JWT token is from valid interview |

---

## 🚀 Quick Start

### 1️⃣ Get Your API Key - 🔑

1. Visit **[https://mcp-playground.labs.incode.com/](https://mcp-playground.labs.incode.com/)**
2. **Sign up** for an account
3. **Verify your email** and retrieve your API KEY

### 2️⃣ Install & Configure

Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "incode-idv": {
      "command": "npx",
      "args": ["-y", "@incodetech/incode-idv-mcp"],
      "env": {
        "API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}
```

> 💡 **Tip:** Replace `YOUR_API_KEY_HERE` with your actual API key from step 1

### 3️⃣ Configure Claude Desktop

1. **Open** Claude Desktop App
2. Navigate to **Settings** ⚙️
3. Go to **Developer** tab
4. Click **Edit Config**
5. Add the configuration above with your **API_KEY**
6. **Restart** Claude Desktop to load the new MCP server. Ensure MCP server is enabled.

### 4️⃣ Verify Installation ✅

After restarting Claude Desktop, ask Claude:
> "Can you generate an identity verification link?"

If configured correctly, Claude will use the MCP server to create a verification session! 🎉

---


## 🔧 Troubleshooting

Having issues? Here's how to get back on track:

### 🐛 Common Issues

<table>
<tr>
<th>Issue</th>
<th>Solution</th>
</tr>
<tr>
<td>❌ <b>Tools Not Working</b></td>
<td>Verify your <code>API_KEY</code> is correctly set in the configuration with a valid value</td>
</tr>
<tr>
<td>📁 <b>Path Errors</b></td>
<td>Ensure the project directory path or package name is correct.</td>
</tr>
<tr>
<td>🚫 <b>Server Not Starting</b></td>
<td>Validate your <code>claude_desktop_config.json</code> syntax (no trailing commas, proper quotes)</td>
</tr>
<tr>
<td>⏱️ <b>Token Expired</b></td>
<td>JWT tokens expire in 15 min. Generate new ones as needed</td>
</tr>
</table>

### 🔍 Debugging Tools

For advanced debugging and troubleshooting:

- 📋 **[View Claude Desktop Logs](https://modelcontextprotocol.io/legacy/tools/debugging#viewing-logs)** — Check detailed error messages
- 📚 **[MCP Debugging Guide](https://modelcontextprotocol.io/legacy/tools/debugging)** — Comprehensive troubleshooting steps
- 🔧 **Test API Key** — Try the API key directly on [mcp-playground.labs.incode.com](https://mcp-playground.labs.incode.com/)

### 💬 Get Help

<table>
<tr>
<td align="center">🐛</td>
<td><b>GitHub Issues</b><br><a href="https://github.com/incodetechnologies/incode-idv-mcp/issues">Report bugs & request features</a></td>
</tr>
<tr>
<td align="center">📧</td>
<td><b>Email Support</b><br><a href="mailto:aisupport@incode.com">aisupport@incode.com</a> for issues and inquiries</td>
</tr>
<tr>
<td align="center">🌐</td>
<td><b>Incode Website</b><br><a href="https://incode.com">incode.com</a> for company information</td>
</tr>
</table>

---

## 📄 License

This project is licensed under the **MIT License** — free to use, modify, and distribute.

See the [LICENSE](LICENSE) file for full details.

---

<div align="center">

### Developed by [Incode Technologies](https://incode.com)

**[Website](https://incode.com)** • **[Documentation](https://github.com/incodetechnologies/incode-idv-mcp)** • **[GitHub](https://github.com/incodetechnologies/incode-idv-mcp)** • **[npm](https://www.npmjs.com/package/@incodetech/incode-idv-mcp)** • **[Other Docs](https://docs.incode.com)**

[![Incode](https://img.shields.io/badge/Incode-Technologies-00B2A9?style=for-the-badge)](https://incode.com)

_Transforming identity verification with AI-powered solutions_

</div>