# US Business Verification — MCP Server

A zero-dependency [Model Context Protocol](https://modelcontextprotocol.io) server that verifies
US businesses against **official, keyless state registries** and screens them against the **live
OFAC SDN sanctions list** — the know-your-business (KYB) checks an agent needs before it trusts a
counterparty, with the exact source URL and timestamp on every field.

No API key. No account. No paid proxy. Every record is built from public-domain official sources.

## What it does

Give it a business name (and optionally a state) and it returns a single structured record:

- **Scored match** — `match_confidence` (0–1) and `match_tier`, not a naive string compare, so an
  agent can threshold its own risk.
- **Official identity** — `entity_name`, `entity_id`, `status` + normalized status, `entity_type`,
  `formation_date`, `jurisdiction`, `registered_agent`, `principal_address`.
- **UCC-lien profile (Colorado)** — active liens, secured parties, filing dates — the debt-and-
  collateral picture an entity lookup alone never shows.
- **OFAC SDN sanctions screen** — the business *and* its registered agent checked against the live
  Specially Designated Nationals list, downloaded per call (a delisted entity correctly clears).
- **Defensible no-match audit** — a miss returns `no_match_reason` and ranked `candidates`, never a
  bare `false`, so "not found" is explainable.
- **Provenance on everything** — `source_url` + `retrieved_at` on every record.

### States currently live

| State | Source | Depth |
|-------|--------|-------|
| **NY** | NY Dept. of State business entities | scored match + status |
| **CO** | CO Secretary of State entities + UCC-lien family | match + full UCC profile |
| **CT** | CT Secretary of the State Business Registry | explicit status + registered agent |

All three are keyless Socrata open-data endpoints published under a public-domain license. Coverage
is derived from the live source registry — `list_states` always reports the true current set.

## Tools

| Tool | What it does |
|------|--------------|
| `verify_business` | Verify one or more businesses (names or `{name, state}`). Scored match, status, formation, registered agent, CO UCC profile, OFAC screen, provenance. |
| `screen_sanctions` | Screen names directly against the live OFAC SDN list. Per-name verdict (`clear` / `potential_match` / `match`), program, matched alias, confidence, source URL. |
| `list_states` | The states verifiable right now and how each is addressed. No network call. |
| `get_hosted_access` | Describes the hosted batch rail for high-volume, metered runs. No network call, no payment. |

## Install & run

Run it straight from the repository — no install, no key:

```bash
npx github:rezearcher/business-verification-mcp
```

### Claude Desktop / Cursor / any MCP client

```json
{
  "mcpServers": {
    "business-verification": {
      "command": "npx",
      "args": ["github:rezearcher/business-verification-mcp"]
    }
  }
}
```

The server speaks MCP stdio (newline-delimited JSON-RPC 2.0). It boots instantly and pulls in no
transitive dependencies.

## Example

```jsonc
// verify_business { "businesses": ["Palantir Technologies"], "state": "CO" }
{
  "input_name": "Palantir Technologies",
  "matched": true,
  "match_confidence": 0.9,
  "entity_name": "Palantir Technologies Inc.",
  "entity_id": "20201707433",
  "status": "Good Standing",
  "status_normalized": "active",
  "entity_type": "FPC",
  "formation_date": "2020-08-18",
  "jurisdiction": "DE",
  "ucc": { "checked": true, "jurisdiction": "CO", "has_active_liens": false, "lien_count": 0 },
  "source_url": "https://data.colorado.gov/resource/4ykn-tg5h.json?$where=entityid='20201707433'",
  "retrieved_at": "2026-11-06T12:43:31.387Z"
}
```

## Source terms

Each state source is a public-domain Socrata open-data dataset; the license is recorded per source
before it is added, and a source whose terms prohibit this use is not included. The OFAC SDN list is
a US-government work (17 U.S.C. §105, public domain).

## Hosted batch rail

These tools are free and keyless. For managed, high-volume batch verification with per-match metered
billing (pay only on a confirmed match; no-matches are free), see
[the hosted rail](https://apify.com/greyridge-signals/us-business-verification). The hosted service
runs the same core — it adds scale, run history, and metering, not different data.

## Maintenance

A scheduled smoke test runs a real MCP client handshake plus a live verification and a live OFAC
load on every push and daily; if an official source changes shape, the roundtrip fails and an issue
is opened automatically. Run it yourself with `npm test`.

## License

MIT — Grey Ridge Signals Group LLC.