Sanctions Screening Mcp Server

Overview

Sanctions screening and legal-entity resolution over the consolidated OFAC, EU, UK, and UN lists plus the GLEIF LEI registry, matched offline against a local mirror. Screen a name for potential watchlist hits, resolve a company to its LEI, and trace its ownership chain. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

[!IMPORTANT] A screening aid, not a compliance determination. Every result is a potential match with a transparent score and source provenance, never a verdict. A hit is a candidate to verify against the official source; an empty result is never a clearance. Sanctions compliance needs human review and a qualified determination. This server feeds that process and does not perform it.

Tools

Resources

All resource data is also reachable through the tools, for clients that don't surface resources.

Prompts

Capability reference

sanctions_screen_name _tool

• name in any script (at most 64 words and 1,024 characters) plus optional sources, entityType, and minScore filters; matchMode is strict (default) or fuzzy, and strict falls back to fuzzy when it finds nothing; up to 100 hits per page (limit, default 25) with offset
• Hits carry source, sourceEntryId, the list's published referenceNumber where it has one, matchedName with its matchedNameType, and matchType (exact / strong / approximate); approximate hits add the raw Jaro-Winkler score (0–1) and queryTokenCoverage
• totalAvailable, hasMore, and nextOffset page the rest; totalAvailableBasis marks the count exact or a lower_bound

sanctions_screen_identifier _tool

• value (an identifier as you hold it) plus optional type (any default, imo, swift_bic, digital_currency_address, passport, national_id) and sources
• Exact match after normalization, never fuzzy and never scored: spacing, letter case, and - . / are ignored; an IMO number matches with or without its IMO prefix; a SWIFT/BIC compares on its first eight characters, so a branch BIC11 matches its institution's BIC8; a wallet address folds case only for hex (0x…), bech32 (bc1…, ltc1…, bnb1…), and cashaddr encodings, while base58 addresses compare exactly
• type matches on each list's published label: imo is OFAC Vessel Registration Identification, UK IMO Number, and EU IMO (vessel identification); swift_bic is SWIFT/BIC and SWIFT BIC; digital_currency_address is OFAC Digital Currency Address - <code>; passport and national_id cover the lists' passport and national-ID labels. any also reaches every label with no category (MMSI, call signs, tail numbers, tax and registration numbers, email, websites)
• One hit per designation, ordered by list then entry ID, each with the matchedIdentifiers that matched as published; not paged. An identifier a list prints only in free-text remarks, or bundled with other numbers in one field, does not match

sanctions_get_designation _tool

• source (ofac_sdn, ofac_consolidated, eu, uk, un) and entryId: the sourceEntryId from a screening hit, or the reference number the list publishes (UN QDe.004, EU EU.27.28, UK OFSI Group ID 14196). Matched trimmed and case-insensitive, entry ID first; a reference number two designations share fails as reference_ambiguous, naming both
• Returns referenceNumber beside sourceEntryId where the list publishes one; OFAC publishes none, its entry ID being its published number
• All published aliases, identifiers, addresses, dates and places of birth, nationalities, program, legal basis, and designation date; a field the source omitted is absent, never filled in
• Identifiers cover identity documents plus the SWIFT/BIC codes, digital-currency addresses, vessel call signs, aircraft tail and serial numbers, phone numbers, email addresses, and websites a list publishes, each typed with the list's own label and its value verbatim
• Dates of birth are ISO 8601 at the precision the source published (1952-10-07, 1946-08, 1938, or an interval such as 1955/1957), with circa: true where the source marks one approximate; designationDate is the source's own designation date as YYYY-MM-DD

sanctions_resolve_entity _tool

• name in any script (same bound as sanctions_screen_name) plus optional jurisdiction, status, and minScore; same matchMode behavior as sanctions_screen_name; up to 50 candidates per page (limit, default 10) with offset
• jurisdiction is a country code, which matches the country and every subdivision under it (US matches US-DE and US-CA), or an ISO 3166-2 subdivision code (US-DE), matched exactly; case-insensitive
• status: issued (default) matches ISSUED, lapsed matches exactly LAPSED, and any applies no filter — the only way to reach RETIRED, DUPLICATE, ANNULLED, PENDING_TRANSFER, PENDING_ARCHIVAL, or MERGED records, each candidate's status naming its state
• Searches every name GLEIF publishes: the legal name, previous legal names, trading names, alternative-language legal names, and ASCII transliterations of a legal name in another script
• Candidates carry lei, legalName, the matchedName and its matchedNameType (LEGAL_NAME, PREVIOUS_LEGAL_NAME, TRADING_OR_OPERATING_NAME, …, or UNKNOWN for a name stored without a type), and matchType, with score and queryTokenCoverage on approximate matches; one candidate per LEI, paged by the same totalAvailable / totalAvailableBasis / hasMore / nextOffset fields

