Configuration

The CLI loads a config file with dynamic import(). The config must export:

• datasets: a registry of dataset names to dataset instances
• analytics: a dataset client created with createDatasetClient

Minimal config

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

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

export const datasets = {
  users: Users,
};

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

Run it:

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

Publish multiple datasets

Chain one publish call per dataset. alias sets the public registry name when it should differ from the dataset's own name.

import { publishDatasets } from '@hypequery/datasets';
import { Orders } from './datasets/orders.js';
import { Customers } from './datasets/customers.js';

export const datasets = publishDatasets()
  .publish(Orders)
  .publish(Customers, { alias: 'accounts' })
  .build();

Agents see two datasets, orders and accounts.

Related datasets

Relationships follow the alias their target was published under. Because Customers is published as accounts, the customer relationship declared on Orders targets accounts, and agents can select customer.tier against a dataset they can also list on its own. See Relationships.

Metadata for agents

MCP schema introspection exposes dataset, dimension, and measure metadata. Add labels and descriptions where field names alone are ambiguous.

measures: {
  revenue: measure.sum('amount', {
    label: 'Revenue',
    description: 'Total completed order revenue.',
  }),
}

Config path

Use an absolute path when configuring desktop clients. Relative paths depend on the client's launch directory and are a common source of connection failures.