KYC MCP Server

A Model Context Protocol (MCP) server for KYC (Know Your Customer) customer verification, built with .NET 10 Web API. Exposes three compliance tools — document validation, identity verification, and risk assessment — over the MCP JSON-RPC 2.0 transport, making it ready to plug directly into Claude Desktop, Claude API tool use, or any MCP-compatible AI system.

Features

Production-ready qualities:

• Structured logging via Serilog (console + rolling file)
• Global error handling mapped to JSON-RPC 2.0 error codes
• IHttpClientFactory with per-API timeout and API-key injection
• Strongly-typed configuration with environment-variable override
• Swagger / OpenAPI UI in development
• CORS pre-configured for Claude Desktop integration
• 20+ xUnit unit tests with Moq and FluentAssertions

Project Structure

kyc-mcp-server/
├── KYCMcpServer.sln
├── .env.example               # All supported environment variables
├── .gitignore
├── src/
│   ├── KYCMcpServer.Core/     # Domain models & interfaces (no dependencies)
│   │   ├── Models/
│   │   │   ├── Mcp/           # McpRequest, McpResponse, McpTool
│   │   │   └── Kyc/           # DocumentValidation, IdentityVerification, RiskAssessment
│   │   └── Interfaces/        # IDocumentValidationService, IIdentityVerificationService …
│   │
│   ├── KYCMcpServer.Services/ # Business logic implementations
│   │   ├── DocumentValidationService.cs
│   │   ├── IdentityVerificationService.cs
│   │   ├── RiskAssessmentService.cs
│   │   ├── McpToolHandler.cs  # Routes MCP tool calls to services
│   │   └── BankingApiClient.cs
│   │
│   └── KYCMcpServer.Api/      # ASP.NET Core Web API host
│       ├── Controllers/McpController.cs
│       ├── Middleware/ErrorHandlingMiddleware.cs
│       ├── Configuration/AppSettings.cs
│       └── Program.cs
│
└── tests/
    └── KYCMcpServer.Tests/    # xUnit unit tests

Prerequisites

Install .NET: https://dotnet.microsoft.com/download

Setup

1. Clone and configure

git clone https://github.com/your-org/kyc-mcp-server.git
cd kyc-mcp-server
cp .env.example .env

Edit .env and fill in your API keys:

BANKING_API_KEY=your_key_here
IDENTITY_VERIFICATION_API_KEY=your_key_here
DOCUMENT_VERIFICATION_API_KEY=your_key_here
AML_API_KEY=your_key_here

Note: Without real API keys the server still runs. Document/identity checks will throw BankingApiException and return a "service unavailable" note — which is the correct fallback behaviour for missing integrations.

2. Restore dependencies

dotnet restore

3. Run the server

dotnet run --project src/KYCMcpServer.Api

The server starts on http://localhost:5000 (or the port in ASPNETCORE_URLS).

• Swagger UI: http://localhost:5000/swagger
• Health check: http://localhost:5000/health
• Tool list (REST): http://localhost:5000/tools

4. Run tests

dotnet test

MCP Protocol Usage

Initialize

POST /
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "clientInfo": { "name": "claude-desktop", "version": "1.0" }
  }
}

List tools

POST /
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

Call a tool

validate_document

POST /
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "validate_document",
    "arguments": {
      "customer_id": "CUST001",
      "document_type": "Passport",
      "document_number": "AB123456",


... [View full README on GitHub](https://github.com/courpaliselizabeth-hub/kyc-mcp-server#readme)