Overview

Expose Hypequery datasets and metrics to AI agents through the Model Context Protocol.

@hypequery/mcp exposes your Hypequery semantic layer through the Model Context Protocol. Agents can discover datasets, inspect schema metadata, query named metrics, and run governed dataset queries without receiving raw SQL access.

Use MCP when you want an agent to work inside a constrained analytics vocabulary:

expose only the datasets you register
expose only named metrics you attach to those datasets
let agents inspect dimensions, labels, descriptions, filters, tenant keys, and time keys
execute through the same createDatasetClient path used by the rest of your app
avoid handing an LLM a direct SQL console

MCP is a capability boundary, not an authentication layer. If your data is multi-tenant, read Safety model before exposing a server broadly.

Install

npm install @hypequery/mcp @hypequery/datasets @hypequery/clickhouse
# or
pnpm add @hypequery/mcp @hypequery/datasets @hypequery/clickhouse

Quick start

Create an ESM config file that exports datasets and analytics.

// mcp-config.mjs
import { createQueryBuilder } from '@hypequery/clickhouse';
import { createDatasetClient } from '@hypequery/datasets';
import { Orders } from './datasets/orders.js';

const db = createQueryBuilder({
  url: process.env.CLICKHOUSE_URL,
  username: process.env.CLICKHOUSE_USER,
  password: process.env.CLICKHOUSE_PASSWORD,
  database: process.env.CLICKHOUSE_DATABASE,
});

const revenue = Orders.metric('revenue', {
  measure: 'revenue',
  label: 'Revenue',
  description: 'Total order revenue.',
});

export const datasets = {
  orders: {
    ...Orders,
    metrics: { revenue },
  },
};

export const analytics = createDatasetClient({ queryBuilder: db });

Run the MCP server with the config file path:

npx hypequery-mcp --config ./mcp-config.mjs

Overview

Install

Quick start

On this page