Examples

Walkthrough: join your vendor list to public records

You keep a small CSV of third-party vendors in your private workspace. You want each name matched to GLEIF LEI records, SEC EDGAR filings, and CISA KEV / NVD CVE rows from the shared public catalog — using the same ten MCP tools as every other example, not a separate product surface.

In federated SQL, public catalog rows are available as public_ch_events and public_events alongside your tenant’s private events table (see run_sql in agents.md).

1 — Load private vendor rows (REST)

MCP tools are read-only. Ingest each CSV row with POST https://api.opendistrict.org/webhook/events and an API key that includes the events:write scope. Repeat for every vendor, or send one request per row from your script.

curl -sS -X POST 'https://api.opendistrict.org/webhook/events' \
  -H "Authorization: Bearer $OD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "event_type": "workspace.vendor",
    "payload": { "vendor_name": "Acme Robotics LLC" }
  }'

A hosted CSV upload control in the web app is not exposed on the public API yet. You can also create private connectors with POST /sources (session auth) — for example the rest template for your own HTTP API, or the file template when a folder is mounted for the gateway — then call POST /sources/{id}/sync. The steps below use only generic MCP tools after ingest.

2 — Open an MCP session

curl -sS -X POST 'https://api.opendistrict.org/mcp' \
  -H "Authorization: Bearer $OD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "examples", "version": "1" }
    }
  }'

3 — list_sources

Confirm your tenant’s private sources and which public catalog slugs are installed (for example gleif, sec-edgar-filings, cisa-kev, nvd-cves).

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "list_sources",
    "arguments": {}
  }
}

4 — get_schema (optional)

Inspect allowlisted tables before writing SQL. Federated joins can use events (your tenant) and public_ch_events (read-only public corpus).

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_schema",
    "arguments": {}
  }
}

5 — run_sql: join private vendors to public GLEIF + risk signals

Match on legal name (GLEIF payloads store the name at attributes.entity.legalName.name). Use payload ILIKE for fuzzy hits on SEC, KEV, and NVD rows. Event types: gleif.lei-record, gov.filing, security.kev, sec.nvd-cve.

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "run_sql",
    "arguments": {
      "sql": "SELECT jsonExtractString(v.payload, 'vendor_name') AS vendor, p.event_type, p.id AS public_event_id FROM events v JOIN public_ch_events p ON (p.event_type = 'gleif.lei-record' AND lower(jsonExtractString(p.payload, 'attributes', 'entity', 'legalName', 'name')) = lower(jsonExtractString(v.payload, 'vendor_name'))) OR (p.event_type IN ('gov.filing', 'security.kev', 'sec.nvd-cve') AND p.payload ILIKE concat('%', jsonExtractString(v.payload, 'vendor_name'), '%')) WHERE v.event_type = 'workspace.vendor' LIMIT 25"
    }
  }
}

6 — unified_search and entity_path (optional)

Ask natural-language questions per vendor, or trace graph hops between a company name and a CVE id when entity edges exist.

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "unified_search",
    "arguments": {
      "query": "Acme Robotics SEC 8-K filing",
      "event_type": "gov.filing",
      "limit": 10
    }
  }
}

unified_search accepts query plus optional event_type, source_id, time_range, score_threshold, and limit (see agents.md). entity_path takes from and to strings.

Example output (illustrative)

Fictitious sample only — not live query results. Shape matches what a successful run_sql join might return; every real row carries citation fields in the result envelope.