sanctions_get_entity _tool

• One 20-character lei; returns the legal name, otherNames, legal and headquarters addresses, status, jurisdiction, registration authority, and lastUpdate
• alternateNames lists every other and transliterated name with its GLEIF type; a name the mirror stored before types were kept reads as UNKNOWN
• sanctionsHits screens the legal name against every watchlist, strict-only and capped at 25; screeningStatus (screened / not_ready) says whether that screen ran, and sanctionsScreen.hasMore flags a capped list

sanctions_trace_ownership _tool

• Root lei, direction (parents / children / both, default both), and depth 1–5 (default 3); screenNodes: true screens every node's legal name, strict-only, up to 10 hits per node
• nodes (with role and depth) and edges (with relationshipType); complete is false when the graph is truncated at the depth limit or missingEntityLeis lists nodes with no Level 1 record. It covers the loaded relationships only, and most entities publish no parent relationship.
• Each node whose parents the walk read carries parentStatus.direct / .ultimate: relationship, exception (a GLEIF reporting exception, with every reason, such as NATURAL_PERSONS), none, or unknown. unknown means exception data is not loaded, which reportingExceptionsLoaded: false states.
• screeningStatus (screened / not_requested / not_ready), screenedNodeCount, and flaggedNodeCount; each screened node reports its own sanctionsScreen.hasMore

sanctions_list_sources _tool

• No input; one row per sanctions list plus gleif, each with recordCount, url, and license
• sanctionsReady / sanctionsAsOf and leiReady / leiAsOf report whether each mirror has synced and when; sanctionsAsOf is the last sync in which every sanctions list refreshed. Not gated on readiness, so it reports an empty mirror instead of failing
• reportingExceptionsLoaded, and on the gleif row a reportingExceptionCount once the reporting exceptions are loaded

sanctions://designation/{source}/{entryId} _resource

• source is one of the five list codes, entryId the list's own ID or its published reference number, resolved as sanctions_get_designation resolves it and decoded once when percent-encoded; returns the sanctions_get_designation payload as application/json
• Cached for an hour, scoped private

sanctions://entity/{lei} _resource

• The sanctions_get_entity Level 1 payload for one lei, without the sanctions cross-reference, which is tool-only
• Cached for an hour, scoped private

sanctions://sources _resource

• The sanctions_list_sources payload, plus the GLEIF relationshipCount
• ttlMs: 0: never cached, because readiness and the as-of timestamps are the payload

sanctions_vet_counterparty _prompt

• Arguments: name required; jurisdiction optional (a country code, which includes its subdivisions, or an ISO 3166-2 subdivision code)
• Returns one user message that screens the name (and any identifier the caller holds, with sanctions_screen_identifier), resolves it to an LEI, traces ownership with screenNodes: true, pulls each hit's designation record, and asks for a summary that treats every match as a candidate to verify. It names GLEIF parents as accounting-consolidation parents, not beneficial owners, and reports a reporting exception's reasons rather than reading it as "no parent"

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

Sanctions-screening-specific:

• One screen covers OFAC SDN, OFAC Consolidated, EU, UK (UKSL), and UN; the matching list shows up as per-hit provenance
• Offline and keyless, with no per-request rate limit: all five sources are normalized into local SQLite + FTS5 mirrors via the framework MirrorService
• Per-alias name index, so a query matches any of an entity's names in one FTS scan, and a per-identifier index for exact lookup by IMO number, SWIFT/BIC, wallet address, or document number
• Strict-then-fuzzy matching: exact-normalized, then all tokens present (FTS5), then Jaro-Winkler + Double-Metaphone, with fuzzy candidates capped by SANCTIONS_FUZZY_MAX_RESULTS
• GLEIF Level 1 (who is who) and Level 2 (who owns whom) for entity resolution and ownership tracing

Agent-friendly output:

