Pinot MCP Server

Pinot MCP Server

目次

• 概要
• 機能
• クイックスタート
• 設定リファレンス
• Docker のビルド
• Claude Desktop との連携
• プロンプトを試す
• セキュリティと脆弱性の報告
• 開発者向けメモ
• リポジトリメンテナー

概要

このプロジェクトは、Apache Pinot を操作するための Python ベースのモデルコンテキストプロトコル（MCP）サーバーです。FastMCP フレームワークを使用して構築されています。Claude Desktop と連携し、Pinot クラスターのリアルタイム分析とメタデータクエリを実行できるように設計されています。

以下の操作が可能です。

• Pinot のテーブル、セグメント、スキーマ情報を一覧表示する
• 読み取り専用の SQL クエリを実行する
• インデックスや列レベルのメタデータを表示する
• Claude との連携を通じてビジネスユーザーを支援する
• その他多数。

機能

• すべてのツールは、型付きの入出力 JSON Schema、MCP リスク注釈、およびエージェントの計画に役立つ障害復旧ガイダンスを提示します。
• 大容量のクエリ、テーブル、セグメント名、セグメントメタデータのレスポンスは、エージェントのコンテキストが無制限に増えるのを避けるため、継続メタデータ付きの上限付きページに分割されます。
• 読み取り専用 SQL は実行前に解析・適用されます。検証エラー、権限エラー、一時的な接続エラーは、対処可能な MCP エラーとして通知されます。
• すべての変更を伴うツールは dry_run に対応しています。適用前に、対象とペイロードを必ず正確にプレビューしてください。適用には、テーブルフィルターの再読み込みを含め、プレビューで発行された有効期限の短い一度限りの confirmation_token が必要です。プレビューは、後続の書き込みが Pinot に受け入れられることを保証するものではありません。
• 用途を絞ったスキーマとテーブル設定の確認ツールを用意し、曖昧な複合操作を避けています。get_schema と get_table_config を個別に使用してください。

MCP Tool Contract

ツール名は大文字と小文字を区別し、アンダースコアを使用します。バージョン 4 では、すべての操作を動詞から始めるために 4 つのツール名が変更されました。以前の名詞から始まる名前を使用しているクライアントは、呼び出しを更新する必要があります。

Tool	目的
test_connection	ブローカー、コントローラー、クエリの接続を診断します。
list_tables	表示可能な Pinot テーブル名を一覧表示します。
get_schema	1 つのテーブルの列スキーマを取得します。
get_table_config	1 つのテーブルのインデックス作成と取り込みの設定を取得します。
get_table_size	1 つのテーブルについて、報告されたストレージサイズと推定ストレージサイズを取得します。
list_segments	1 つのテーブルの正確なセグメント名を一覧表示します。
list_segment_metadata	テーブルのセグメントに関するメタデータをページ分割して取得します。
get_segment_index_metadata	正確なセグメント 1 つについて、列ごとのインデックスを調べます。
read_query	読み取り専用の Pinot SQL クエリを 1 つ実行します。
begin_investigation / query_incident	オプトインのスコープ指定された証拠収集を開始し、クエリします。
get_trace / finish_investigation	記録されたスパンのエッジを取得し、引用情報を添えて終了します。
create_schema / update_schema	スキーマの変更をプレビューまたは適用します。
create_table_config / update_table_config	テーブル設定の変更をプレビューまたは適用します。
reload_table_filters	設定済みのテーブルフィルター YAML をプレビューまたは適用します。

スキーマ、テーブル設定、テーブルフィルターを変更する場合は、まず同じツールを dry_run=true で呼び出し、プレビューをユーザーに提示してください。確認を得てから、プレビューの一度限りの confirmation_token を指定し、dry_run=false で呼び出してください。プレビュー後にテーブルフィルターのファイルを編集すると、トークンは無効になります。Pinot はテーブル／スキーマの適用呼び出し中に最終的な検証を行うため、プレビューが成功しても書き込みが失敗することがあります。

クエリ実行の証拠

