Pinot MCP Server

Un servidor MCP

Documentación

Pinot MCP Server

Tabla de Contenidos

Resumen
Características
Inicio Rápido
Referencia de Configuración
Compilación Docker
Integración con Claude Desktop
Probar un Prompt
Seguridad y Reporte de Vulnerabilidades
Notas para Desarrolladores

Resumen

Este proyecto es un servidor Model Context Protocol (MCP) basado en Python para interactuar con Apache Pinot. Está construido usando el framework FastMCP. Está diseñado para integrarse con Claude Desktop para habilitar consultas de analítica y metadatos en tiempo real en un clúster de Pinot.

Permite:

Listar tablas, segmentos e información de esquemas de Pinot
Ejecutar consultas SQL de solo lectura
Ver metadatos de índices/nivel de columna
Diseñado para asistir a usuarios de negocio mediante la integración con Claude
y mucho más.

Características

Cada herramienta anuncia esquemas JSON de entrada y salida tipados, anotaciones de riesgo MCP y orientación para la recuperación de fallos para la planificación de agentes.
Las respuestas grandes de consultas, tablas, nombres de segmentos y metadatos de segmentos usan páginas limitadas con metadatos de continuación en lugar de devolver contexto de agente ilimitado.
El SQL de solo lectura se analiza y se aplica antes de la ejecución; los errores de validación, permisos y conectividad transitoria se muestran como errores MCP accionables.
Cada herramienta de mutación admite dry_run; siempre previsualiza el objetivo y la carga útil exactos antes de aplicar. Aplicar requiere el confirmation_token de corta duración y de un solo uso de la previsualización, incluso para recargas de filtros de tabla. Una previsualización no es una garantía de que Pinot aceptará la escritura posterior.
Las herramientas de inspección de esquemas y configuración de tablas de propósito único evitan operaciones combinadas ambiguas: usa get_schema y get_table_config de forma independiente.

Contrato de Herramientas MCP

Los nombres de las herramientas distinguen entre mayúsculas y minúsculas y usan guiones bajos. La versión 4 renombró cuatro herramientas para que cada operación sea verbo-primero; los clientes que usan los nombres anteriores sustantivo-primero deben actualizar sus llamadas.

Herramienta	Propósito
`test_connection`	Diagnosticar la conectividad del broker, controlador y consultas.
`list_tables`	Listar los nombres de tablas visibles de Pinot.
`get_schema`	Obtener el esquema de columnas de una tabla.
`get_table_config`	Obtener la configuración de indexación e ingesta de una tabla.
`get_table_size`	Obtener el tamaño de almacenamiento reportado y estimado de una tabla.
`list_segments`	Listar los nombres exactos de segmentos de una tabla.
`list_segment_metadata`	Paginar a través de los metadatos de los segmentos de una tabla.
`get_segment_index_metadata`	Inspeccionar los índices por columna de un segmento exacto.
`read_query`	Ejecutar una consulta SQL de solo lectura de Pinot.
`create_schema` / `update_schema`	Previsualizar o aplicar cambios de esquema.
`create_table_config` / `update_table_config`	Previsualizar o aplicar cambios de configuración de tabla.
`reload_table_filters`	Previsualizar o aplicar el YAML de filtro de tabla configurado.

Para cada cambio de esquema, configuración de tabla o filtro de tabla, primero llama a la misma herramienta con dry_run=true, presenta la previsualización al usuario y llámala con dry_run=false y el confirmation_token de un solo uso de la previsualización solo después de la confirmación. Editar un archivo de filtro de tabla después de la previsualización invalida su token. Pinot realiza una validación autoritativa durante las llamadas de aplicación de tabla/esquema, por lo que una escritura aún puede fallar después de una previsualización exitosa.

StarTree Server for Apache Pinot MCP server

Pinot MCP en Acción

Mira Pinot MCP en acción a continuación:

Obtención de Metadatos

Pinot MCP fetching metadata

Obtención de Datos, seguido de análisis

Prompt: ¿Puedes hacer un gráfico de histograma de los eventos de GitHub a lo largo del tiempo? Pinot MCP fetching data and analyzing table

Prompts de Ejemplo

Una vez que Claude esté en ejecución, haz clic en el ícono de martillo 🛠️ y prueba estos prompts:

