Apache Pinot MCP Server

Open an owner-bound, budgeted evidence run using a server-owned profile. Supply closed baseline/incident windows in epoch milliseconds. The server checks scope, windows, and authorization before issuing an opaque run ID. Failure recovery: Correct invalid scope/window inputs; expired runs require a new investigation.

Preview or create a new Pinot schema without replacing an existing schema. The default preview performs strict local structural validation and returns a short-lived confirmation token bound to the exact normalized schema. Pass that token with ``dry_run=false`` to apply. Replacement belongs in ``update_schema``. Failure recovery: Invalid JSON, missing ``schemaName``, and controller validation failures are non-retryable until corrected. Permission failures require access changes; retry transient controller failures only after connectivity is restored.

Create a new Pinot table configuration. Accepts a typed table-config object. The default ``dry_run=true`` asks Pinot to validate the payload and returns a confirmation token without applying. Failure recovery: Invalid JSON, missing ``tableName``, and controller validation failures need a corrected payload; do not retry unchanged. Fix access failures first, and retry transient controller errors after connectivity is restored.

Close a run once with authentic citations and an unverified outcome. Choose proposed for an adequately supported candidate association, abstained when adequate evidence shows healthy, unrelated, or confounded observations, and incomplete when missing, sparse, stale, partial, or failed evidence prevents evaluating the association. Complete SQL execution can still yield insufficient observations. Missing matched controls in otherwise adequate observations can reveal confounding and support abstention. Proposed requires a hypothesis; proposed/abstained require complete citations. Incomplete requires a reason. Pending work blocks finishing. These semantic choices are caller judgments; finishing validates ownership, citations, and execution completeness. Evidence sufficiency, the semantic choice, hypotheses, and dataset coverage remain unvalidated. Failure recovery: Correct citation/status errors; a closed run cannot be reused.

Get one Pinot schema, including dimensions, metrics, time, and primary keys. This is a single-object lookup, not a list, so pagination does not apply. The output preserves additional fields introduced by the connected Pinot version. Failure recovery: For not-found errors, pass the table's exact schema name (normally the table name without a type suffix). Fix permissions before retrying; retry transient controller failures after ``test_connection`` succeeds.

Get per-column index metadata for ONE segment (which indexes each column has). Use this to inspect how a specific segment is indexed (inverted, sorted, range, etc.). Requires a ``segment_name`` from ``list_segments``. For a segment's row count/size/time boundaries use ``list_segment_metadata``; for the table's declared index *configuration* (not per-segment state) use ``get_table_config``. Failure recovery: A missing segment is non-retryable with the same value; refresh ``list_segments`` and use an exact returned name. Retry transient controller errors after ``test_connection`` succeeds.

Get one table's indexing, retention, tenant, and ingestion configuration. This is a single-object lookup, not a list, so pagination does not apply. Set ``table_type`` only when one side of a hybrid table is needed. Failure recovery: For not-found errors, use an exact name from ``list_tables`` and a valid table type. Fix permissions before retrying; retry transient controller failures after ``test_connection`` succeeds.

Get a table's storage footprint: reported vs. estimated size in bytes. Use this for capacity/size questions about a whole table. It does NOT list segments (use ``list_segments``) or return row counts/time boundaries (use ``list_segment_metadata``). ``reportedSizeInBytes`` is what the servers currently hosting the segments report; ``estimatedSizeInBytes`` assumes every replica is present. Failure recovery: For not-found errors, copy an exact name from ``list_tables``. Fix permission errors before retrying; retry transient controller failures after a health check.

Retrieve scoped trace rows with actual span and parent-span identifiers. Configure both span columns in the server profile. This fetches recorded relationships and does not infer causality or validate instrumentation coverage. Failure recovery: Use an exact scoped trace ID; inspect completeness before citing.