read_query は既存のページフィールドに加えて metadata を返します。たとえば、{"query":"SELECT service, count(*) FROM events GROUP BY service","limit":20} は、metadata.completeness として complete、partial、または unknown を返し、ネイティブサーバーの件数、クエリ ID、クエリの SHA-256、上限付きの実行統計も含みます。resultTable または必須の実行フラグが欠落している場合は、unknown のままです。サーバー応答が不完全な場合やグループ数の上限に達した場合は partial のままです。空のページは、テレメトリーが正常である証拠にはなりません。ネイティブの complete が示すのは、この上限付き SQL 実行の完了であり、インシデント期間またはデータセット全体の網羅性ではありません。row_limit_reached は、実行の完全性やページ分割とは別の項目です。

MCP のクエリパスでは、送信とデコードに cursor.execute_native() を使用し、pinotdb>=9.2.1 を介して実行します。SDK は構造化された完全な query_statistics を公開し、MCP は上限付きのカウンターと安全な実行証拠をツールの応答に反映します。このパスでは送信を一度だけ行い、結果が不明瞭な失敗が起きてもトランスポートを切り替えません。固有の clientQueryId と applicationName=mcp-pinot は、利用可能な場合にクエリ履歴またはブローカーログとの任意の相関付けをサポートします。Python インテグレーションでは、共有設定を変更せずにネイティブと HTTP のタイムアウトを設定するため、execute_query_with_metadata(..., timeout_seconds=5) を呼び出せます。HTTP タイムアウトは非アクティブ状態の制限です。遅れて届いた結果は拒否されますが、これはネイティブのキャンセルではありません。

ツールエラーを含むツールの結果には、標準の MCP 応答 _meta["io.github.startreedata/mcp-pinot"] にタイミングの証拠が含まれます。既存のツールデータと出力スキーマは維持されます。たとえば、次の応答メタデータの一部はログへのアクセスを必要としません。

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

MCP のレート制限プロトコルエラーでは、JSON-RPC のコードとメッセージが保持され、同じエンベロープが error.data._meta["io.github.startreedata/mcp-pinot"] に含まれます。その他のトランスポート／プロトコルエラーやキャンセルでは、ツールの結果が生成されない場合があります。 デフォルトのポート 8080 で MCP_TRANSPORT=http を使用すると、FastMCP Python クライアントはワイヤー上の _meta を result.meta から読み取ります。call_tool_mcp はツールエラーも返します。

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"]

ホストがプロトコルメタデータを自動的に表示しない場合、オーケストレーターは .meta を読み取り、この証拠をエージェントに転送してください。

queue_wait_ms は、MCP の同時実行セマフォでの待機時間のみを測定します。 execution_ms は、SDK の HTTP 処理と検証を含む、許可された MCP ツールパイプラインを測定します。admitted=false は、そのパイプラインが開始されなかったことを意味します。duration_ms は、許可チェックを含むサーバーのツール呼び出しを対象とし、モデルの推論時間とクライアントへの配信時間は含みません。MCP の処理結果について、status は success または error です。read_query では、別途 metadata.completeness を確認してください。

エージェントは queue_wait_ms を使って MCP の許可待ちによる遅延を特定し、その後、値がある場合は read_query の metadata.native_stats.timeUsedMs を確認して Pinot のネイティブクエリ時間を調べられます。ネイティブクエリ時間は execution_ms と重複するため、計測範囲の違いからネットワークオーバーヘッドを正確に差し引くことはできません。共有の request_id はクエリメタデータとネイティブの clientQueryId にも含まれており、必要に応じて、追加のコンテキストを得るための履歴やログとの関連付けに利用できます。

応答のタイミングメタデータには、シークレット、プリンシパル識別子、ツール引数、SQL、行は含まれません。監査ログには、ハッシュ化されたプリンシパル識別子とともに同じタイミング情報が記録されます。MCP_MAX_RESPONSE_BYTES は、この上限付きタイミングエンベロープを追加する前のツールペイロードを制限します。追加される可観測性メタデータは対象外です。応答が返されない場合、キャンセルは監査目的でのみ記録され、Pinot の実行が停止したことを証明するものではありません。

