Overview

@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 dataset client the rest of your app uses, whether that app is TypeScript or Python (Python backends have a native server)
• avoid handing an LLM a direct SQL console

How it fits together

Quick start with the CLI

If your project already serves datasets with @hypequery/serve, the CLI can expose them over MCP with no extra config. Install the MCP server package alongside the CLI:

npm install @hypequery/mcp
npm install -D @hypequery/cli

Then, from your project root:

npx hypequery mcp

The command finds your Serve API file (analytics/api.ts, hypequery.ts, or analytics/queries.ts, among others) and serves the datasets registered with serve({ queryBuilder, datasets }). Pass a file to choose one explicitly, or --path for a different analytics directory:

npx hypequery mcp ./src/analytics/api.ts
npx hypequery mcp --path src/analytics

If any dataset has a tenantKey, pass the trusted tenant the server should run as. The server refuses to start without one:

npx hypequery mcp --tenant acme

Check the setup without starting the server:

npx hypequery mcp --self-test

Datasets served from Python

A Python backend (hypequery.serve) has its own MCP server, with the same four tools, the same input schemas and the same MCP_* errors as @hypequery/mcp. It serves the API's authorized client contract: the endpoints the caller's principal may call, with their fields and limits. The API keeps ownership of SQL, authentication and the tenant.

pip install "hypequery[mcp]"
hypequery mcp app:api --self-test

app:api is the Api from create_api (or the ASGI app from to_asgi_app). Each tool call goes through Api.handle in the same process, so authentication, endpoint policy, rate limits and tenant resolution are exactly the ones an HTTP caller meets, without running a server. The hypequery init scaffolds already publish a client contract; in your own API, give endpoints client_profile=ClientQueryProfile() and call add_client_contract_endpoint(api); the server reads that route and never changes the API.

To reach an API that is already deployed instead, bridge its discovery route:

HYPEQUERY_API_KEY=… hypequery mcp --client-contract-url https://analytics.example.com/v1/client-contract

• The URL is the backend's discovery route (add_client_contract_endpoint). It must be HTTPS, or plain HTTP on localhost, 127.0.0.1 or [::1], and must not contain credentials, a query string or a fragment.
• HYPEQUERY_API_KEY is sent as Authorization: Bearer …, in-process or to that origin only; --header 'Name: value' sends any other credential. Redirects are refused, so a credential is never forwarded elsewhere.
• One process serves one principal. Its tenant comes from that principal on the Python side; there is no tenant tool argument.
• If the backend's definitions change while the server runs, tools fail with MCP_STALE_CONTRACT. Restart it to load the new contract.

--self-test reads and validates the contract and counts the endpoints it would expose, without calling any query tool. --print-config prints the mcpServers entry for Claude, Cursor or another MCP client.

The Node bridge, npx hypequery mcp --client-contract-url … with @hypequery/mcp installed, serves the same contract with the same tools and remains supported.

The server speaks MCP over stdio, so an MCP client normally launches it. See Clients for Claude Desktop and Cursor configuration.

Standalone server

Use @hypequery/mcp directly when you don't have a Serve API, or want a dedicated config file for the agent:

npm install @hypequery/mcp @hypequery/datasets @hypequery/clickhouse
npx hypequery-mcp --config ./mcp-config.mjs

The config file exports datasets and an analytics dataset client; Configuration shows a minimal one, publishing several datasets, and the metadata agents see. To register the server with Claude Desktop or Cursor, see Clients.