¿Puedes ayudarme a analizar mis datos en Pinot? Usa la herramienta de Pinot y mira la lista de tablas para empezar.
¿Puedes hacer un gráfico de histograma de los eventos de GitHub a lo largo del tiempo?

Inicio Rápido

Requisitos Previos

Instalar uv (si aún no está instalado)

uv es un instalador y resolutor de paquetes de Python rápido, escrito en Rust. Está diseñado para ser un reemplazo directo de pip con un rendimiento significativamente mejor.

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

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

Instalación

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

Configurar el Clúster de Pinot

El servidor MCP espera un archivo .env de estilo de configuración de uvicorn en el directorio raíz para configurar la conexión al clúster de Pinot. Este repositorio incluye un archivo .env.example de muestra que asume una configuración de inicio rápido de pinot.

mv .env.example .env

Referencia de Configuración

El servidor carga la configuración desde variables de entorno y desde un archivo .env encontrado en el directorio de trabajo actual. Las variables de entorno del proceso tienen prioridad sobre .env, por lo que los ajustes de tiempo de implementación no pueden ser reemplazados silenciosamente por un archivo verificado.

Perfiles Comunes

Caso de uso	Configuración requerida	Notas
Claude Desktop	`MCP_TRANSPORT=stdio`	Predeterminado y recomendado para uso de escritorio local; no se inicia ningún listener HTTP.
HTTP local	`MCP_TRANSPORT=http`, `MCP_HOST=127.0.0.1`	Perfil web local explícito. Accesible solo desde la misma máquina.
HTTP/HTTPS remoto	`MCP_TRANSPORT=http`, `MCP_HOST=0.0.0.0`, `MCP_ALLOWED_HOSTS=<host[:port]>`, `AUTH_PROVIDER=oauth`\|`static`\|`oauth+static`	El servidor rechaza enlaces HTTP/HTTPS no loopback a menos que un proveedor de autenticación esté activo, y un enlace comodín requiere una lista de Host permitidos explícita. Usa `oauth+static` para servir a usuarios interactivos y a un backend de confianza a la vez. Usa TLS directamente o un proxy inverso autenticado.
Exposición Helm	`service.enabled=true`, `mcp.host=0.0.0.0`, `mcp.oauth.enabled=true`	Los valores predeterminados de Helm son solo locales y no renderizan ningún Service a menos que la exposición esté explícitamente habilitada.

Conexión a Pinot

Variable	Predeterminado	Descripción
`PINOT_CONTROLLER_URL`	`http://localhost:9000`	Endpoint del controlador de Pinot utilizado para operaciones de metadatos y tabla/esquema.
`PINOT_BROKER_URL`	`http://localhost:8000`	Endpoint del broker de Pinot utilizado para consultas SQL.
`PINOT_BROKER_HOST`	Analizado desde `PINOT_BROKER_URL`	Anulación opcional del host para la conexión al broker.
`PINOT_BROKER_PORT`	Analizado desde `PINOT_BROKER_URL`	Anulación opcional del puerto para la conexión al broker.
`PINOT_BROKER_SCHEME`	Analizado desde `PINOT_BROKER_URL`	Anulación opcional del esquema, usualmente `http` o `https`.
`PINOT_USERNAME` / `PINOT_PASSWORD`	sin establecer	Autenticación básica para Pinot.
`PINOT_TOKEN`	sin establecer	Token Bearer o crudo para Pinot; tiene prioridad sobre `PINOT_TOKEN_FILENAME`.
`PINOT_TOKEN_FILENAME`	sin establecer	Archivo que contiene un token de Pinot. Un archivo faltante o vacío registra una advertencia y continúa sin autenticación de token.
`PINOT_DATABASE`	vacío	Encabezado de base de datos opcional para implementaciones de Pinot multi-base de datos.
`PINOT_USE_MSQE`	`false`	Habilita la opción de consulta del motor de consultas multi-etapa de Pinot.
`PINOT_REQUEST_TIMEOUT`	`60`	Tiempo de espera de solicitud HTTP en segundos.
`PINOT_CONNECTION_TIMEOUT`	`60`	Tiempo de espera de conexión HTTP en segundos.
`PINOT_QUERY_TIMEOUT`	`60`	Tiempo de espera de consulta SQL en segundos.

Servidor MCP