インシデントツールは、サーバーを --incident-profiles 付きで起動するまで無効です。設定と、begin_investigation、query_incident、任意の get_trace、finish_investigation を使うワークフローについては、インシデント証拠ガイドとプロファイル例を参照してください。証拠クエリは、報告される場合、同じ応答 _meta のタイミング情報とネイティブリクエスト ID を公開します。ログへのアクセスは任意です。実行は所有者に紐付けられ、予算が設定されています。実行が完了しても、根本原因の仮説とデータセットの網羅性は未検証のままです。この初版では、単一プロセス内の上限付きインメモリ状態を使用します。

Pinot MCP の実際の動作

以下で Pinot MCP の実際の動作をご覧ください。

メタデータの取得

データの取得と分析

プロンプト： GitHub イベントを対象に、時間ごとのヒストグラムを作成できますか？

プロンプト例

Claude が起動したら、ハンマー 🛠️ アイコンをクリックして、次のプロンプトを試してください。

• Pinot のデータ分析を手伝ってもらえますか？Pinot のツールを使い、まずテーブルの一覧を確認してください。
• GitHub イベントを対象に、時間ごとのヒストグラムを作成できますか？

クイックスタート

前提条件

uv をインストールする（まだインストールしていない場合）

uv は、Rust で記述された高速な Python パッケージインストーラーおよびリゾルバーです。大幅に優れたパフォーマンスを備え、pip のドロップイン置換として設計されています。

curl -LsSf https://astral.sh/uv/install.sh | sh

# Reload your bashrc/zshrc to take effect. Alternatively, restart your terminal
# source ~/.bashrc

インストール

# Clone the repository
git clone https://github.com/startreedata/mcp-pinot.git
cd mcp-pinot
uv pip install -e . # Install dependencies

# For development dependencies (including testing tools), use:
# uv pip install -e .[dev] 

Pinot クラスターの設定

MCP サーバーでは、Pinot クラスターへの接続を設定するため、ルートディレクトリにある uvicorn の設定形式の .env ファイルが必要です。このリポジトリには、Pinot のクイックスタート環境を想定したサンプルの .env.example ファイルが含まれています。

mv .env.example .env

設定リファレンス

サーバーは、環境変数と、現在の作業ディレクトリから見つかる .env ファイルから設定を読み込みます。プロセス環境変数は .env より優先されるため、デプロイ時の設定がチェックアウトされたファイルによって意図せず置き換えられることはありません。

一般的なプロファイル

ユースケース	必須設定	備考
Claude Desktop	MCP_TRANSPORT=stdio	ローカルのデスクトップで使用する場合のデフォルトかつ推奨設定です。HTTP リスナーは起動しません。
ローカル HTTP	MCP_TRANSPORT=http, MCP_HOST=127.0.0.1	ローカル Web 用の明示的なプロファイルです。同じマシンからのみアクセスできます。
リモート HTTP/HTTPS	MCP_TRANSPORT=http, MCP_HOST=0.0.0.0, MCP_ALLOWED_HOSTS=<host[:port]>, AUTH_PROVIDER=oauth|static|oauth+static	認証プロバイダーが有効でない場合、サーバーはループバック以外への HTTP/HTTPS バインドを拒否します。また、ワイルドカードバインドには Host の許可リストを明示する必要があります。対話型ユーザーと信頼できるバックエンドを同時に利用するには、oauth+static を使用します。TLS を直接使用するか、認証済みのリバースプロキシを使用してください。
Helm による公開	service.enabled=true, mcp.host=0.0.0.0, mcp.oauth.enabled=true	Helm のデフォルトはローカルのみで、公開を明示的に有効にしない限り Service は生成されません。

Pinot 接続

