.codex-plugin— mcp server

<div align="center"> <h1>@cyanheads/sanctions-screening-mcp-server</h1> <p><b>Screen names against the consolidated OFAC, EU, UK, and UN sanctions lists and resolve legal entities against GLEIF, fuzzy-matched offline over a local SQLite + FTS5 mirror. A screening aid, not a compliance determination.</b> <div>6 Tools • 3 Resources • 1 Prompt</div> </p> </div>

<div align="center">

</div>

<div align="center">

Public Hosted Server: https://sanctions-screening.caseyjhand.com/mcp

</div>

[!IMPORTANT] This is a screening aid, not legal or compliance certification. Every tool returns potential matches with a transparent score and source provenance — never a verdict. A hit means "review this candidate against the official source"; an empty result never means "cleared." Real sanctions compliance is a legal process — it requires human review and a qualified compliance determination. This server feeds that process; it does not perform it, and its output is not a compliance record.

Overview

sanctions-screening-mcp-server turns the world's open sanctions data plus the global legal-entity registry into one screening-and-resolution workflow, answered offline and fuzzy-matched. It screens a name against the consolidated US (OFAC), EU, UK, and UN sanctions lists at once, and resolves legal entities against the GLEIF Legal Entity Identifier (LEI) database with corporate-ownership tracing.

All sources are bulk-downloadable, keyless, and clear for redistribution. The server mirrors them to a local SQLite + FTS5 index and serves matches from that mirror — no live API key, no per-request rate limit on the hot path. The agent sees screening verbs (screen_name, resolve_entity, trace_ownership); which list answered a query surfaces only as provenance on each hit.

The matching model is transparent by design: strict token matching first (exact-normalized, then all-tokens-present via FTS5), with a scored Jaro-Winkler + phonetic fuzzy fallback. Approximate hits carry the raw Jaro-Winkler similarity (0–1) — a real measurement, never a fabricated "confidence percentage."

Tools

Six tools organized around two workflows — screen a name against the watchlists, and resolve a legal entity to its global identifier and ownership graph:

sanctions_screen_name

The 80% entry point — "is this entity on a watchlist?"

• Fans out across all four sanctions lists (OFAC SDN + Consolidated, EU, UK, UN) in one call; the source surfaces only as provenance per hit
• Alias-aware: matches against every published primary name, a.k.a., and f.k.a., not just the canonical name
• Strict mode (default): exact-normalized equality, then all-tokens-present via FTS5 — handles word-order swaps and missing interior words with no fuzzy library
• Fuzzy mode (opt-in, or automatic when strict finds nothing): adds Jaro-Winkler similarity and Double-Metaphone phonetic matching for transliteration-class misses
• Hits labeled exact / strong / approximate; approximate hits carry the raw Jaro-Winkler score (0–1)
• Filter by entity type, source list subset, similarity floor (min_score), and result limit
• On an empty result, returns guidance on how to broaden — and states explicitly that no match is not a clearance

sanctions_get_designation

The drill-in after sanctions_screen_name surfaces a candidate.

• Full normalized record by source + entry_id (the sourceEntryId from a screen hit)
• All published aliases, structured identifiers (passport / national ID / tax / registration), addresses, dates and places of birth, nationalities, sanctioning program, legal basis, and designation date
• Preserves source sparsity — missing fields mean the source omitted them; the record is never padded with fabricated data

sanctions_resolve_entity

The bridge from a free-text counterparty name to a stable LEI that the entity tools key off.

• Resolves a company / organization name to ranked GLEIF LEI candidates
• Optional ISO 3166-1 alpha-2 jurisdiction filter and registration-status filter (issued default, lapsed, or any)
• Same strict-then-fuzzy matching model as name screening; approximate hits carry the raw Jaro-Winkler score
• Matches against legal names and published other/trading names

sanctions_get_entity

Who is this legal entity — plus a watchlist cross-reference in the same call.

• Full GLEIF Level 1 record: legal name, other/trading names, legal and headquarters addresses, registration status, jurisdiction, registration authority and ID, last-update date
• Cross-references the entity's legal name against all loaded watchlists (strict match only — auto-fuzzy on a generic legal name would flood the result with single-common-token false positives)
• LEI input is regex-validated (20 chars: 18 alphanumerics + 2 check digits)

sanctions_trace_ownership

Beneficial-ownership screening — the cross-source workflow that single-list tools can't do.

• Traverses the GLEIF Level 2 ownership graph breadth-first to a bounded depth (1–5)
• direction: walk parents (who owns it), children (what it owns), or both
• Returns nodes (with role and depth) and directed ownership edges with relationship type
• screenNodes: true screens every entity in the graph against all watchlists — "is anyone in this ownership chain sanctioned?"
• Per-node screen is strict-only and reports screenedNodeCount / flaggedNodeCount so a caller can see coverage at a glance

Resources and prompts

All resource data is also reachable via the tools, which are the primary path for tool-only MCP clients. The resources are a convenience for resource-capable clients only.

Source lists

The server aggregates five upstream sources behind the screening surface. All are bulk, keyless, and clear for redistribution.

The UK source is the UK Sanctions List (UKSL), the single authoritative UK source since the OFSI Consolidated List closed on 28 January 2026.

First run: populate the mirror

