Note (2026-04-24): After this document was written, legal_entity was renamed to tenant and the old tenant was renamed to organization. Read references to these terms with the pre-rename meaning.

Master Data MCP Tools Design

Two MCP tools for querying master data, used by agents during the Data Discovery Protocol (Phase 3 — Cross-References & Gaps).

Tool 1: orcha-master-data-legal-entities

Returns legal entities accessible to the OAuth identity.

Input:

• search (string, optional) — ILIKE filter on name

Query:

SELECT id, name FROM legal_entity
WHERE id = ANY(:legal-entity-ids)
  AND (:search IS NULL OR name ILIKE '%' || :search || '%')
ORDER BY name

Response:

{"legal_entities": [{"id": "uuid", "name": "Acme GmbH"}]}

No pagination — a tenant has at most a handful of legal entities.

Tool 2: orcha-data-master-data

Queries master data datasets for a legal entity. Supports three types via a type parameter, each backed by a different table with a JSONB data column.

Input:

• legal_entity_id (string, optional) — auto-selects if identity has exactly one LE; errors with guidance to use orcha-master-data-legal-entities if multiple LEs available
• type (string, required, enum: gl-accounts, cost-centers, business-partners)
• search (string, optional) — ILIKE filter on type-specific JSONB fields
• page (integer, optional, default 1)
• per_page (integer, optional, default 100, max 500)

Legal entity resolution

1. Provided + in context → use it
2. Provided + not in context → error: unauthorized
3. Omitted + 1 LE in context → auto-select
4. Omitted + multiple LEs → error instructing to use orcha-master-data-legal-entities

Active dataset lookup

Each table stores one active dataset per legal entity:

• gl_accounts_dataset, business_partner_dataset: WHERE is_active = true
• cost_center_dataset: WHERE position IS NOT NULL

JSONB filtering

Use jsonb_array_elements to unnest the data array, apply ILIKE on type-specific fields:

• gl-accounts: number, name
• cost-centers: search across all string values (flexible headers)
• business-partners: account-number, name, vat-id, iban

Pagination via SQL LIMIT/OFFSET on the unnested rows.

Response format

{
  "type": "gl-accounts",
  "legal_entity_id": "uuid",
  "total_count": 342,
  "page": 1,
  "per_page": 100,
  "items": [
    {"number": "4200", "name": "Erlöse", "balance_position": "GuV"}
  ]
}

Cost centers include dynamic headers:

{
  "type": "cost-centers",
  "headers": ["Number", "Name", "Employee"],
  "items": [{"Number": "100", "Name": "Sales", "Employee": "John Doe"}]
}

File structure

Single file: src/com/getorcha/link/mcp/tools/master_data.clj

Both tools registered via tools/register-tool!. Query logic inline — no separate queries namespace. Legal entity resolution extracted as a shared private function used by orcha-data-master-data.

Registration added to tools/init-tools!.

Scoping

Both tools use "mcp:read" scope (default).