変数	デフォルト	説明
PINOT_CONTROLLER_URL	http://localhost:9000	メタデータとテーブル／スキーマの操作に使用する Pinot コントローラーのエンドポイントです。
PINOT_BROKER_URL	http://localhost:8000	SQL クエリに使用する Pinot ブローカーのエンドポイントです。
PINOT_BROKER_HOST	PINOT_BROKER_URL から解析	ブローカー接続のホストを任意で上書きします。
PINOT_BROKER_PORT	PINOT_BROKER_URL から解析	ブローカー接続のポートを任意で上書きします。
PINOT_BROKER_SCHEME	PINOT_BROKER_URL から解析	ブローカー接続のスキームを任意で上書きします。通常は http または https です。
PINOT_USERNAME / PINOT_PASSWORD	未設定	Pinot の基本認証です。
PINOT_TOKEN	未設定	Pinot 用の Bearer トークンまたは生のトークンです。PINOT_TOKEN_FILENAME より優先されます。
PINOT_TOKEN_FILENAME	未設定	Pinot トークンを含むファイルです。印字可能な ASCII 文字の1行で、Bearer プレフィックスの有無は問いません。リクエストのたびにファイルを再読み込みするため、投影された Kubernetes サービスアカウントトークンなど、ローテーションされたトークンが反映されます。起動時にファイルを使用できない場合（ファイルがない、空、読み取り不可、または無効）、サーバーは警告をログに記録し、再起動されるまでトークン認証なしで動作します。その後に問題が発生した場合は、最後に読み込んだトークンが引き続き使用され、エラーは各リクエストごとではなく一度だけログに記録されます。
PINOT_DATABASE	空	複数データベースの Pinot デプロイで使用する任意のデータベースヘッダーです。
PINOT_USE_MSQE	false	Pinot のマルチステージクエリエンジンのクエリオプションを有効にします。
PINOT_REQUEST_TIMEOUT	60	HTTP リクエストのタイムアウト（秒）です。
PINOT_CONNECTION_TIMEOUT	60	HTTP 接続のタイムアウト（秒）です。
PINOT_QUERY_TIMEOUT	60	SQL クエリのタイムアウト（秒）です。

MCP サーバー

変数	デフォルト	説明
MCP_TRANSPORT	stdio	トランスポートモードです。デスクトップクライアントには stdio、Streamable HTTP クライアントには http を使用します。
MCP_HOST	127.0.0.1	HTTP のバインド先ホストです。0.0.0.0 は、認証プロバイダーが有効な場合にのみ設定してください。
MCP_PORT	8080	HTTP のリッスンポートです。
MCP_PATH	/mcp	MCP の HTTP パスです。
MCP_ALLOWED_HOSTS	exact host[:port] of a concrete bind	MCP エンドポイントで許可する Host authority のカンマ区切りリストです。ワイルドカードバインド（0.0.0.0、::）では公開 authority を推定できないため、デフォルトは空となり、クライアントが使用するホスト名（例：mcp.example.com,mcp.example.com:443）を指定するまでサーバーは起動時に終了します。
MCP_ALLOWED_ORIGINS	unset	許可するブラウザーの Origin 値をカンマ区切りで指定します。空の場合、Origin を送信するリクエストは拒否されますが、Origin を省略するクライアントは引き続き使用できます。
MCP_SSL_KEYFILE	unset	TLS 秘密鍵のパスです。MCP_SSL_CERTFILE が必要です。
MCP_SSL_CERTFILE	unset	TLS 証明書のパスです。MCP_SSL_KEYFILE が必要です。
MCP_LOG_LEVEL	INFO	アプリケーションのログレベルです。DEBUG、INFO、WARNING、ERROR、CRITICAL のいずれかを指定します。ログは stderr に出力されるため、STDIO プロトコルの出力は有効なままです。
MCP_RATE_LIMIT_RPS / MCP_RATE_LIMIT_BURST	10 / 20	プリンシパル（認証済み）またはピア（ループバック HTTP）ごとのツール呼び出しレートとバーストの上限です。
MCP_RATE_LIMIT_MAX_CLIENTS	10000	メモリ内に保持できるクライアントバケットの最大数です。最も長く使用されていないバケットから削除されます。
MCP_RATE_LIMIT_IDLE_TTL_SECONDS	600	レート制限バケットが削除可能になるまでのアイドル時間です。
MCP_CONFIRMATION_TTL_SECONDS	300	確認トークンの有効期間です。30～3600 秒に制限されます。トークンはプロセスに紐づいており、再起動後は意図的に無効になります。

認証