Variable	Predeterminado	Descripción
`MCP_TRANSPORT`	`stdio`	Modo de transporte. Usa `stdio` para clientes de escritorio y `http` para clientes HTTP Streamable.
`MCP_HOST`	`127.0.0.1`	Host de enlace HTTP. Establece `0.0.0.0` solo con un proveedor de autenticación habilitado.
`MCP_PORT`	`8080`	Puerto de escucha HTTP.
`MCP_PATH`	`/mcp`	Ruta HTTP de MCP.
`MCP_ALLOWED_HOSTS`	host exacto[:puerto] de un enlace concreto	Autoridades de Host separadas por comas aceptadas en el endpoint MCP. Un enlace comodín (`0.0.0.0`, `::`) no tiene una autoridad pública inferible, por lo que el valor predeterminado es vacío y el servidor se cierra al inicio hasta que enumeres los nombres que usan los clientes, p. ej. `mcp.example.com,mcp.example.com:443`.
`MCP_ALLOWED_ORIGINS`	sin establecer	Valores de `Origin` del navegador separados por comas aceptados. Vacío rechaza solicitudes que envían `Origin` mientras aún permite clientes que lo omiten.
`MCP_SSL_KEYFILE`	sin establecer	Ruta de la clave privada TLS. Requiere `MCP_SSL_CERTFILE`.
`MCP_SSL_CERTFILE`	sin establecer	Ruta del certificado TLS. Requiere `MCP_SSL_KEYFILE`.
`MCP_LOG_LEVEL`	`INFO`	Nivel de registro de la aplicación: `DEBUG`, `INFO`, `WARNING`, `ERROR` o `CRITICAL`. Los registros van a stderr para que la salida del protocolo STDIO siga siendo válida.
`MCP_RATE_LIMIT_RPS` / `MCP_RATE_LIMIT_BURST`	`10` / `20`	Límites de tasa y ráfaga de llamadas a herramientas por principal (autenticado) o por par (HTTP loopback).
`MCP_RATE_LIMIT_MAX_CLIENTS`	`10000`	Máximo de buckets de clientes en memoria; los buckets menos recientemente usados se desalojan.
`MCP_RATE_LIMIT_IDLE_TTL_SECONDS`	`600`	Tiempo de inactividad antes de que un bucket de límite de tasa pueda ser desalojado.
`MCP_CONFIRMATION_TTL_SECONDS`	`300`	Vida útil del token de confirmación, limitada a 30–3600 segundos. Los tokens están vinculados al proceso y fallan intencionalmente después de un reinicio.

Autenticación

Se requiere un proveedor de autenticación antes de enlazar HTTP o HTTPS a un host no loopback.

Variable	Predeterminado	Descripción
`AUTH_PROVIDER`	sin establecer	Proveedor de autenticación activo: `none` (predeterminado), `oauth`, `static` o `oauth+static`. Se requiere algún proveedor antes de un enlace no loopback.
		`oauth+static` acepta tanto un inicio de sesión OIDC como el token compartido en una sola implementación — el caso alojado habitual, donde las personas usan un navegador y un backend de confianza no puede. Cualquier ortografía funciona; el secreto compartido se verifica primero, y cada credencial mantiene sus propios ámbitos (`MCP_STATIC_SCOPES` vs `OAUTH_GRANTED_SCOPES`).
