Connect an LLM agent

datahashi implements the Model Context Protocol (MCP) over Streamable HTTP. An AI agent reads your metric catalog. It emits a structured query. It does not invent raw SQL.

The agent never sees warehouse tables, credentials, or SQL syntax.

flowchart TD
    A["AI agent<br/>Claude · Cursor"] -->|"MCP over HTTP (/mcp)<br/>bearer token or OAuth"| S
    subgraph S["datahashi MCP server"]
        direction TB
        T1["1 · list_catalog<br/>discovers granted metrics and dimensions"]
        T2["2 · describe_metric<br/>reads formulas, units, time axes"]
        T3["3 · list_dimension_values<br/>checks real values, e.g. valid regions"]
        T4["4 · run_semantic_query<br/>executes the governed query"]
        T5["5 · refine_semantic_query<br/>modifies the previous query by delta"]
        T6["6 · drill_down<br/>decomposes a cell into granular rows"]
        T7["7 · expand_hierarchy<br/>walks one hierarchy level"]
        T8["8 · get_lineage<br/>shows what a member depends on"]
    end

All eight tools operate on granted entities and metrics. If an agent asks for an ungranted dimension, the engine rejects the request. The warehouse never runs that query.

Connect the agent

Endpoint URL

Point your MCP client at the engine /mcp route:

https://<engine-host>/mcp

Authentication

Send the data-plane API key in the authorization header:

Authorization: Bearer <your-datahashi-key>

The engine also supports RFC 9728 MCP OAuth discovery at /.well-known/oauth-protected-resource.

Claude Desktop configuration

Add datahashi to claude_desktop_config.json:

{
  "mcpServers": {
    "datahashi": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote-client",
        "https://engine.datahashi.internal/mcp"
      ],
      "env": {
        "AUTHORIZATION": "Bearer your-datahashi-api-key"
      }
    }
  }
}

Cursor configuration

In Cursor, open Settings → Features → MCP, and add:

• Type: command or streamable-http
• URL: https://<engine-host>/mcp
• Headers: Authorization: Bearer <key>

MCP tools

datahashi gives eight native MCP tools:

Tool	Purpose	Annotations
list_catalog	Discover metrics, dimensions, entities, and name collisions for this credential. Accepts an entity filter.	ReadOnly, Idempotent
describe_metric	Read definitions: description, unit, format, default time dimension, and underlying entities. Several names in one call.	ReadOnly, Idempotent
run_semantic_query	Run a governed query (metrics, dimensions with grains, filters, having, order, limit, offset).	ReadOnly, Idempotent
refine_semantic_query	Change an existing query without restating it (add_dimensions, add_filters, drop_filters).	ReadOnly, Idempotent
drill_down	Drill into one aggregated cell. measure is a raw measure, never a metric.	ReadOnly, Idempotent
list_dimension_values	Fetch distinct values for a dimension from the warehouse. Optional substring filter q.	ReadOnly, Idempotent
expand_hierarchy	Walk one level of a hierarchy from list_catalog. path is the levels already chosen, broadest first.	ReadOnly, Idempotent
get_lineage	Show what a member depends on, and what depends on it. node is an id such as metric:total_gmv. Business names only.	ReadOnly, Idempotent

Tool examples

1. Discover metrics (list_catalog)

The agent calls list_catalog to see which numbers it may report:

{
  "entity": "Order"
}

2. Inspect metric definitions (describe_metric)

The agent reads formulas and time axes before it queries:

{
  "names": ["avg_order_value", "region"]
}

3. Run a query (run_semantic_query)

{
  "measures": ["Order.revenue"],
  "dimensions": [
    { "name": "order_date", "entity": "Order", "grain": "month" },
    "Customer.region"
  ],
  "filters": [
    { "dimension": "status", "entity": "Order", "op": "eq", "value": "completed" }
  ],
  "limit": 10
}

4. Refine a query (refine_semantic_query)

To add a filter or a dimension, the agent passes the previous query as base:

{
  "base": {
    "measures": ["Order.revenue"],
    "dimensions": ["Customer.region"]
  },
  "add_dimensions": [{ "name": "plan_tier", "entity": "Customer" }],
  "add_filters": [{ "dimension": "region", "entity": "Customer", "op": "eq", "value": "emea" }]
}

Next: Install Query Runner · Self-host the community engine.