# Technical Guide: Reusable MFA Service via Model Context Protocol (MCP)

This document explains how the Multi-Factor Authentication (MFA) service was built, installed, and how it can be integrated into other projects using the Model Context Protocol (MCP).

---

## 1. Overview
The MFA service is based on the TOTP (Time-based One-Time Password) algorithm, compatible with Google Authenticator, Microsoft Authenticator, and Authy. 

We provide two ways to use it:
1. **Local Integration**: Using standard Python libraries (used in the current ATS backend).
2. **MCP Service**: A standalone server that exposes MFA tools to AI agents or other applications via standard protocol.

---

## 2. Installation & Setup (How we did it)

### Prerequisites
- Python 3.12+
- Virtual Environment (Recommended)

### Libraries Installed
We installed the following core libraries:
```bash
pip install pyotp qrcode Pillow fastmcp
```
- `pyotp`: Handles the logic for generating secrets and verifying 6-digit codes.
- `qrcode`: Generates the QR code images for the user to scan.
- `Pillow`: Required by `qrcode` to render and save image files.
- `fastmcp`: The framework used to expose these functions as MCP tools.

---

## 3. How to Use the Reusable MCP Service

The standalone MFA server is located in: `/mcp_otp_service/server.py`

### Running the MCP Server
To start the MFA service as an MCP server:
```bash
python mcp_otp_service/server.py
```

### Available MCP Tools
When connected via an MCP client (like Claude Desktop or another backend), you have access to:

1. `generate_mfa_secret()`: Returns a random Base32 string.
2. `get_provisioning_uri(secret, email, issuer)`: Returns the `otpauth://` URI.
3. `verify_mfa_code(secret, code)`: Returns `True/False`. It also supports the master bypass code `098765`.

---

## 4. Integrating into a New Project (Steps)

If you want to use this MFA logic in a completely different project (e.g., a new Node.js or Python app):

### Step 1: User Model Update
Add two fields to your database's User table:
- `mfa_enabled` (Boolean, default False)
- `mfa_secret` (String, max_length 32, null=True)

### Step 2: Setup Phase (One-time)
1. Call `generate_mfa_secret()` via MCP.
2. Save this secret to the user's record in your database.
3. Call `get_provisioning_uri()` with the secret and user's email.
4. Convert that URI into a QR code (using a QR library) and show it to the user.
5. Ask the user for the 6-digit code from their app to "Enable" it.

### Step 3: Login Phase
1. After the user enters their password, check if `user.mfa_enabled` is True.
2. If True, redirect them to an MFA input screen.
3. Call `verify_mfa_code(user.mfa_secret, user_provided_code)` via MCP.
4. If it returns `True`, grant the login session/token.

---

## 5. Security Features
- **Master OTP**: During development, you can use `098765` to bypass any MFA check.
- **Zero External Dependency**: This service works offline and does not require paid SMS or Email APIs.
- **Protocol Agnostic**: Because it uses MCP, you can call these tools from a CLI, a Web App, or an AI Agent without re-implementing the math.

---
Guide generated on: June 09, 2026
Project: Indovision TA-ATS