ループバック以外のホストに HTTP または HTTPS をバインドする前に、認証プロバイダーを設定する必要があります。

変数	デフォルト	説明
AUTH_PROVIDER	未設定	有効な認証プロバイダーです。none（デフォルト）、oauth、static、oauth+static のいずれかを指定します。ループバック以外にバインドする場合は、いずれかのプロバイダーが必要です。
		oauth+static では、1 つのデプロイで OIDC ログインと共有トークンの両方を受け付けます。ブラウザーを使う人と、信頼できるバックエンドを使う人がいる、一般的なホスト環境向けです。どちらの表記でも機能します。共有シークレットが先に確認され、各認証情報にはそれぞれのスコープ（MCP_STATIC_SCOPES と OAUTH_GRANTED_SCOPES）が適用されます。
MCP_STATIC_TOKEN	空	AUTH_PROVIDER=static 用の共有ベアラーシークレットです。サービス間で呼び出す場合は、Authorization: Bearer <token> として送信します。static プロバイダーが有効な場合は必須です。
MCP_STATIC_SCOPES	pinot:read pinot:write pinot:admin	static プリンシパルに付与するスコープを、スペースまたはカンマ区切りで指定します。読み取り専用のサービスでは pinot:read を使用してください。
OAUTH_ENABLED	false	レガシーフラグです。true は AUTH_PROVIDER=oauth と同じです。OAuth 認証を有効にします。
OAUTH_CLIENT_ID	空	OAuth クライアント ID です。
OAUTH_CLIENT_SECRET	空	OAuth クライアントシークレットです。
OAUTH_BASE_URL	http://localhost:8080	この MCP サーバーの公開ベース URL です。
OAUTH_AUTHORIZATION_ENDPOINT	空	上流の認可エンドポイントです。
OAUTH_TOKEN_ENDPOINT	空	上流のトークンエンドポイントです。
OAUTH_JWKS_URI	空	トークンの検証に使用する JWKS URI です。
OAUTH_ISSUER	空	想定するトークン発行者です。
OAUTH_AUDIENCE	正規の MCP リソース URI	トークンの検証対象となるオーディエンスです。デフォルトでは、OAUTH_BASE_URL（末尾のスラッシュを除く）に MCP_PATH を加えた値になり、RFC 9728 のメタデータで公開される URI です。プロバイダーが異なる aud を発行する場合は、明示的に設定してください。Dex など、多くのプロバイダーではクライアント ID が設定されます。サーバーは警告をログに記録し、設定値を優先します。
OAUTH_GRANTED_SCOPES	pinot:read pinot:write pinot:admin	このプロバイダーが認証するすべてのプリンシパルに付与される Pinot スコープです。トークンにすでに含まれるスコープに追加されます。汎用の OIDC プロバイダーは固定のスコープ一覧を発行し、pinot:* を発行できないため、この設定が必要です。付与しない場合、有効なユーザーからのすべてのツール呼び出しが拒否されます。読み取り専用のデプロイでは pinot:read を設定してください。
OAUTH_EXTRA_AUTH_PARAMS	未設定	追加の認可パラメーターを指定するオプションの JSON オブジェクトです。

テーブルのフィルタリング

変数	デフォルト	説明
PINOT_TABLE_FILTER_FILE	未設定	included_tables の glob パターンを含む YAML ファイルです。設定されているにもかかわらずファイルが見つからない場合、起動に失敗します。

本番環境への公開に関するチェックリストと脆弱性の報告手順については、SECURITY.md を参照してください。

テーブルフィルタリングの設定（任意）

⚠️ セキュリティに関する注意： 本番環境のアクセス制御には、Pinot のネイティブなテーブルレベル ACL（Pinot 0.8.0 以降で利用可能）を使用してください。この MCP サーバーのテーブルフィルタリングは、テーブルを整理して UX を向上させるための便利な機能であり、セキュリティ境界ではありません。ベストエフォートの SQL 解析を使用するため、セキュリティ目的では信頼しないでください。

テーブルフィルタリングを使用すると、MCP サーバーを通じて表示する Pinot テーブルを制御できます。次のような用途に便利です。