• Real signal with provenance: approximate hits carry the raw Jaro-Winkler score and a literal queryTokenCoverage count, never a blended confidence; every hit names its list, program, designation date, and the name that matched, typed primary / aka / fka / low-quality-aka
• Decision-support caveat in the output of sanctions_screen_name, sanctions_screen_identifier, sanctions_get_designation, sanctions_get_entity, and sanctions_trace_ownership
• Disclosed gaps: totalAvailableBasis, screeningStatus, complete / truncated / missingEntityLeis, and each node's parentStatus say what a response did not cover
• Typed errors: every tool and resource except the sources listing fails as mirror_not_ready (retryable) until its mirror is loaded; unknown IDs fail as designation_not_found or lei_not_found, and a reference number two designations share as reference_ambiguous; a name with no letter or digit fails as name_not_searchable, one past the length bound as name_too_long, and an identifier with nothing left once spacing and separators are removed as identifier_not_searchable

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:

{  "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 mirror is not bundled: populate it with bun run mirror:init before screening (see Mirror lifecycle).

{  "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.4.0 or higher (or Node.js v24+).
• Disk for the local mirror; GLEIF Level 1 takes most of it. No source needs an API key.

Installation

1. Clone the repository:

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

2. Navigate into the directory:

cd sanctions-screening-mcp-server

3. Install dependencies:

bun install

4. Configure environment:

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

5. Populate the mirror:

bun run mirror:init

Configuration

Every source is keyless, so nothing here is required.

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

Running the server

Local development

• Build and run:

  sh

  # One-time buildbun run rebuild
  # Run the built serverbun run start:stdio# orbun run start:http

• Run checks and tests:

  sh

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

Mirror lifecycle

The mirror loads out-of-band, never on the request path.

A list that fails to download or arrives truncated keeps its stored rows and removes nothing, while every other list still refreshes and the name and identifier indexes are rebuilt. GLEIF still refreshes after it, and the run then exits non-zero naming each failed list (ofac_sdn, eu, …). sanctionsAsOf advances only on a run in which every list refreshed, and a first mirror:init with a failed list leaves the mirror not ready.

GLEIF advances all at once or not at all. leiAsOf and the checkpoint move only after every dataset's covering delta has applied, so an interrupted refresh leaves both where they were, and the next run re-applies from the same point. Two cases apply nothing to GLEIF, leave leiAsOf unchanged, and exit non-zero naming mirror:init: a checkpoint older than the one-month window, and a mirror with no checkpoint. Every mirror written by 0.3.0 or earlier has no checkpoint, so run mirror:init once after upgrading. Until then, traces read unpublished parents as unknown, and sanctions_resolve_entity searches legal names only, with a notice saying alternate names are not yet indexed: 0.3.0 stored other names without their types and no transliterated names at all, so the name index is built from the golden copy mirror:init loads, never from the stored rows. Every GLEIF write after that keeps the index current. A GLEIF write by an earlier release, after a rollback, leaves it behind, and resolution returns to legal names and the notice until the next mirror:init.

A mirror written by an earlier release upgrades in place on first open: the designation table gains its reference_number column, and the identifier index is built from the stored records before the first lookup, so sanctions_screen_identifier answers from a populated mirror without a re-init. What the earlier release did not read — reference numbers, the OFAC and UK identifiers beyond identity documents, and dates at published precision — arrives with the next sanctions refresh, so run mirror:refresh after upgrading rather than waiting for the cron. The index is also rebuilt on open whenever a sync it did not follow has changed the stored records, such as one an earlier release ran after a rollback.

Every leg of mirror:init and mirror:refresh streams in bounded batches, so peak memory tracks the batch size, not the source size. The sanctions XML totals about 172 MB. The GLEIF Level 1 golden copy is about 3.4M records (~890 MB compressed) and dominates disk use; its name index (~4M names) adds about 0.8 GB of that. The reporting exceptions add about 6.4M rows (~525 MiB on disk).

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. Mount a volume at /usr/src/app/data so the mirror survives restarts, and populate it with bun run mirror:init via docker exec. 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; the mirror is reached through getScreeningService(), not ctx.state
• 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 these sources, cited per their terms:

UKSL has been the single authoritative UK source since the OFSI Consolidated List closed on 28 January 2026.

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheckbun run test

License

Apache-2.0 — see LICENSE for details.