interface / agent tool
Query through MCP
Call the registered CatDB entity-query tool from an MCP client and receive the structured semantic answer.
Prerequisites and boundary
Connect an MCP client to a CatDB server over the transport configured for that server.
request
MCP tools/call parameters
{
"name": "catdb.entity_query",
"arguments": {
"workspace_id": "00000000-0000-0000-0000-000000000001",
"catalog_revision_id": null,
"schema_version_id": null,
"entity": "Customer",
"select": [
"id",
"name"
],
"filters": [],
"order_by": [],
"source_ids": null,
"max_staleness_ms": null,
"require_complete": true,
"page_size": 50,
"limit": 50,
"query_id": null,
"cursor": null
}
}Fieldsentity required · filters required · limit required · order_by required · page_size required · select required · workspace_id required · catalog_revision_id optional · cursor optional · max_staleness_ms optional · query_id optional · require_complete optional · schema_version_id optional · source_ids optional
Input contract · EntityQueryRequest
Input JSON Schema
{
"$defs": {
"EntityCursor": {
"description": "An opaque, versioned entity-query continuation cursor.",
"type": "string"
},
"EntityFilter": {
"description": "One explicitly ANDed entity filter.",
"properties": {
"field": {
"description": "Field name.",
"maxLength": 4096,
"type": "string"
},
"operator": {
"$ref": "#/$defs/FilterOperator",
"description": "Comparison operator."
},
"value": {
"description": "Lexical value parsed against the pinned semantic schema.",
"maxLength": 4096,
"type": "string"
}
},
"required": [
"field",
"operator",
"value"
],
"type": "object"
},
"FilterOperator": {
"description": "One V1 comparison operator.",
"oneOf": [
{
"const": "eq",
"description": "Equality.",
"type": "string"
},
{
"const": "lt",
"description": "Strictly less than.",
"type": "string"
},
{
"const": "le",
"description": "Less than or equal.",
"type": "string"
},
{
"const": "gt",
"description": "Strictly greater than.",
"type": "string"
},
{
"const": "ge",
"description": "Greater than or equal.",
"type": "string"
},
{
"const": "glob",
"description": "Glob matching over a text field.",
"type": "string"
}
]
},
"OrderBy": {
"description": "One explicit ordering key.",
"properties": {
"direction": {
"$ref": "#/$defs/OrderDirection",
"description": "Sort direction."
},
"field": {
"description": "Field name.",
"maxLength": 4096,
"type": "string"
}
},
"required": [
"field",
"direction"
],
"type": "object"
},
"OrderDirection": {
"description": "Sort direction for one ordering field.",
"oneOf": [
{
"const": "ascending",
"description": "Lowest value first.",
"type": "string"
},
{
"const": "descending",
"description": "Highest value first.",
"type": "string"
}
]
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"catalog_revision_id": {
"description": "Exact catalog revision, or `None` to resolve the authoritative head once.",
"format": "uuid",
"type": [
"string",
"null"
]
},
"cursor": {
"anyOf": [
{
"$ref": "#/$defs/EntityCursor"
},
{
"type": "null"
}
],
"description": "Opaque continuation from an earlier page."
},
"entity": {
"description": "Qualified semantic entity name.",
"maxLength": 4096,
"type": "string"
},
"filters": {
"description": "Filters combined with logical AND.",
"items": {
"$ref": "#/$defs/EntityFilter"
},
"maxItems": 64,
"type": "array"
},
"limit": {
"description": "Maximum reconciled rows in the whole logical query.",
"format": "uint32",
"maximum": 100000,
"minimum": 1,
"type": "integer"
},
"max_staleness_ms": {
"description": "Maximum acceptable source age in milliseconds.",
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"order_by": {
"description": "Explicit ordering. Record key and source identity are implicit stable\ntie-breakers.",
"items": {
"$ref": "#/$defs/OrderBy"
},
"maxItems": 16,
"type": "array"
},
"page_size": {
"description": "Number of reconciled rows returned in this page.",
"format": "uint32",
"maximum": 1000,
"minimum": 1,
"type": "integer"
},
"query_id": {
"description": "Server-issued logical query identity required only with a continuation.",
"format": "uuid",
"type": [
"string",
"null"
]
},
"require_complete": {
"description": "Whether every authorized source must answer. `None` means `true`.",
"type": [
"boolean",
"null"
]
},
"schema_version_id": {
"description": "Exact semantic schema version, or `None` to use the revision's default.",
"format": "uuid",
"type": [
"string",
"null"
]
},
"select": {
"description": "Explicit response fields.",
"items": {
"type": "string"
},
"maxItems": 128,
"minItems": 1,
"type": "array"
},
"source_ids": {
"description": "Optional source selection.",
"items": {
"format": "uuid",
"type": "string"
},
"maxItems": 128,
"type": [
"array",
"null"
]
},
"workspace_id": {
"description": "Workspace being queried.",
"format": "uuid",
"type": "string"
}
},
"required": [
"workspace_id",
"entity",
"select",
"filters",
"order_by",
"page_size",
"limit"
],
"type": "object"
}Response contract
A successful call returns the EntityQueryResponse shape defined by the interface. The schema below identifies the fields your application can read from that response.
Output contract · EntityQueryResponse
Output JSON Schema
{
"$defs": {
"Completeness": {
"description": "Derived answer completeness.",
"oneOf": [
{
"description": "Every authorized source answered.",
"properties": {
"state": {
"const": "complete",
"type": "string"
}
},
"required": [
"state"
],
"type": "object"
},
{
"description": "Explicitly opted-in answer with visible authorized exclusions.",
"properties": {
"excluded_source_ids": {
"description": "Authorized sources that refused.",
"items": {
"format": "uuid",
"type": "string"
},
"type": "array"
},
"state": {
"const": "partial",
"type": "string"
}
},
"required": [
"state",
"excluded_source_ids"
],
"type": "object"
}
]
},
"EntityCursor": {
"description": "An opaque, versioned entity-query continuation cursor.",
"type": "string"
},
"EntityRow": {
"description": "One typed, reconciled semantic row.",
"properties": {
"fields": {
"additionalProperties": true,
"description": "Explicitly selected fields; absent remains different from JSON null.",
"type": "object"
},
"provenance": {
"additionalProperties": {
"$ref": "#/$defs/FieldProvenance"
},
"description": "Provenance for every selected field.",
"type": "object"
},
"record_key": {
"description": "Stable source record key.",
"type": "string"
}
},
"required": [
"record_key",
"fields",
"provenance"
],
"type": "object"
},
"FieldObservation": {
"description": "One source's evidence for one field on one source record.",
"properties": {
"mapping_version_id": {
"format": "uuid",
"type": "string"
},
"observed_at_ms": {
"format": "int64",
"type": [
"integer",
"null"
]
},
"physical_attribute": {
"type": [
"string",
"null"
]
},
"record_key": {
"type": "string"
},
"source_version_id": {
"format": "uuid",
"type": "string"
},
"state": {
"$ref": "#/$defs/WireObservationState"
}
},
"required": [
"source_version_id",
"record_key",
"mapping_version_id",
"state"
],
"type": "object"
},
"FieldProvenance": {
"description": "Provenance for one resolved field.",
"properties": {
"considered": {
"items": {
"$ref": "#/$defs/FieldObservation"
},
"type": "array"
},
"field": {
"type": "string"
},
"provenance_rule_version_id": {
"format": "uuid",
"type": "string"
},
"selected": {
"format": "uint",
"minimum": 0,
"type": [
"integer",
"null"
]
}
},
"required": [
"provenance_rule_version_id",
"field",
"considered"
],
"type": "object"
},
"PinnedVersions": {
"description": "Exact immutable versions used by one answer.",
"properties": {
"catalog_resolver_id": {
"description": "Stable identity of the catalog authority that resolved the revision.",
"format": "uuid",
"type": "string"
},
"catalog_revision_id": {
"description": "Catalog revision resolved once at query start.",
"format": "uuid",
"type": "string"
},
"mapping_version_ids": {
"description": "Mapping versions used, in source-report order.",
"items": {
"format": "uuid",
"type": "string"
},
"type": "array"
},
"physical_schema_version_ids": {
"description": "Physical schema versions used, in source-report order.",
"items": {
"format": "uuid",
"type": "string"
},
"type": "array"
},
"policy_version_ids": {
"description": "Policy versions in authoritative revision order.",
"items": {
"format": "uuid",
"type": "string"
},
"type": "array"
},
"provenance_rule_version_id": {
"description": "Exact provenance rule version used to reconcile every field.",
"format": "uuid",
"type": "string"
},
"schema_version_id": {
"description": "Semantic schema version.",
"format": "uuid",
"type": "string"
},
"source_version_ids": {
"description": "Source versions used, in source-report order.",
"items": {
"format": "uuid",
"type": "string"
},
"type": "array"
}
},
"required": [
"catalog_resolver_id",
"catalog_revision_id",
"schema_version_id",
"physical_schema_version_ids",
"mapping_version_ids",
"source_version_ids",
"policy_version_ids",
"provenance_rule_version_id"
],
"type": "object"
},
"SourceExecution": {
"description": "One visible source execution and freshness report.",
"properties": {
"freshness_ms": {
"description": "Age at execution time, or `None` when the source did not run.",
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"outcome": {
"$ref": "#/$defs/SourceOutcome",
"description": "Typed execution outcome."
},
"retry_after_ms": {
"description": "Provider-requested delay before retrying a rate-limited source.",
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"returned": {
"description": "Rows surviving this source's pushed and residual predicates.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"scanned": {
"description": "Candidates examined across all source pages.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"source_id": {
"description": "Stable source identity.",
"format": "uuid",
"type": "string"
},
"source_version_id": {
"description": "Exact immutable source version.",
"format": "uuid",
"type": "string"
}
},
"required": [
"source_id",
"source_version_id",
"outcome",
"scanned",
"returned"
],
"type": "object"
},
"SourceOutcome": {
"description": "Outcome of one authorized source execution.",
"oneOf": [
{
"const": "ran",
"description": "Source ran successfully, including a successful empty result.",
"type": "string"
},
{
"const": "refused",
"description": "Source refused at compilation.",
"type": "string"
},
{
"const": "stale",
"description": "Source executed, but its measured readable view exceeded the caller's\nmaximum staleness.",
"type": "string"
},
{
"const": "runtime_refused",
"description": "Source refused after compilation, while entering or performing a read.",
"type": "string"
},
{
"const": "budget_exceeded",
"description": "Source exhausted its bounded work or serialized-byte allocation.",
"type": "string"
},
{
"const": "authentication_failed",
"description": "The source rejected or could not refresh its runtime credential.",
"type": "string"
},
{
"const": "rate_limited",
"description": "The physical source rejected the read because its request rate was\nexceeded.",
"type": "string"
},
{
"const": "incomplete_search",
"description": "The source returned a successful-looking page while reporting that\nsome storage domains were omitted.",
"type": "string"
},
{
"const": "transport_failed",
"description": "Communication with the physical source failed.",
"type": "string"
},
{
"const": "source_cancelled",
"description": "The physical source cancelled its own work independently of CatDB.",
"type": "string"
},
{
"const": "schema_drift",
"description": "The physical source no longer matched its pinned schema identity.",
"type": "string"
},
{
"const": "source_failed",
"description": "Source failed while performing an authorized read.",
"type": "string"
},
{
"const": "protocol_failed",
"description": "Source violated the connector protocol.",
"type": "string"
},
{
"const": "timed_out",
"description": "Source did not finish before the absolute query deadline.",
"type": "string"
},
{
"const": "source_timed_out",
"description": "A source-local statement timeout fired before the CatDB deadline.",
"type": "string"
},
{
"const": "cancelled",
"description": "Source did not finish because cooperative cancellation fired.",
"type": "string"
}
]
},
"WireObservationState": {
"oneOf": [
{
"properties": {
"state": {
"const": "observed_value",
"type": "string"
},
"value": true
},
"required": [
"state",
"value"
],
"type": "object"
},
{
"properties": {
"state": {
"const": "observed_null",
"type": "string"
}
},
"required": [
"state"
],
"type": "object"
},
{
"properties": {
"state": {
"const": "field_unseen",
"type": "string"
}
},
"required": [
"state"
],
"type": "object"
},
{
"properties": {
"state": {
"const": "record_unseen",
"type": "string"
}
},
"required": [
"state"
],
"type": "object"
},
{
"properties": {
"state": {
"const": "not_asked",
"type": "string"
},
"value": {
"properties": {
"reason": {
"type": "string"
}
},
"required": [
"reason"
],
"type": "object"
}
},
"required": [
"state",
"value"
],
"type": "object"
}
]
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"completeness": {
"$ref": "#/$defs/Completeness",
"description": "Completeness derived from [`Self::sources`]."
},
"next_cursor": {
"anyOf": [
{
"$ref": "#/$defs/EntityCursor"
},
{
"type": "null"
}
],
"description": "Continuation bound to this request, authorization, and pin set."
},
"pins": {
"$ref": "#/$defs/PinnedVersions",
"description": "Exact immutable versions used."
},
"query_id": {
"description": "Query execution identity.",
"format": "uuid",
"type": "string"
},
"rows": {
"description": "One deterministic page of reconciled rows.",
"items": {
"$ref": "#/$defs/EntityRow"
},
"type": "array"
},
"sources": {
"description": "Visible authorized source reports in deterministic order.",
"items": {
"$ref": "#/$defs/SourceExecution"
},
"type": "array"
}
},
"required": [
"query_id",
"pins",
"rows",
"sources",
"completeness"
],
"type": "object"
}completeness- Completeness derived from [`Self::sources`].
next_cursor- Continuation bound to this request, authorization, and pin set.
pins- Exact immutable versions used.
query_id- Query execution identity.
rows- One deterministic page of reconciled rows.
sources- Visible authorized source reports in deterministic order.
Version, schema, and provenance
The MCP tool name is unversioned. Its input and structured output reuse the EntityQueryRequest and EntityQueryResponse DTOs from the HTTP API.
- Every entity query resolves and pins catalog, schema, mapping, source, and policy versions before execution.
- Responses include per-field provenance, source execution reports, and an explicit completeness outcome.
- Authorization happens before planning or source disclosure.
- Unknown fields and unsupported operations return typed errors instead of changing query semantics.