• 認知負荷の軽減：Pinot クラスターに数百または数千のテーブルがある場合、関連するテーブルに絞り込めます
• マルチテナント UX：同じ Pinot クラスターに対して複数の MCP サーバーインスタンスを実行し、チームやユースケースごとに異なるテーブルのサブセットを表示できます
• 環境の分離：環境固有のテーブルのみを表示する異なる MCP サーバーインスタンス（dev、staging、prod）をデプロイできます
• システムテーブルの非表示：内部用、テスト用、または非推奨のテーブルをエンドユーザーの表示から除外できます

テーブルフィルタリングを有効にすると、すべてのテーブル操作で、設定されたテーブルのみが表示されます。

フィルタリングの対象

テーブルのフィルタリングは、すべての MCP 操作に適用されます。

1. テーブル一覧 - 設定されたテーブルのみがテーブル一覧に表示されます
2. クエリの実行 - 参照されるすべてのテーブル（FROM、JOIN、サブクエリ、CTE など）が設定されたパターンに一致することを確認するため、SQL クエリをチェックします
3. テーブル操作 - テーブルへの直接アクセス操作では、テーブル名でフィルタリングします。
   • テーブルの詳細、サイズ、メタデータの取得
   • テーブルのセグメントとセグメントのメタデータの取得
   • インデックス／カラムの詳細の取得
   • テーブル設定の取得／更新
4. スキーマ操作 - スキーマ名でスキーマ操作をフィルタリングします。
   • スキーマの取得／作成／更新
   • テーブル設定の作成

セットアップ

サンプル設定ファイルをコピーします。

cp table_filters.yaml.example table_filters.yaml

table_filters.yaml を編集して、対象に含めるテーブルを指定します。

included_tables:
  - production_*        # All tables starting with "production_"
  - analytics_events    # Specific table name
  - metrics_*          # All tables starting with "metrics_"

.env でフィルターファイルのパスを設定します。

PINOT_TABLE_FILTER_FILE=table_filters.yaml

パターンマッチング

フィルターは、標準的な Unix のファイル名パターンマッチングを使用した glob 形式のパターンに対応しています。

• exact_table_name - このテーブルに完全一致します
• prefix_* - 「prefix_」で始まるすべてのテーブルに一致します
• *_suffix - 「_suffix」で終わるすべてのテーブルに一致します
• *pattern* - 「pattern」を含むすべてのテーブルに一致します
• sharded_table_? - アンダースコアの後に文字が1つだけ続くテーブルに一致します（例：sharded_table_1、sharded_table_a）

クエリのフィルタリング

フィルタリングが有効な場合、実行前に SQL クエリがチェックされます。

• 対応する SQL 機能：FROM 句、JOIN 句（INNER、LEFT、RIGHT、OUTER、CROSS）、サブクエリ、CTE（WITH）、カンマ区切りのテーブル一覧
• 引用符付き識別子：ダブルクォートで囲まれたテーブル名（"table name"）とバッククォートで囲まれたテーブル名（`table_name`）の両方に対応しています
• スキーマプレフィックス：スキーマで修飾されたテーブル名に対応しています（例：database.schema.table）
• コメント：チェック前に SQL コメントを削除します

フィルタリングされるクエリの例：

SELECT * FROM allowed_table
JOIN other_table ON allowed_table.id = other_table.id

エラー： Query references unauthorized tables: other_table. Allowed tables: allowed_table, prod_*

設定機能

フェイルファスト検証：

• ⚠️ PINOT_TABLE_FILTER_FILE が設定されているのにファイルが存在しない場合、サーバーは FileNotFoundError で起動に失敗します
• これにより、設定ミスが原因で誤ってすべてのテーブルが表示されるのを防ぎます
• 空のフィルターファイル、または included_tables キーがない場合は、すべてのテーブルが表示されます（フィルタリングなし）

包括的なフィルタリング：

• テーブルにアクセスするすべての MCP ツールは、実行前にフィルタリングを適用します
• すべてのテーブルアクセスポイントで一貫したフィルタリングが行われます
• 設定されたパターンに一致しないテーブルを明示する、わかりやすいエラーメッセージが表示されます

