The Diligent Entities
API, composed by an agent.

Three layers, one conversation.

The server is designed so an LLM can navigate it without memorizing 166 tool names. A meta layer describes itself; a smart ingest layer handles the messy human work; a primitive layer exposes every GraphQL mutation the Diligent Entities API offers.

Architecture at a glance.

Claude talks to the MCP over stdio. The MCP wraps a hardened GraphQL client with retry, structured errors, and token refresh. Reference data is cached for 15 minutes so fuzzy matches don't thrash the API.

              ┌───────────────────────────────────────────────────────┐
              │  Claude (agent loop)                                     │
              └──────────────────────────┬────────────────────────────┘
                                         │ MCP Protocol (stdio)
                                         ▼
      ┌───────────────────────────────────────────────────────────────────┐
      │                    Diligent Entities MCP                          │
      │                                                                   │
      │   Meta layer       Smart ingest       Primitive layer         │
      │   self-discovery   fuzzy match       CRUD + getters             │
      │   health & metrics concurrency       audit trail                 │
      │   introspection    dry-run            security groups             │
      │   query_all        duplicates         addresses & appointments    │
      │                                                                   │
      │   ─────────────────────────────────────────────────────          │
      │                                                                   │
      │   Hardened GraphQL client                                        │
      │   · retry + exponential backoff   · typed error classification    │
      │   · auth refresh hook              · in-memory session metrics     │
      │   · reference-data cache (15m)     · auto-pagination              │
      └──────────────────────────────┬────────────────────────────────────┘
                                     │ HTTPS + Bearer token
                                     ▼
              ┌───────────────────────────────────────────────┐
              │       Diligent Entities                        │
              │       GraphQL API · HotChocolate              │
              └───────────────────────────────────────────────┘

Six beats, thirty-seven seconds.

A realistic end-to-end ingestion flow: messy CSV in, clean data plus audit proof out. This is the exact sequence the agent runs during the demo, timed across 3 rehearsal runs against a live tenant.

The smart ingest layer.

Ingestion is the place where Diligent Entities, as an API, is at its most unforgiving: reference data, per-country type scoping, and duplicate semantics all have to be right before a single mutation is accepted. The smart ingest layer handles all of it so the agent can think in natural language.

// Map CSV rows to the MCP's free-text schema — no IDs required.
const payloads = rows.map(r => ({
  entityName:        r.company_name,
  companyTypeName:   r.company_type,    // "BV" / "GmbH" / "SARL" — resolved by fuzzy match
  countryName:       r.country,         // "Holland" / "USA" — resolved via alias table
  companyNumber:     r.reg_number,
  incorporationDate: r.incorporated,
}));

// Step 1 — dry-run. Zero writes. Catches every issue.
const dry = await entities_bulk_create_companies({
  companies: payloads,
  dryRun:    true,
});

// Step 2 — commit. Duplicates skipped. Concurrency 4.
const real = await entities_bulk_create_companies({
  companies:      payloads,
  skipDuplicates: true,
  concurrency:    4,
});

// Step 3 — hold the references so you can undo.
const refs = real.results
  .filter(r => r.status === 'created')
  .map(r => r.created.entityReference);
// → ["BRTP2020", "COBT2011", "FRMR2013", ...]

Browse by capability area.

Click any category to filter the tool reference. The meta layer, smart match, and bulk ingest tools are the ones you'll want the agent to reach for first.

All 166 tools.

Each tool documents its name, one-line purpose, and full input schema. Type in the search box or click a category above to filter.

Pre-validated end-to-end scenarios.

Each pack is a full agent loop — tested against a live tenant, timed, and scored. Use them as reference workflows or as the starting point for a new one.

What the agent does when there's no tool for that.

The MCP has 166 tools. Real questions are unbounded. When there's no dedicated tool, the agent composes primitives.

UK companies grouped by type

const all = await entities_query_all({
  collection: 'companies',
  maxRecords: 500,
});
const uk = all.items.filter(c => c.country?.name === 'United Kingdom');
const byType = uk.reduce((acc, c) => {
  const k = c.companyType?.name || '(unknown)';
  acc[k] = (acc[k] || 0) + 1;
  return acc;
}, {});
// → { 'Limited by Shares': 55, 'Limited by Guarantee': 1, 'Public Limited Company': 1 }

Individuals serving as directors of 3+ companies

const all = await entities_query_all({ collection: 'individuals', maxRecords: 1000 });
const results = [];
for (const ind of all.items) {
  const appts = await entities_list_appointments({
    entityId: ind.id,
    appointmentTypeName: 'Director',
  });
  if (appts.items.length >= 3) {
    results.push({ individual: ind, count: appts.items.length });
  }
}

Roll back an entire bulk import

// refs was collected from the previous bulk_create_companies call
for (const ref of refs) {
  const co = await entities_get_company_by_reference({ reference: ref });
  await entities_delete_company({ id: co.id });
}
const audit = await entities_list_audit_trails({ take: 50 });
// audit.items contains the 17 delete events, signed with user + timestamp

Error model.

Every error is classified. Validation and limit errors fail fast; network and 5xx errors are retried with exponential backoff; auth errors transparently refresh the token once.

Getting started.

The server is a single Node.js process. Connect Claude to it via MCP stdio and you're in business.

# clone and install
git clone https://github.com/RiskaptureAI/diligent-entities-mcp.git
cd diligent-entities-mcp
npm install

# environment
export ENTITIES_API_URL="https://your-tenant.blueprintserver.com"
export ENTITIES_API_TOKEN="<your bearer token>"

# DXM fallback (optional — only for UI automation)
export ENTITIES_DXM_USERNAME="[email protected]"
export ENTITIES_DXM_PASSWORD="<password>"

# run
node src/index.js

Claude MCP config

{
  "mcpServers": {
    "diligent-entities": {
      "command": "node",
      "args": ["/path/to/diligent-entities-mcp/src/index.js"],
      "env": {
        "ENTITIES_API_URL": "https://your-tenant.blueprintserver.com",
        "ENTITIES_API_TOKEN": "<your bearer token>"
      }
    }
  }
}

First agent prompt

I've got a CSV of 20 companies from a messy handover. Pull them into
Diligent Entities — but don't trust the data. Validate everything first,
tell me what's clean and what's broken, then import the good stuff.

Production readiness.

Today this is a hardened pilot, not a production release. If you're shipping it to a real customer, read this section first.

What's solid today

• Retry with exponential backoff and structured error classification across all 166 tools.
• Bounded concurrency with per-row error capture — one bad row never aborts a batch.
• In-memory session metrics (call count, success rate, avg latency, retry count) exposed via get_session_metrics.
• Auto-pagination helper for collections up to 10,000 rows.
• Optional JSONL observability log via ENTITIES_LOG_FILE.
• Transparent token refresh via DXM Playwright fallback on 401.

What still needs work

• Multi-tenancy: one token per server instance today.
• GraphQL queries use string interpolation, not variables — refactor before untrusted input gets anywhere near the MCP.
• Playwright browser doesn't yet close on SIGTERM — clean up resource leaks before long-running deployments.
• Test suite is manual scripts hitting live tenants — needs a mocked-client test framework + CI.
• PII redaction at the logging layer is currently opt-out by not enabling file logging.