Pinot MCP Server

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.

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.

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.

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, and a has_more` flag.

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. Zero rows is a successful result.

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.

Returns: Preview/application status, whether it was applied, old/new patterns, and a confirmation token on previews.

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.