テーブルフィルタリングの無効化

テーブルフィルタリングを無効にするには、次のいずれかを行います。

1. PINOT_TABLE_FILTER_FILE 環境変数を削除する
2. .env ファイルで設定しない

設定されていない場合、Pinot クラスター内のすべてのテーブルが表示されます。

フィルターファイルで allow_all: true と空でない included_tables の両方を指定した場合、明示的な許可リストが優先され、サーバーは 警告をログに記録します。再読み込みを適用するには、変更されていないドライラン候補のトークンが必要です。

読み取り専用クエリの強制

read_query ツールは、SQL を Pinot に転送する前に必ず検証します。 受け付けるのは1つのステートメントのみで、そのステートメントは読み取り専用の SELECT または WITH ... SELECT クエリでなければなりません。SQL コメントは削除され、セミコロンで連結された複数のステートメントは拒否され、書き込み／DDL／管理用のキーワードはブロックされます。

OAuth 認証を設定する（任意）

OAuth 認証を有効にするには、.env ファイルで次の環境変数を設定します。

必須の変数（OAUTH_ENABLED=true の場合）：

• OAUTH_CLIENT_ID：OAuth クライアント ID
• OAUTH_CLIENT_SECRET：OAuth クライアントシークレット
• OAUTH_BASE_URL：MCP サーバーのベース URL
• OAUTH_AUTHORIZATION_ENDPOINT：OAuth 認可エンドポイントの URL
• OAUTH_TOKEN_ENDPOINT：OAuth トークンエンドポイントの URL
• OAUTH_JWKS_URI：トークン検証用の JSON Web Key Set URI
• OAUTH_ISSUER：トークン発行者の識別子

任意の変数：

• OAUTH_AUDIENCE：トークンの検証対象となるオーディエンスです。デフォルトは正規の MCP リソース URI（OAUTH_BASE_URL + MCP_PATH）です。プロバイダーが異なる aud を発行する場合（たとえば、IdP がクライアント ID を設定する場合）に設定します。
• OAUTH_GRANTED_SCOPES：認証済みプリンシパルに付与する Pinot スコープです（デフォルトでは 3 つすべて）。すべての OIDC 呼び出し元に対してデプロイを読み取り専用にするには、pinot:read を使用します。
• OAUTH_REQUIRED_SCOPES：アクセストークンにあらかじめ含まれている必要がある基本スコープです（デフォルトでは強制されません）。
• OAUTH_EXTRA_AUTH_PARAMS：JSON オブジェクトで指定する追加の認可パラメーターです（例：{"scope": "openid profile"}）

ツールレベルの認可では、pinot:read / pinot:write / pinot:admin を使用します。汎用 OIDC プロバイダーは固定のスコープカタログを発行し、これらのようなリソーススコープを発行できません。そのため、認証済みユーザーがツールを呼び出せるようにするには OAUTH_GRANTED_SCOPES が必要です。ツールを無制限に公開せず、スコープを絞ってください。

設定例：

OAUTH_ENABLED=true
OAUTH_CLIENT_ID=client-id
OAUTH_CLIENT_SECRET=client-secret
OAUTH_BASE_URL=http://localhost:8000
OAUTH_AUTHORIZATION_ENDPOINT=https://example.com/oauth/authorize
OAUTH_TOKEN_ENDPOINT=https://example.com/oauth/token
OAUTH_JWKS_URI=https://example.com/.well-known/jwks.json
OAUTH_ISSUER=https://example.com
OAUTH_AUDIENCE=http://localhost:8000/mcp
OAUTH_EXTRA_AUTH_PARAMS={"scope": "openid profile"}

サーバーを起動する

uv --directory . run mcp_pinot/server.py

サーバーが実行中であることを示すログが表示されます。

セキュリティに関する注意：

