Skip to main content
Glama
CTD-Techs

KYC MCP Server

by CTD-Techs
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

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

  1. Clone the repository

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

  1. Create virtual environment

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

  1. Install dependencies

pip install -r requirements.txt

  1. Configure environment

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

  1. Start Redis

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

  1. Run the server

python -m src.main

Docker Setup

  1. Configure environment

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

  1. Build and run with Docker Compose

docker-compose up -d

  1. View logs

docker-compose logs -f kyc-mcp-server

  1. 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:

  1. 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

  1. Create metadata file in metadata/tools/

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

  1. Register tool in src/main.py

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

  1. 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:

Acknowledgments

Built with:

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/CTD-Techs/CTD-MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server