`MCP_STATIC_TOKEN`	vacío	Secreto Bearer compartido para `AUTH_PROVIDER=static` — un llamador de servicio a servicio lo envía como `Authorization: Bearer <token>`. Requerido cuando el proveedor estático está activo.
`MCP_STATIC_SCOPES`	`pinot:read pinot:write pinot:admin`	Ámbitos separados por espacios o comas otorgados al principal estático. Usa `pinot:read` para un servicio de solo lectura.
`OAUTH_ENABLED`	`false`	Indicador heredado; `true` es equivalente a `AUTH_PROVIDER=oauth`. Habilita la autenticación OAuth.
`OAUTH_CLIENT_ID`	vacío	ID de cliente OAuth.
`OAUTH_CLIENT_SECRET`	vacío	Secreto de cliente OAuth.
`OAUTH_BASE_URL`	`http://localhost:8080`	URL base pública para este servidor MCP.
`OAUTH_AUTHORIZATION_ENDPOINT`	vacío	Endpoint de autorización ascendente.
`OAUTH_TOKEN_ENDPOINT`	vacío	Endpoint de token ascendente.
`OAUTH_JWKS_URI`	vacío	URI JWKS utilizada para la verificación de tokens.
`OAUTH_ISSUER`	vacío	Emisor de token esperado.
`OAUTH_AUDIENCE`	URI de recurso MCP canónico	Audiencia contra la que se validan los tokens. El valor predeterminado es `OAUTH_BASE_URL` (sin barra final) más `MCP_PATH`, que es lo que anuncia los metadatos de RFC 9728. Establécelo explícitamente cuando el proveedor emita un `aud` diferente — muchos (Dex entre ellos) lo establecen al ID de cliente; el servidor registra una advertencia y honra tu valor.
`OAUTH_GRANTED_SCOPES`	`pinot:read pinot:write pinot:admin`	Ámbitos de Pinot otorgados a cada principal que este proveedor autentica, unidos a los ámbitos que el token ya lleva. Necesario porque los proveedores OIDC de propósito general emiten un catálogo de ámbitos fijo y no pueden acuñar `pinot:*`, por lo que sin una concesión cada llamada de herramienta de un usuario válido sería denegada. Establécelo a `pinot:read` para una implementación de solo lectura.
`OAUTH_EXTRA_AUTH_PARAMS`	sin establecer	Objeto JSON opcional con parámetros de autorización adicionales.

Filtrado de Tablas

Variable	Predeterminado	Descripción
`PINOT_TABLE_FILTER_FILE`	sin establecer	Archivo YAML con patrones glob de `included_tables`. Si está configurado y falta, el inicio falla.

Consulta SECURITY.md para la lista de verificación de exposición en producción y el proceso de reporte de vulnerabilidades.

Configurar el Filtrado de Tablas (Opcional)

⚠️ Nota de seguridad: Para el control de acceso en producción, use las ACL nativas a nivel de tabla de Pinot (disponibles desde Pinot 0.8.0+). El filtrado de tablas en este servidor MCP es una función de conveniencia para organizar tablas y mejorar la experiencia de usuario, no un límite de seguridad. Utiliza un análisis SQL de mejor esfuerzo y no debe considerarse como una medida de seguridad.

El filtrado de tablas le permite controlar qué tablas de Pinot son visibles a través del servidor MCP. Esto es útil para:

Reducir la carga cognitiva: Concéntrese en las tablas relevantes cuando su clúster de Pinot tiene cientos o miles de tablas
Experiencia multiinquilino: Ejecute múltiples instancias del servidor MCP contra el mismo clúster de Pinot, mostrando cada una diferentes subconjuntos de tablas para diferentes equipos o casos de uso
Separación de entornos: Implemente diferentes instancias del servidor MCP (desarrollo, staging, producción) que muestren solo tablas específicas del entorno
Ocultar tablas del sistema: Filtre tablas internas, de prueba o obsoletas de la vista del usuario final

Cuando el filtrado de tablas está habilitado, todas las operaciones de tablas se filtran para mostrar solo las tablas configuradas.

Qué se filtra

El filtrado de tablas se aplica en todas las operaciones MCP:

Listado de tablas: Solo las tablas configuradas aparecen en las listas de tablas
Ejecución de consultas: Las consultas SQL se verifican para asegurar que todas las tablas referenciadas (en FROM, JOIN, subconsultas, CTE, etc.) coincidan con los patrones configurados
Operaciones de tablas: Las operaciones de acceso directo a tablas filtran por nombre de tabla:
- Obtener detalles, tamaño y metadatos de la tabla
- Obtener segmentos de tabla y metadatos de segmentos
- Obtener detalles de índices/columnas
- Obtener/actualizar configuraciones de tablas
Operaciones de esquemas: Las operaciones de esquemas filtran por nombre de esquema:
- Obtener/crear/actualizar esquemas
- Crear configuraciones de tablas

Configuración

Copie el archivo de configuración de ejemplo:

cp table_filters.yaml.example table_filters.yaml

Edite table_filters.yaml para especificar qué tablas incluir:

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

Configure la ruta del archivo de filtro en su .env:

PINOT_TABLE_FILTER_FILE=table_filters.yaml

Coincidencia de patrones