• デフォルトでは STDIO を使用します。HTTP を選択した場合は 127.0.0.1 にバインドされます。MCP_HOST=0.0.0.0 を設定するのは、OAuth または静的トークン認証に加えて TLS か認証済みリバースプロキシを使用する場合に限ってください。
• HTTP が非ループバックホストにバインドされていて、認証プロバイダー（AUTH_PROVIDER=oauth または static、あるいは従来の OAUTH_ENABLED=true）が設定されていない場合、サーバーは起動を拒否します。
• read_query は実行前に、単一の読み取り専用 SQL 文であることを検証します。これは安全対策であり、Pinot の認証および認可に代わるものではありません。
• サポート対象の mcp[cli] 依存関係には、Streamable HTTP サーバー向けの DNS リバインディング保護が含まれています。
• 確認の再利用状態とレート制限のバケットはプロセス内に保存されます。サーバープロセス／Helm レプリカは必ず 1 つだけ実行してください。チャートでは replicas != 1 は拒否されます。水平スケーリングには、共有ステートストアの実装が必要です。
• /readyz が報告するのは MCP プロセスの準備状況であり、Pinot クラスターの健全性ではありません。Pinot への依存関係を診断するには test_connection を使用してください。

Pinot Quickstart を起動する（任意）

docker を使って Pinot QuickStart を起動します。

docker run --name pinot-quickstart -p 2123:2123 -p 9000:9000 -p 8000:8000 -d apachepinot/pinot:1.5.1 QuickStart -type batch

MCP サーバーにクエリを実行する

uv --directory . run examples/example_client.py

このクイックスタートでは、すべてのツールを確認し、airlineStats テーブルにクエリを実行します。

Claude Desktop との統合

Claude の設定ファイルを開く

vi ~/Library/Application\ Support/Claude/claude_desktop_config.json

MCP サーバーのエントリを追加する

{
  "mcpServers": {
      "pinot_mcp": {
          "command": "/path/to/uv",
          "args": [
              "--directory",
              "/path/to/mcp-pinot-repo",
              "run",
              "mcp_pinot/server.py"
          ],
          "env": {
            // You can also include your .env config here
          }
      }
  }
}

/path/to/uv を uv コマンドの絶対パスに置き換えます。which uv を実行すると確認できます。

/path/to/mcp-pinot を、このリポジトリをクローンしたフォルダーの絶対パスに置き換えます。

注：Claude desktop で使用するには、サーバーの実行時に stdio トランスポートを使う必要があります。

複数の pinot クラスターに MCP サーバーとして接続する場合は、.env ファイルの代わりに、ここで環境変数を設定することもできます。

Claude Desktop を再起動する

Claude は起動時に MCP サーバーを自動で起動し、Pinot ベースの新しいツールを認識するようになります。

MCP Bundle の使用

リリースワークフローでは、Claude Desktop 用の MCP Bundle（.mcpb）が公開されます。付属の UV ランタイムが、ユーザーのプラットフォーム向けにロックされた依存関係をインストールするため、小さな Bundle 1 つで macOS、Linux、Windows に対応できます。ローカルでビルドするには：

npm install -g @anthropic-ai/[email protected]
mcpb validate manifest.json
mcpb pack

生成された .mcpb ファイルを開いて、Claude Desktop にインストールします。

セキュリティと脆弱性の報告

脆弱性の報告手順、セキュリティカテゴリ、MCP HTTP エンドポイントを安全に公開するためのチェックリストについては、SECURITY.md をご覧ください。

開発者向け

• MCP ツールの定義は mcp_pinot/server.py にあり、Pinot の HTTP／DB 操作は mcp_pinot/pinot_client.py にあります。
• 依存関係のポリシー、SDK 2 の統合に関する変更、検証、ロールバックについては、MCP SDK との互換性と移行をご覧ください。

ビルド

次のコマンドでプロジェクトをビルドします。

uv sync --frozen

テスト

次のコマンドでリポジトリをテストします。

uv run pytest --cov=mcp_pinot

Docker イメージのビルド

docker build -t mcp-pinot .

コンテナの実行

docker run --rm -i -v "$(pwd)/.env:/app/config/.env:ro" mcp-pinot

これはデフォルトの STDIO トランスポートを使用します。HTTP／Kubernetes 環境にデプロイする場合は、ループバック以外のアドレスにバインドする前に、インバウンド認証プロバイダーを設定してください。詳細は、上記の設定と Helm のセクションをご覧ください。