ComplianceGate-MCP: Payments Screening & Ingestion Gateway

ComplianceGate-MCP is a deterministic, full-stack trade and payment compliance gateway and Model Context Protocol (MCP) server. It parses SWIFT MT and ISO 20022 MX payment messages, evaluates parties through a deterministic multi-script screening engine, identifies missing originator/beneficiary compliance fields, and enforces human-in-the-loop review governance with tamper-evident audit trails.

1. Core Architecture & Standards Coverage

A. Message Families & Tested Profiles

1. SWIFT MT103 (Single Customer Credit Transfer): Standard, STP, and REMIT parsing (:20:, :23B:, :32A:, :50a, :52a, :56a, :57a, :59a, :70, :71a).

2. SWIFT MT202 COV (Cover Payment): Handles both Sequence A (Interbank routing) and Sequence B (Underlying commercial customer parties) to prevent cover sanctions evasion.

3. ISO 20022 pacs.008.001.08 / .09 (FI to FI Customer Credit Transfer): Safe bounded XML parsing; extracts Debtor, Creditor, Ultimate parties, Agents, and structured postal addresses.

4. ISO 20022 pacs.009 COV (Financial Institution Transfer with Cover): Extracts both direct interbank FI settlement parties and underlying commercial cover parties (UndrlygCstmrCdtTrf).

5. ISO 20022 pacs.004.001.09 / .10 (Payment Return): Captures return reason codes, separates original debtor/creditor from returning institutions, and re-screens the return path.

6. ISO 20022 pain.001.001.09 / .10 (Corporate Initiation): Extracts and screens ALL payment transactions across multi-payment <PmtInf> / <CdtTrfTxInf> batches.

7. Generic Envelope Fallback: Safely parses unprofiled SWIFT FIN blocks (MT101, MT202 non-cov, MT940) and ISO 20022 documents (camt.053, pacs.002) without throwing schema exceptions.

B. 2-Dimensional Evaluation Matrix

Every transaction query produces two independent dimensions:

1. Coverage Status:

   • COMPLETE: All required watchlists are fresh and verified.

   • PARTIAL_STALE: One or more secondary lists are stale, but available lists were evaluated. (Hard invariant: Stale secondary lists never suppress or mask an exact identifier candidate hit found on an active list).

   • INSUFFICIENT: A mandatory watchlist is unindexed or missing.

2. Finding Severity:

   • EXACT_IDENTIFIER_MATCH: Candidate hit on a typed identifier (SWIFT BIC, LEI, Tax ID, Passport). Automated release or agent override is prohibited (HUMAN_ONLY).

   • FUZZY_NAME_CANDIDATE: Algorithmic token-similarity match exceeding threshold.

   • NO_MATCH_FOUND: No matching record found. Explicitly labeled NO_MATCH_FOUND, never "Cleared" or "Approved".

C. Missing Data & Travel Rule Engine

Audits transactions against configurable compliance profiles (e.g. FATF Recommendation 16 cross-border wire standards) flagging missing originator/beneficiary physical addresses, national identity numbers, or destination account numbers.

Related MCP server: ISO20022Oracle

2. Local Run & Test Commands

Run Development Server

npm run dev

Starts the full-stack server on http://localhost:3000 with the Streamable HTTP MCP endpoint at http://localhost:3000/mcp.

Run Automated Test Suite

npm test

Executes the comprehensive CLI test suite (src/tests/payments_gateway.test.ts), verifying:

• SWIFT MT103 and MT202 COV dual-sequence parsing

• ISO 20022 pacs.008, pacs.009 COV, pacs.004 return, and pain.001 multi-payment batch parsing

• Generic envelope fallback handling

• Configurable missing data rules

• Multi-script Unicode normalization (Arabic, Chinese, Cyrillic, accented Latin)

• Exact identifier candidate matching (BIC, LEI)

• List freshness gate & severity independence

• Server-held result reference tokens (ref_<uuid>) and forgery prevention

• Case adjudication validation with mandatory review rationale ($\ge 10$ chars)

• Tamper-evident SHA-256 hash-chain verification

• Client remote engine adapter unconfigured failure contract

• Official MCP Client protocol (initialize, tools/list, tools/call)

• MCP sensitive data redaction for agent contexts

3. Official Model Context Protocol (MCP) Integration

Streamable HTTP Endpoint

• URL: POST /mcp (or POST /api/mcp)

• Protocol: JSON-RPC 2.0

• Supported Methods: initialize, tools/list, tools/call

Local Terminal Stdio Runner

For local CLI agents or desktop MCP clients (e.g. Claude Desktop), launch:

npx tsx src/server/mcpStdio.ts

Registered Tools

1. extract_payment_parties: Extracts standardized canonical parties, amounts, and provenance from raw MT/MX.

2. screen_payment: Screens payment parties against registered watchlists; returns 2D status matrix and server reference token.

3. route_payment_alert: Validates a server-held reference token (ref_<uuid>).

4. audit_missing_data: Audits transaction against missing-data profiles (e.g. FATF Rec 16).

5. list_health: Queries snapshot timestamps, digests, and freshness states.

6. get_payment_evidence: Exports verified tamper-evident audit bundle.

7. generate_test_payments: Emits synthetic test payments.

4. Google Cloud Deployment Prerequisites & Budget Boundaries

Environment Status

• Current Project: gen-lang-client-0475955540

• Billing Status: Currently no billing account is linked.

• Spending Ceiling: Target is $\le$ £10/month.

Deployment Commands (For Execution when Billing is Linked)

# 1. Authenticate with Google Cloud
gcloud auth login

# 2. Set active project
gcloud config set project gen-lang-client-0475955540

# 3. Build container using Cloud Build
gcloud builds submit --tag gcr.io/gen-lang-client-0475955540/compliancegate-mcp:latest

# 4. Deploy to Cloud Run (Scale-to-zero, 512MB RAM, max 1 instance)
gcloud run deploy compliancegate-mcp \
  --image gcr.io/gen-lang-client-0475955540/compliancegate-mcp:latest \
  --platform managed \
  --region europe-west2 \
  --allow-unauthenticated \
  --memory 512Mi \
  --max-instances 1 \
  --port 3000

Cost Controls

• Cloud Run scales down to zero instances when idle.

• Real commercial watchlists (Dow Jones, World-Check) and live vessel/price feeds remain explicitly

5. License

This project is licensed under the MIT License — see the LICENSE file for details.