El filtro admite patrones de estilo glob utilizando la coincidencia estándar de patrones de nombres de archivo Unix:

exact_table_name - Coincide exactamente con esta tabla
prefix_* - Coincide con todas las tablas que comienzan con "prefix_"
*_suffix - Coincide con todas las tablas que terminan con "_suffix"
*pattern* - Coincide con todas las tablas que contienen "pattern"
sharded_table_? - Coincide con tablas con exactamente un carácter después del guion bajo (por ejemplo, sharded_table_1, sharded_table_a)

Filtrado de consultas

Cuando el filtrado está habilitado, las consultas SQL se verifican antes de la ejecución:

Funciones SQL compatibles: Cláusulas FROM, cláusulas JOIN (INNER, LEFT, RIGHT, OUTER, CROSS), subconsultas, CTE (WITH) y listas de tablas separadas por comas
Identificadores entre comillas: Admite nombres de tablas entre comillas dobles ("table name") y entre comillas invertidas (`table_name`)
Prefijos de esquema: Maneja nombres de tablas calificados por esquema (por ejemplo, database.schema.table)
Comentarios: Elimina los comentarios SQL antes de verificar

Ejemplo de consulta filtrada:

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

Error: Query references unauthorized tables: other_table. Allowed tables: allowed_table, prod_*

Características de configuración

Validación de fallo rápido:

⚠️ Si PINOT_TABLE_FILTER_FILE está configurado pero el archivo no existe, el servidor fallará al iniciar con un FileNotFoundError
Esto evita mostrar accidentalmente todas las tablas debido a una configuración incorrecta
Archivos de filtro vacíos o la falta de la clave included_tables mostrarán todas las tablas (sin filtrado)

Filtrado integral:

Todas las herramientas MCP que acceden a tablas aplican el filtrado antes de la ejecución
Filtrado consistente en todos los puntos de acceso a tablas
Mensajes de error claros indican qué tablas no coinciden con los patrones configurados

Deshabilitar el filtrado de tablas

Para deshabilitar el filtrado de tablas, ya sea:

Elimine la variable de entorno PINOT_TABLE_FILTER_FILE, o
No la configure en su archivo .env

Cuando no está configurado, todas las tablas del clúster de Pinot son visibles.

Cuando un archivo de filtro proporciona tanto allow_all: true como una lista included_tables no vacía, la lista de permitidos explícita tiene prioridad y el servidor registra una advertencia. Aplicar una recarga requiere el token de un candidato de prueba sin cambios.

Cumplimiento de consultas de solo lectura

La herramienta read_query siempre valida SQL antes de reenviarlo a Pinot. Acepta solo una declaración, y esa declaración debe ser una consulta de solo lectura SELECT o WITH ... SELECT. Los comentarios SQL se eliminan, las declaraciones apiladas con punto y coma se rechazan, y las palabras clave de escritura/DDL/administración están bloqueadas.

Configurar autenticación OAuth (Opcional)

Para habilitar la autenticación OAuth, configure las siguientes variables de entorno en su archivo .env:

Variables requeridas (cuando OAUTH_ENABLED=true):

OAUTH_CLIENT_ID: ID de cliente OAuth
OAUTH_CLIENT_SECRET: Secreto de cliente OAuth
OAUTH_BASE_URL: URL base de su servidor MCP
OAUTH_AUTHORIZATION_ENDPOINT: URL del punto final de autorización OAuth
OAUTH_TOKEN_ENDPOINT: URL del punto final de token OAuth
OAUTH_JWKS_URI: URI del conjunto de claves web JSON para verificación de tokens
OAUTH_ISSUER: Identificador del emisor de tokens

Variables opcionales:

OAUTH_AUDIENCE: audiencia contra la que se validan los tokens. Por defecto, la URI canónica del recurso MCP (OAUTH_BASE_URL + MCP_PATH). Configúrela cuando su proveedor emita un aud diferente — por ejemplo, un IdP que coloque el ID de cliente allí.
OAUTH_GRANTED_SCOPES: Alcances de Pinot otorgados a los principales autenticados (por defecto los tres). Use pinot:read para hacer que la implementación sea de solo lectura para cada llamador OIDC.
OAUTH_REQUIRED_SCOPES: Alcances base que un token de acceso ya debe llevar (por defecto: ninguno aplicado).
OAUTH_EXTRA_AUTH_PARAMS: Parámetros de autorización adicionales como objeto JSON (por ejemplo, {"scope": "openid profile"})