The mirror is not bundled — the sanctions lists and the GLEIF golden copy are downloaded and normalized on first run. Run the init lifecycle script out-of-band before screening:

bun run mirror:init

This harvests all four sanctions lists in full, rebuilds the per-alias name index, then streams the GLEIF golden copy (Level 1 entities + Level 2 ownership relationships). It is resumable and intended to run once, off the request path.

Set SANCTIONS_INIT_SKIP_GLEIF=1 on mirror:init to load only the (small) sanctions lists and skip GLEIF.

GLEIF memory note: the GLEIF Level 1 ingest is the memory-heavy leg — the full golden copy is roughly 3.3M LEI records (~490 MB compressed) and ~890 MB of resident memory during the streaming ingest. The four sanctions lists and the GLEIF deltas / Level 2 ownership data are light by comparison. Size the host accordingly for mirror:init, or skip GLEIF with SANCTIONS_INIT_SKIP_GLEIF=1 if you only need watchlist screening.

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool, resource, and prompt definitions — single file per primitive, framework handles registration and validation
• Unified error handling — handlers throw, framework catches, classifies, and formats
• Typed error contracts with recovery hints (mirror_not_ready, designation_not_found, lei_not_found)
• Pluggable auth: none, jwt, oauth (defaults to none — all data is public)
• Structured logging with optional OpenTelemetry tracing
• STDIO and Streamable HTTP transports

Sanctions-specific:

• Multi-source, workflow-organized surface — one screen fans out across OFAC, EU, UK, and UN internally; sources surface only as provenance
• Local SQLite + FTS5 mirror via the framework MirrorService — offline, no live API key, no per-request rate limit
• Normalized common schema across the four sanctions lists, with a denormalized per-alias name index (one row per name and per alias) so a query matches any of an entity's names in one FTS scan
• Strict-then-fuzzy matching: exact-normalized → all-tokens-present (FTS5) → Jaro-Winkler + Double-Metaphone, capped to bound work on short queries
• GLEIF Level 1 + Level 2 ingest for entity resolution and beneficial-ownership tracing

Agent-friendly output:

• Real signal, not synthetic confidence — approximate hits carry the raw Jaro-Winkler similarity (0–1); strict hits carry a match_type (exact / strong), never a fabricated percentage
• Provenance on every hit — source list, sanctioning program, designation date, the exact name/alias that matched, and its type (primary / aka / fka / low-quality-aka)
• Decision-support caveat carried in every screening tool's output — a hit is a candidate to verify, an empty result is not a clearance
• Freshness surfaced via sanctions_list_sources — each source's record count and the mirror's as-of timestamp, so an agent can judge staleness

Getting started

Public Hosted Instance

A public instance is available at https://sanctions-screening.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP, with this client config:

{
  "mcpServers": {
    "sanctions-screening-mcp-server": {
      "type": "streamable-http",
      "url": "https://sanctions-screening.caseyjhand.com/mcp"
    }
  }
}

Self-hosted / local

Add the following to your MCP client configuration file. The server is offline-first — populate the mirror with bun run mirror:init before screening (see Source lists).

{
  "mcpServers": {
    "sanctions-screening-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/sanctions-screening-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "sanctions-screening-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/sanctions-screening-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.3 or higher (or Node.js v24+).
• Disk for the local mirror (the populated SQLite files; GLEIF Level 1 dominates). No API key for any source.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/sanctions-screening-mcp-server.git

1. Navigate into the directory:

cd sanctions-screening-mcp-server

1. Install dependencies:

bun install

1. Configure environment:

cp .env.example .env
# edit .env if you need to override defaults (all optional)

1. Populate the mirror:

bun run mirror:init

Configuration

All sources are keyless — there is no required API key. Every variable below is optional with a sensible default.

Source URLs default to the verified official endpoints; overrides exist for testing and for pinning a mirror in restricted environments. The EU "token" is a static public path component, not a credential.

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run:

  # One-time build
  bun run rebuild

  # Run the built server
  bun run start:stdio
  # or
  bun run start:http

• Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, security, changelog sync
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t sanctions-screening-mcp-server .
docker run --rm -p 3010:3010 -v sanctions-data:/usr/src/app/data sanctions-screening-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/sanctions-screening-mcp-server. The image runs under Bun, so the mirror uses bun:sqlite (no native build). Mount a volume at the mirror path (/usr/src/app/data by default) so the populated mirror survives container restarts, and run bun run mirror:init inside the container (docker exec) to populate it. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Development guide

See CLAUDE.md/AGENTS.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
• Register new tools and resources via the barrels in src/mcp-server/*/definitions/index.ts
• Wrap external sources: validate raw → normalize to the common schema → return the output schema; never fabricate fields a source omits, and never synthesize a confidence score

Attribution

This server redistributes open data from the following sources, cited here per their terms:

• OFAC SDN and Consolidated lists — US Department of the Treasury, Office of Foreign Assets Control (US Government public domain).
• EU Consolidated Financial Sanctions List — European Commission / EEAS (freely redistributable).
• UK Sanctions List — UK Foreign, Commonwealth & Development Office, licensed under the Open Government Licence v3.0 (attribution required).
• UN Security Council Consolidated List — United Nations Security Council (freely redistributable).
• GLEIF LEI data — Global Legal Entity Identifier Foundation, CC0 1.0 Universal.

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.