Get a deterministic page of segment rows, sizes, and time boundaries. Pinot can return thousands of segment objects. Results are sorted by exact segment name, then sliced with ``limit``/``offset``; follow ``has_more`` until false. Use ``list_segments`` when only names are needed. Failure recovery: An empty page is success. For not-found errors, use ``list_tables``; correct permissions before retrying, and retry transient server failures only after ``test_connection`` succeeds.

List a table's segment names, grouped by table type (OFFLINE/REALTIME). Use this to discover segment names — e.g. to get a ``segment_name`` for ``get_segment_index_metadata``, or to see how a table is partitioned. For per-segment row counts / sizes / time boundaries call ``list_segment_metadata`` instead; for total storage call ``get_table_size``. Segment names are paginated (a busy table can have thousands) — use ``limit``/``offset`` and the ``has_more`` flag to page through them. Failure recovery: An empty page is success. For not-found errors, use an exact name from ``list_tables``; correct access errors, or retry transient controller errors.

List Pinot tables visible to this server (subject to table filters). Returns a paginated list of table names. Use ``limit``/``offset`` and the ``has_more`` flag to page through clusters with many tables. Failure recovery: An empty page is success. For authentication/connectivity errors, verify the controller with ``test_connection`` and retry after access is restored.

Collect bounded evidence with fixed tenant/time predicates and citations. The server generates SQL for the selected kind. Candidate filters apply only to onset queries. Failed, unknown, partial, truncated, or late execution is retained as incomplete evidence; it cannot support a qualified finish. Failure recovery: Query attempts consume budget even on failure. Inspect evidence before retrying.

Run a read-only SQL query against Pinot and return a page of rows. Only a single SELECT (or WITH ... SELECT) statement is allowed; the query is rejected if it contains multiple statements or write/DDL/admin keywords. Results are paginated to keep responses small — use ``limit``/``offset`` and the ``has_more`` flag to page through large result sets. Returns ``QueryResult`` with the page of rows, the column list, fetched row count, a ``has_more`` flag, and native execution metadata. Missing native metadata is unknown; complete execution does not establish dataset coverage. Failure recovery: SQL/allow-list/permission failures require correcting the query or access; do not retry unchanged. A timeout or connection failure can be retried after ``test_connection`` succeeds. Check ``metadata.completeness`` even for zero rows; no response is promoted to healthy empty evidence.

Preview or apply the configured table-filter YAML without restarting. Reads only the path configured by ``PINOT_TABLE_FILTER_FILE``. The YAML must be an object whose ``included_tables`` value is a non-empty list of glob strings. Allowing every table requires an explicit ``allow_all: true``. The default ``dry_run=true`` validates and reports the before/after patterns and returns a short-lived confirmation token. Pass ``dry_run=false`` with that token to apply the exact candidate atomically. Editing the file after preview invalidates the confirmation and requires another preview. Failure recovery: A missing setting/file or malformed YAML is non-retryable until corrected; fix ``PINOT_TABLE_FILTER_FILE`` or its ``included_tables`` list, then retry.

Probe Pinot connectivity and return diagnostics. Runs three checks — broker connection, a trivial ``SELECT 1`` query, and a controller table listing — and reports which succeeded plus a small sample of tables. Useful for troubleshooting configuration before using other tools. Failure recovery: Individual check failures are returned in ``error``. Verify the broker and controller URLs, credentials, and network, then retry only failed checks.

Update an existing Pinot schema. Accepts a typed schema object. This can change column definitions on a live table; the default ``dry_run=true`` previews without applying and returns a confirmation token bound to the exact replacement. Failure recovery: Invalid JSON/name or schema validation failures require a corrected payload; do not retry unchanged. Fix permission errors first, and retry transient controller failures only after connectivity is restored.

Update an existing Pinot table configuration. Accepts a typed replacement table-config object. This changes a live table; the default ``dry_run=true`` asks Pinot to validate it, compares it with the current configuration, and returns a token without applying. Failure recovery: Invalid JSON/name or controller validation failures require a corrected payload; do not retry unchanged. Fix access errors first, and retry transient controller failures only after connectivity is restored.