KYC MCP Server

A production-ready Model Context Protocol (MCP) server for KYC (Know Your Customer) API integration with advanced features including auto tool registry, caching, rate limiting, and comprehensive error handling.

Features

✅ Auto Tool Registry: Automatic tool discovery from metadata JSON files
✅ Advanced Caching: Redis-based caching with configurable TTL
✅ Rate Limiting: Per-tool rate limiting with token bucket algorithm
✅ JWT Authentication: Secure API authentication with token management
✅ Retry Logic: Exponential backoff for failed requests
✅ Structured Logging: Comprehensive logging with structlog
✅ Docker Ready: Full Docker and Docker Compose support
✅ Type Safety: Pydantic v2 for data validation
✅ Production Ready: Error handling, monitoring, and graceful shutdown

Implemented Tools

1. PAN Verification (`verify_pan`)

Verify PAN card details with name and date of birth matching.

Input:

pan: 10-character PAN number (e.g., "XXXPX1234A")
name_as_per_pan: Full name as per PAN card
date_of_birth: Date of birth in DD/MM/YYYY format
consent: User consent ('Y' or 'y')
reason: Reason for verification

Output:

PAN validation status
Name and DOB match results
Aadhaar seeding status
PAN holder category

Cache TTL: 1 hour

2. PAN-Aadhaar Link Check (`check_pan_aadhaar_link`)

Check if PAN and Aadhaar are linked.

Input:

pan: Individual PAN number (4th character must be 'P')
aadhaar_number: 12-digit Aadhaar number
consent: User consent ('Y' or 'y')
reason: Reason for checking

Output:

Link status (linked/not linked)
Descriptive message

Cache TTL: 2 hours

Architecture

kyc-mcp-server/ ├── src/ │ ├── main.py # Application entry point │ ├── server/ │ │ └── mcp_server.py # MCP server implementation │ ├── tools/ │ │ ├── base_tool.py # Abstract base tool class │ │ ├── pan_verification.py # PAN verification tool │ │ └── pan_aadhaar_link.py # PAN-Aadhaar link tool │ ├── registry/ │ │ └── tool_registry.py # Auto tool discovery & registration │ ├── clients/ │ │ └── kyc_api_client.py # KYC API client with retry logic │ ├── auth/ │ │ └── jwt_manager.py # JWT token management │ ├── cache/ │ │ └── redis_cache.py # Redis caching layer │ ├── models/ │ │ ├── requests.py # Request models │ │ └── responses.py # Response models │ └── utils/ │ ├── logger.py # Structured logging │ └── rate_limiter.py # Rate limiting ├── config/ │ └── settings.py # Configuration management ├── metadata/ │ └── tools/ # Tool metadata JSON files │ ├── pan_verification.json │ └── pan_aadhaar_link.json ├── Dockerfile ├── docker-compose.yml ├── requirements.txt └── .env.example

Installation

Prerequisites

Python 3.11+
Redis (for caching)
KYC API credentials

Local Setup

Clone the repository

git clone <repository-url> cd kyc-mcp-server

Create virtual environment

python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate

Install dependencies

pip install -r requirements.txt

Configure environment

cp .env.example .env # Edit .env with your credentials

Start Redis

docker run -d -p 6379:6379 --name kyc-redis redis:7-alpine

Run the server

python -m src.main

Docker Setup

Configure environment

cp .env.example .env # Edit .env with your credentials

Build and run with Docker Compose

docker-compose up -d

View logs

docker-compose logs -f kyc-mcp-server

Stop the server

docker-compose down

Configuration

All configuration is managed through environment variables. See .env.example for all available options.

Key Configuration Options

Variable	Description	Default
`KYC_API_BASE_URL`	KYC API base URL	Required
`KYC_API_KEY`	KYC API key	Required
`KYC_JWT_SECRET`	JWT secret for token generation	Required
`REDIS_HOST`	Redis host	`localhost`
`REDIS_PORT`	Redis port	`6379`
`CACHE_ENABLED`	Enable caching	`true`
`CACHE_DEFAULT_TTL`	Default cache TTL (seconds)	`3600`
`RATE_LIMIT_ENABLED`	Enable rate limiting	`true`
`RATE_LIMIT_PER_MINUTE`	Requests per minute	`60`
`RATE_LIMIT_PER_HOUR`	Requests per hour	`1000`
`LOG_LEVEL`	Logging level	`INFO`

Usage

Using MCP Client

# Connect to the server mcp-client connect stdio -- python -m src.main # List available tools mcp-client list-tools # Call a tool mcp-client call-tool verify_pan '{ "pan": "XXXPX1234A", "name_as_per_pan": "John Doe", "date_of_birth": "01/01/1990", "consent": "Y", "reason": "KYC verification" }'

Example Tool Calls

PAN Verification