La autorización a nivel de herramienta utiliza pinot:read / pinot:write / pinot:admin. Los proveedores OIDC de propósito general emiten un catálogo de alcances fijo y no pueden acuñar alcances de recursos como estos, por lo que OAUTH_GRANTED_SCOPES es lo que permite que un usuario autenticado pueda llamar a cualquier cosa — redúzcalo en lugar de dejar herramientas sin control.

Ejemplo de configuración:

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

Ejecutar el servidor

uv --directory . run mcp_pinot/server.py

Debería ver registros que indican que el servidor está en ejecución.

Notas de seguridad:

STDIO es el predeterminado. Cuando se selecciona HTTP, se vincula a 127.0.0.1; configure MCP_HOST=0.0.0.0 solo con autenticación OAuth o token estático más TLS o un proxy inverso autenticado.

El servidor se niega a iniciar cuando HTTP está vinculado a un host no loopback sin un proveedor de autenticación (AUTH_PROVIDER=oauth o static, o el OAUTH_ENABLED=true heredado).

read_query aplica una sola declaración SQL de solo lectura antes de la ejecución. Esto es una salvaguarda, no un reemplazo para la autenticación y autorización de Pinot.

La dependencia compatible mcp[cli] incluye protecciones contra el rebinding de DNS para el servidor HTTP Streamable.

El estado de reproducción de confirmación y los buckets de límite de velocidad son locales al proceso. Ejecute exactamente un proceso de servidor/réplica de Helm. El gráfico rechaza replicas != 1; el escalado horizontal requiere una implementación de almacén de estado compartido.

/readyz informa la preparación del proceso MCP, no la salud del clúster de Pinot. Use test_connection para diagnosticar dependencias de Pinot.

Iniciar Pinot Quickstart (Opcional)

Inicie Pinot QuickStart usando docker:

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

Consultar el servidor MCP

uv --directory . run examples/example_client.py

Este quickstart solo verifica todas las herramientas y consulta la tabla airlineStats.

Integración con Claude Desktop

Abra el archivo de configuración de Claude

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

Agregue una entrada de servidor 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
          }
      }
  }
}

Reemplace /path/to/uv con la ruta absoluta al comando uv; puede ejecutar which uv para averiguarlo.

Reemplace /path/to/mcp-pinot con la ruta absoluta a la carpeta donde clonó este repositorio.

Nota: debe usar el transporte stdio al ejecutar su servidor para usarlo con Claude Desktop.

También puede configurar variables de entorno aquí en lugar del archivo .env, en caso de que desee conectarse a múltiples clústeres de Pinot como servidores MCP.

Reinicie Claude Desktop

Claude ahora iniciará automáticamente el servidor MCP al inicio y reconocerá las nuevas herramientas basadas en Pinot.

Uso del paquete MCP

El flujo de trabajo de publicación publica un paquete MCP de Claude Desktop (.mcpb). Su entorno de ejecución UV instala las dependencias bloqueadas para la plataforma del usuario, por lo que un pequeño paquete funciona en macOS, Linux y Windows. Para construir uno localmente:

npm install -g @anthropic-ai/mcpb@2.1.2
mcpb validate manifest.json
mcpb pack

Abra el archivo .mcpb resultante para instalarlo en Claude Desktop.

Seguridad y reporte de vulnerabilidades

Consulte SECURITY.md para instrucciones de reporte de vulnerabilidades, categorías de seguridad y la lista de verificación para exponer de manera segura el punto final HTTP MCP.

Desarrollador

Las definiciones de herramientas MCP viven en mcp_pinot/server.py; las operaciones HTTP/DB de Pinot viven en mcp_pinot/pinot_client.py.

Construir

Construya el proyecto con

uv sync --frozen

Probar

Pruebe el repositorio con:

uv run pytest --cov=mcp_pinot

Construir la imagen Docker

docker build -t mcp-pinot .

Ejecutar el contenedor

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

Esto utiliza el transporte STDIO predeterminado. Para implementaciones HTTP/Kubernetes, configure un proveedor de autenticación entrante antes de vincularse a una dirección no loopback; consulte las secciones de configuración y Helm anteriores.