mcp-pinot

# Pinot MCP Server
<!-- mcp-name: io.github.startreedata/mcp-pinot -->

[![Build and Test](https://github.com/startreedata/mcp-pinot/actions/workflows/build-and-test.yml/badge.svg)](https://github.com/startreedata/mcp-pinot/actions/workflows/build-and-test.yml)
[![PyPI version](https://img.shields.io/pypi/v/mcp-pinot-server.svg)](https://pypi.org/project/mcp-pinot-server/)
[![Python versions](https://img.shields.io/pypi/pyversions/mcp-pinot-server.svg)](https://pypi.org/project/mcp-pinot-server/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)

## Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Quick Start](#quick-start)
- [Configuration Reference](#configuration-reference)
- [Docker Build](#docker-build)
- [Claude Desktop Integration](#claude-desktop-integration)
- [Try a Prompt](#try-a-prompt)
- [Security and Vulnerability Reporting](#security-and-vulnerability-reporting)
- [Developer Notes](#developer-notes)
- [Repo Maintainer](docs/repo-maintainer.md)

## Overview

This project is a Python-based [Model Context Protocol (MCP)](https://github.com/anthropic-ai/mcp) server for interacting with Apache Pinot. It is built using the [FastMCP framework](https://github.com/jlowin/fastmcp). 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.

<a href="https://glama.ai/mcp/servers/@startreedata/mcp-pinot">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/@startreedata/mcp-pinot/badge" alt="StarTree Server for Apache Pinot MCP server" />
</a>

## 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
inactivity limits; late results are rejected, but this is not native cancellation.

Tool results, including tool errors, include timing evidence in the standard
MCP response `_meta["io.github.startreedata/mcp-pinot"]`. Existing tool data and
output schemas are preserved. For example, this response metadata fragment
requires no log access:

```json
{
  "_meta": {
    "io.github.startreedata/mcp-pinot": {
      "request_id": "38cb1444b20c446a96bc272531f34518",
      "status": "success",
      "admitted": true,
      "queue_wait_ms": 12,
      "execution_ms": 84,
      "duration_ms": 97
    }
  }
}
```

MCP rate-limit protocol errors preserve their JSON-RPC code and message and carry
the same envelope in `error.data._meta["io.github.startreedata/mcp-pinot"]`.
Other transport/protocol failures or cancellation may not produce a tool result.

With `MCP_TRANSPORT=http` on the default port 8080, a FastMCP Python client reads
wire `_meta` through `result.meta`. `call_tool_mcp` also returns tool errors:

```python
from fastmcp import Client


async def read_timing():
    async with Client("http://localhost:8080/mcp") as client:
        result = await client.call_tool_mcp("read_query", {"query": "SELECT 1"})
        return result.meta["io.github.startreedata/mcp-pinot"]
```

Orchestrators should read `.meta` and forward this evidence to the agent when the
host does not automatically surface protocol metadata.

`queue_wait_ms` measures only waiting for the MCP concurrency semaphore.
`execution_ms` measures the admitted MCP tool pipeline, including SDK HTTP work
and validation; `admitted=false` means that pipeline never started. `duration_ms`
covers the server's tool invocation, including admission checks, and excludes
model reasoning and client delivery. `status` is `success` or `error` for the MCP
outcome; for `read_query`, separately inspect `metadata.completeness`.

An agent can use `queue_wait_ms` to identify MCP admission delay, then inspect
`read_query`'s `metadata.native_stats.timeUsedMs` for Pinot's native query duration
when present. Native query time overlaps `execution_ms`; their different timer
boundaries do not support exact network-overhead subtraction. The shared
`request_id` also appears in query metadata and native `clientQueryId`, enabling
optional history/log correlation when more context is needed.

Response timing metadata contains no secrets, principal identifiers, tool
arguments, SQL, or rows. Audit logs record the same timings with hashed principal
identifiers. `MCP_MAX_RESPONSE_BYTES` limits the tool payload before this bounded
timing envelope is added; it excludes the added observability metadata.
Cancellation is audit-only when no response is returned and does not prove that
Pinot execution stopped.

Incident tools are disabled until the server starts with `--incident-profiles`.
See [the incident evidence guide](docs/incident-evidence.md) and
[example profile](examples/incident-profiles.example.json) for configuration and a
workflow using `begin_investigation`, `query_incident`, optional `get_trace`, and
`finish_investigation`. Evidence queries expose the same response `_meta` timings
and native request IDs when reported; log access is optional. Runs are
owner-bound and budgeted; complete execution still leaves root-cause hypotheses
and dataset coverage unvalidated. This first version uses bounded in-memory state
in one process.

## Pinot MCP in Action

See Pinot MCP in action below:

### Fetching Metadata
![Pinot MCP fetching metadata](assets/pinot-mcp-in-action.png)

### Fetching Data, followed by analysis

Prompt:
Can you do a histogram plot on the GitHub events against time
![Pinot MCP fetching data and analyzing table](assets/github-events-analysis.png)

### Sample Prompts
Once Claude is running, click the hammer 🛠️ icon and try these prompts:

- Can you help me analyse my data in Pinot? Use the Pinot tool and look at the list of tables to begin with.
- Can you do a histogram plot on the GitHub events against time


## Quick Start

### Prerequisites

#### Install uv (if not already installed)
[uv](https://github.com/astral-sh/uv) is a fast Python package installer and resolver, written in Rust. It's designed to