{ "tool": "verify_pan", "arguments": { "pan": "XXXPX1234A", "name_as_per_pan": "John Doe", "date_of_birth": "01/01/1990", "consent": "Y", "reason": "Customer onboarding" } }

Response:

{ "pan": "XXXPX1234A", "category": "individual", "status": "valid", "remarks": null, "name_match": true, "dob_match": true, "aadhaar_seeding_status": "y", "verified_at": 1234567890, "_cached": false }

PAN-Aadhaar Link Check

{ "tool": "check_pan_aadhaar_link", "arguments": { "pan": "XXXPX1234A", "aadhaar_number": "123456789012", "consent": "Y", "reason": "Link verification" } }

Response:

{ "linked": true, "status": "y", "message": "PAN and Aadhaar are linked", "checked_at": 1234567890, "_cached": false }

Adding New Tools

The server uses an auto tool registry system. To add a new tool:

Create tool class in src/tools/

from src.tools.base_tool import BaseTool class NewTool(BaseTool): def get_name(self) -> str: return "new_tool_name" async def execute(self, params): # Implementation pass

Create metadata file in metadata/tools/

{ "name": "new_tool_name", "description": "Tool description", "input_schema": { ... }, "output_schema": { ... } }

Register tool in src/main.py

new_tool = NewTool(api_client=self.api_client) tool_registry.register_tool(new_tool)

Restart server - Tool is automatically available!

Error Handling

The server provides comprehensive error handling:

VALIDATION_ERROR: Invalid input parameters
RATE_LIMIT_EXCEEDED: Rate limit exceeded
TOOL_NOT_FOUND: Unknown tool requested
EXECUTION_ERROR: Tool execution failed
SERVICE_UNAVAILABLE: External API unavailable

All errors include descriptive messages and appropriate error codes.

Monitoring

Logs

Structured JSON logs are output to stdout:

{ "event": "tool_executed_successfully", "tool": "verify_pan", "timestamp": "2024-01-20T10:30:00Z", "level": "info" }

Metrics

The server exposes Prometheus-compatible metrics on port 9090 (configurable).

Performance

Cache Hit Rate: >70% for repeated queries
Response Time: <500ms (p95) for uncached requests
Response Time: <10ms (p95) for cached requests
Concurrent Requests: Supports 100+ concurrent requests

Security

JWT-based authentication for API calls
Input validation using Pydantic
Rate limiting to prevent abuse
Secure credential management via environment variables
No sensitive data in logs

Troubleshooting

Redis Connection Failed

# Check if Redis is running docker ps | grep redis # Start Redis docker run -d -p 6379:6379 redis:7-alpine

Rate Limit Exceeded

# Increase rate limits in .env RATE_LIMIT_PER_MINUTE=120 RATE_LIMIT_PER_HOUR=2000

Tool Not Found

# Check metadata files exist ls metadata/tools/ # Check tool registration in logs docker-compose logs kyc-mcp-server | grep "tool_registered"

Development

Running Tests

# Install dev dependencies pip install -r requirements-dev.txt # Run tests pytest tests/ -v # Run with coverage pytest tests/ --cov=src --cov-report=html

Code Quality

# Format code black src/ # Lint code ruff check src/ # Type checking mypy src/

License

[Add your license here]

Support

For issues and questions:

Create an issue in the repository
Contact: [your-email@example.com]

Acknowledgments

Built with:

KYC MCP Server

KYC MCP Server

Features

Implemented Tools

1. PAN Verification (`verify_pan`)

2. PAN-Aadhaar Link Check (`check_pan_aadhaar_link`)

Architecture

Installation

Prerequisites

Local Setup

Docker Setup

Configuration

Key Configuration Options

Usage

Using MCP Client

Example Tool Calls

PAN Verification

PAN-Aadhaar Link Check

Adding New Tools

Error Handling

Monitoring

Logs

Metrics

Performance

Security

Troubleshooting

Redis Connection Failed

Rate Limit Exceeded

Tool Not Found

Development

Running Tests

Code Quality

License

Support

Acknowledgments

Related Resources

New MCP Servers

MCP directory API

KYC MCP Server

Features

Implemented Tools

1. PAN Verification (verify_pan)

2. PAN-Aadhaar Link Check (check_pan_aadhaar_link)

Architecture

Installation

Prerequisites

Local Setup

Docker Setup

Configuration

Key Configuration Options

Usage

Using MCP Client

Example Tool Calls

PAN Verification

PAN-Aadhaar Link Check

Adding New Tools

Error Handling

Monitoring

Logs

Metrics

Performance

Security

Troubleshooting

Redis Connection Failed

Rate Limit Exceeded

Tool Not Found

Development

Running Tests

Code Quality

License

Support

Acknowledgments

Related Resources

New MCP Servers

MCP directory API

1. PAN Verification (`verify_pan`)

2. PAN-Aadhaar Link Check (`check_pan_aadhaar_link`)