KYC Compliance MCP Server

An agentic KYC/AML compliance system built on the Model Context Protocol (MCP). An MCP server exposes compliance checks as tools, and an AI model (Claude) decides which tools to call and in what order to perform customer due diligence — wrapped in a host layer that enforces the legally non-negotiable checks, validates the model's decision, and writes a tamper-evident audit log.

The point: the model does the discretionary investigation; deterministic code enforces the mandatory controls and records everything. That hybrid — a reasoning core inside compliance rails — is the difference between a demo and something defensible in a regulated setting.

Note: this is a proof-of-concept for demonstrating MCP orchestration and compliance architecture, not a production compliance system. See Notes / limitations below — several data sources are deliberately stubbed as honest integration points because the real data is licensed or legally gated.

Architecture

applicant ─► HOST: enforce mandatory sanctions screen (always runs)
                │
                ▼
            CLAUDE orchestrates the rest — picks tools, reads results, decides:
            verify_identity · assess_industry_risk · lookup_business ·
            screen_pep · assess_country_risk
                │
                ▼
            HOST: validate the model's decision against the gathered facts
                  (overrides can only make the outcome STRICTER, never looser)
                │
                ▼
            FINAL DECISION  +  hash-chained AUDIT LOG (tamper-evident)

The decision is one of PASS / ESCALATE / FAIL, where ESCALATE routes the case to a human for enhanced due diligence — the honest posture for an AI first-pass triage tool.

Risk score

Each result carries a risk score from 0 to 10 where HIGHER means MORE risky (this is the opposite direction of a credit score, so it can be counterintuitive):

• 0–3 low risk — e.g. a clean standard-industry business with domestic owners
• 4–6 moderate risk — elevated factors present, warrants attention
• 7–10 high risk — a hard gate hit (sanctions, prohibited industry), failed identity validation, or high country risk

A low score does not guarantee a PASS: an unresolved integration-point check (e.g. PEP) can still force an ESCALATE even at 2/10, because final clearance requires that check be completed manually.

Tools

Tool	What it does	Backed by
screen_sanctions	Screens names against the live OFAC SDN list	treasury.gov OFAC SDN (live)
verify_identity	Structural SSN / driver's-license / address validation	SSA rules + state DL formats (live, no key)
assess_country_risk	0–10 country risk score + band	World Bank indicators (+ proxy overrides)
lookup_business	Verifies a company is an SEC-registered filer	SEC EDGAR (live, no key)
assess_industry_risk	PROHIBITED / STATE_CONDITIONAL / ELEVATED / STANDARD	NAICS-keyed rules (built in)
screen_pep	Politically Exposed Person screening	Integration-point stub (see caveats)

The industry tool encodes real regulatory nuance: weapons are a hard gate; cannabis is state-conditional (legal-program states → escalate for enhanced due diligence; non-program states → decline); crypto, gambling, cash-intensive, etc. are elevated-risk inputs the model weighs.

Why this is an MCP showcase

The model orchestrates the calls. Given a business applicant it will typically call assess_industry_risk first (a PROHIBITED result can short-circuit to FAIL), then screen_sanctions on the company and each owner, lookup_business to verify the entity, and assess_country_risk on any non-US owner. For a personal applicant it calls and verify_identity. That orchestration is the model's, not the code's — which is what distinguishes MCP from a fixed serverless pipeline.

Web UI

A React UI (ui/) drives the agent over an Express backend. It shows the decision and the tool-call sequence ("how the agent investigated") to anyone, while detailed findings and the audit trace are officer-gated behind a passcode — demonstrating both the orchestration and an access-control boundary. See UI_SETUP.md to run it.

Run it

npm install
npm run build

Test with the MCP Inspector (recommended first step)

npm run inspect

This opens the Inspector UI (port 6274). You can fire each tool manually and watch the raw JSON-RPC traffic — the fastest way to confirm the tools work before wiring a host.

Wire into Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "kyc-compliance": {
      "command": "node",
      "args": ["/absolute/path/to/kyc-mcp-server/dist/index.js"]
    }
  }
}

Restart Claude Desktop, then ask it to "run KYC due diligence on Acme LLC, a firearms retailer in Texas with owners Jane Doe and John Roe" — it will discover and call the tools.

Compliance guardrails (the host layer)

"The model decides which tools to call" is great for capability but unacceptable on its own in a regulated setting — a missed sanctions check is a violation, not a bug. The src/host/ layer wraps the model so it reasons inside deterministic rails:

• Mandatory-screening enforcement (orchestrator.ts) — sanctions screening (and, for businesses, industry classification) always run, executed by the host, regardless of whether the model would have chosen to call them. The model never gets to skip a required check.
• Output validation (validation.ts) — the model's PASS/FAIL/ESCALATE is checked against the hard screening facts. A potential OFAC match or a PROHIBITED industry forces FAIL even if the model said PASS; a state-conditional industry or high country risk forces at least ESCALATE. Overrides only ever make the outcome stricter, never looser.
• Hash-chained audit log (audit.ts) — every request, tool call, tool result, model decision, override, and final decision is written to an append-only, SHA-256 hash-chained log. Editing any past entry breaks the chain and is detectable — this is what you hand an examiner to reconstruct why any customer was approved or declined.

The division of labor: the model orchestrates the discretionary analysis; the code enforces the non-negotiable checks and records everything. That hybrid — reasoning core, deterministic guardrails — is the difference between a demo and a system you could defend in a compliance review.

Screenshots

Clean business applicant (PASS): All checks pass; decision is PASS at 3/10 risk. Escalation due to lack of PEP integration. <img width="1266" height="856" alt="Pass Clean Business" src="https://github.com/user-attachments/assets/0271baa6-c9d3-4c17-9269-67be8dac85c7" /> <img width="1069" height="854" alt="Pass Clean_Details" src="https://github.com/user-attachments/assets/d0754ae6-bc7f-4a0d-98c9-759f0e7e7b6d" />

State-conditional industry (ESCALATE): Cannabis in California triggers state-conditional escalation for enhanced due diligence. <img width="895" height="855" alt="Escalate State Condl Business" src="https://github.com/user-attachments/assets/5b31ccb3-75d2-40e3-8cdb-8c19cc4c32e2" />

Prohibited industry (FAIL): Weapons dealer hard-gate; decision is FAIL at 10/10 risk. <img width="1252" height="819" alt="Fail Prohibited Business" src="https://github.com/user-attachments/assets/ec83c72b-41f0-4e71-bff2-c178ff064cda" />

Officer-gated findings: Detailed per-tool findings and audit trace are revealed only after entering the passcode. <img width="979" height="851" alt="Gated Detail with PEP person" src="https://github.com/user-attachments/assets/efda214a-0728-480f-9516-72f974b57525" />

Notes / limitations

• Sanctions matching is simple (token match, not fuzzy/phonetic). Real screening adds secondary identifiers (DOB, nationality) to cut false positives. The architecture — live government data driving the decision — is the point. (You'll see common names like "Maria Garcia" produce false-positive potential matches; the system fails safe by escalating, which is the correct direction.)
• Country risk uses a small override table plus a World Bank indicator fallback, as a public proxy for a licensed country-risk feed. The country-name→ISO lookup is thin; passing ISO-2 codes (e.g. "BR") is most reliable.
• Business lookup covers SEC filers only. lookup_business uses SEC EDGAR (free, no key), which only contains public / SEC-registered companies. A no-match is EXPECTED for most small private LLCs and is NOT disqualifying — the tool says so in its note. Full private-entity coverage requires OpenCorporates (paid) or per-state Secretary-of-State integration (California has a key-gated API; Delaware is CAPTCHA-protected with paywalled status). Those are defined as production integration points, not built here.
• Identity verification is structural only. verify_identity validates SSN format/range (SSA rules), driver's-license format per state, and address presence — it catches fabricated or malformed identifiers, but does NOT confirm they belong to the person. Authoritative match (SSN-to-name via SSA eCBSV, DL-to-record via AAMVA/DMV) is legally gated to permitted entities with consumer consent, so it's a documented production integration point.
• PEP screening is an integration point, not live. screen_pep returns an INTEGRATION_POINT status, not a clean result. Credible PEP data is licensed — OpenSanctions has strong PEP coverage but its API requires a key/commercial license, and World-Check / Dow Jones / LexisNexis are commercial. PEP is a required KYC control, so the tool seam is built and the model is told to treat the result as "manual EDD required" rather than "no PEP found." Production supplies provider credentials.

Roadmap

• Wire EU/UK consolidated lists into screen_sanctions (the parameter already exists)
• Fuzzy name matching with secondary identifiers
• A thin host backend + the existing React UI as the front end