startreedata/mcp-pinot

Table of Contents
- Overview
- Features
- Quick Start
- Configuration Reference
- Docker Build
- Claude Desktop Integration
- Try a Prompt
- Security and Vulnerability Reporting
- Developer Notes
- Repo Maintainer
Overview
This project is a Python-based Model Context Protocol (MCP) server for interacting with Apache Pinot. It is built using the FastMCP framework. It is designed to integrate with Claude Desktop to enable real-time analytics and metadata queries on a Pinot cluster.
It allows you to
- List tables, segments, and schema info from Pinot
- Execute read-only SQL queries
- View index/column-level metadata
- Designed to assist business users via Claude integration
- and much more.
Features
- Every tool advertises typed input and output JSON Schemas, MCP risk annotations,
and failure-recovery guidance for agent planning.
- Large query, table, segment-name, and segment-metadata responses use bounded
pages with continuation metadata instead of returning unbounded agent context.
- Read-only SQL is parsed and enforced before execution; validation, permission,
and transient connectivity errors are surfaced as actionable MCP errors.
- Every mutating tool supports dry_run; always preview the exact target and
payload before applying. Applying requires the preview's short-lived, one-time
confirmation_token, including for table-filter reloads. A preview is not a
guarantee that Pinot will accept the later write.
- Single-purpose schema and table-config inspection tools avoid ambiguous combined
operations: use get_schema and get_table_config independently.
MCP Tool Contract
Tool names are case-sensitive and use underscores. Version 4 renamed four tools
to make every operation verb-first; clients using the former noun-first names must
update their calls.
| Tool | Purpose |
|---|---|
| test_connection | Diagnose broker, controller, and query connectivity. |
| list_tables | List visible Pinot table names. |
| get_schema | Get one table's column schema. |
| get_table_config | Get one table's indexing and ingestion configuration. |
| get_table_size | Get reported and estimated storage size for one table. |
| list_segments | List exact segment names for one table. |
| list_segment_metadata | Page through metadata for a table's segments. |
| get_segment_index_metadata | Inspect per-column indexes for one exact segment. |
| read_query | Run one read-only Pinot SQL query. |
| begin_investigation / query_incident | Open and query an opt-in scoped evidence run. |
| get_trace / finish_investigation | Fetch recorded span edges and close with citations. |
| create_schema / update_schema | Preview or apply schema changes. |
| create_table_config / update_table_config | Preview or apply table-config changes. |
| reload_table_filters | Preview or apply the configured table-filter YAML. |
For every schema, table-config, or table-filter change, first call the same tool
with dry_run=true, present the preview to the user, and call it with
dry_run=false and the preview's one-time confirmation_token only after
confirmation. Editing a table-filter file after preview invalidates its token.
Pinot performs authoritative validation during table/schema apply calls, so a
write can still fail after a successful preview.
Query execution evidence
read_query returns the existing page fields plus metadata. For example,
{"query":"SELECT service, count(*) FROM events GROUP BY service","limit":20}
returns metadata.completeness as complete, partial, or unknown, along with
native server counts, query ID, query SHA-256, and bounded execution statistics.
Missing resultTable or required execution flags remains unknown. A partial
server response or group limit remains partial; an empty page is not proof of
healthy telemetry. Native complete describes this bounded SQL execution, not
coverage of the incident window or the entire dataset. row_limit_reached is
separate from execution completeness and paging.
The MCP query path uses pinotdb>=9.2.1 through cursor.execute_native() for
submission and decoding. The SDK exposes full structured query_statistics;
MCP projects bounded counters and safe execution evidence into the tool response.
The path submits once and does not switch transports after an ambiguous failure.
Its unique clientQueryId and applicationName=mcp-pinot support optional
correlation with query history or broker logs when available. Python integrations can
call execute_query_with_metadata(..., timeout_seconds=5) to bound native and
HTTP timeouts without modifying shared configuration. HTTP timeouts are