Semantic Layer Agent Tools#
The Hopsworks MCP server gives an agent tools to discover the metrics and saved queries of a project's semantic projects, query them, compile their definitions, and build Superset dashboards of them. The discovery and query tools have the names of the semantic layer tools of the dbt MCP server. list_exports lists the feature groups that saved queries keep filled, which an agent can then read like any feature group.
Run the MCP server#
The server ships with the Hopsworks Python library, in the mcp extra:
pip install "hopsworks[python,mcp]"
hopsworks-mcp --transport stdio --hopsworks_host my.hopsworks.ai --project demo \
--api_key_file ~/.hopsworks/api_key
Without --transport stdio, the server listens over HTTP on 127.0.0.1:8000; --host and --port change the address, and a non-loopback address needs --auth-token. The tools act on the project the server is logged in to, from the start options or the login tool. The API key needs the FEATURESTORE and TRINO scopes for the semantic layer tools, since their queries run as the key's user, see Who a query runs as.
Tools#
| Tool | Tag | Arguments | Returns |
|---|---|---|---|
list_semantic_projects | READ | Each semantic project's name, root path, mode, serving build, and whether it is stale. | |
list_metrics | READ | semantic_project, tag (optional) | CSV of the metrics: name, type, label, description and tags. tag keeps the metrics that set that tag schema. |
list_saved_queries | READ | semantic_project | CSV of the saved queries: name, label, description, metrics and group-bys. |
list_exports | READ | semantic_project | CSV of the exports: name, saved query, feature group, version, schedule (empty for an export run on demand only), lookback, enabled, last status, last run, last rows and last message. |
list_query_history | READ | semantic_project, then limit, 20 by default, status and user (optional) | CSV of the query history, newest first: started at, user, surface, status, duration, rows, cache outcome, error, request and execution id. A Data Owner's server reads every member's records, and user picks one member's. |
get_dimensions | READ | semantic_project, metrics | CSV of the dimensions the metrics can be grouped by: name, type, grains and entity path. |
get_entities | READ | semantic_project, metrics (optional) | CSV of the entities. |
get_dimension_values | READ | semantic_project, dimension, metrics and limit (optional) | CSV of the distinct values of a dimension. |
query_metrics | READ | semantic_project, metrics, then group_by, where, order_by and limit (optional) | CSV of the rows, 100 rows unless limit says otherwise. |
query_saved_query | READ | semantic_project, name, then group_by, where and limit (optional) | CSV of the rows of a saved query; group_by and limit replace its own, where adds to its filters. 100 rows unless limit says otherwise. |
get_metrics_compiled_sql | READ | The arguments of query_metrics | The SQL the query compiles to. |
get_semantic_project_tags | READ | semantic_project | The semantic project's tags, name and value. |
validate_semantic_project | READ | semantic_project | The status the definitions would compile to, VALID or INVALID, and their issues; no build is made. |
compile_semantic_project | WRITE | semantic_project | The build id, its status and its issues. |
create_dashboard_from_metrics | WRITE | semantic_project, metrics, then group_by and title (optional) | The id, title and URL of a Superset dashboard of the metrics, see Dashboards in Superset. |
Group-bys and filters take the forms of Query metrics: customer__country, metric_time__month and {{ Dimension('order__status') }} = 'completed'. The CSV of query_metrics and query_saved_query is capped in length, so a large result needs a limit or a filter. A metric that needs metric_time, such as a cumulative metric with a window, needs it in group_by, see Metric types.
validate_semantic_project checks the definitions as they are in HopsFS, as a compile would, and stores nothing: the build that answers queries stays the one it was. compile_semantic_project makes them a build: files that have not changed return their existing build. In FOLLOW mode the resulting VALID build answers queries at once, which undoes a promote of an older build; in PINNED mode only promoted builds are served, see Serving modes.
Coding agents#
A coding agent that runs the hops CLI uses the hops-semantic skill: authoring semantic YAML over feature groups, with every metric type, the time spine and saved queries, compiling, testing metrics, and querying them with hops semantic. The hops-semantic-views skill scopes a semantic project to one business domain and keeps it small enough for an agent to read whole. hops skills list lists both, and the project terminal has Claude Code and Codex preinstalled with hops connected.
Size a semantic project for agents#
Keep each semantic project under 100k tokens, so that it does not swamp an agent's context window. Count the semantic YAML under its root path and the four lists an agent reads before it queries: metrics, dimensions, entities and saved queries. YAML and CSV of snake_case names run at about 3 characters per token, so 100k tokens is about 300,000 characters. The tools above cut each list at 50,000 characters and say so on a last line, so a list longer than that hides the metrics or dimensions past the cut.
hops semantic show sales # the root path; a terminal mounts /Projects/<project>/<dir> at /hopsfs/<dir>
grep -rlE --include='*.yml' '^(semantic_models|metrics|saved_queries):' /hopsfs/Resources/semantic/sales | xargs -r cat | wc -c
for list in metrics dimensions entities saved-queries; do hops semantic $list sales --json | wc -c; done
To stay under it, give each business domain its own semantic project with only the feature groups its questions need, leave out dimensions nobody groups or filters by, and add saved queries for the most-asked questions. Two semantic projects can model the same feature group, so splitting a large project by domain loses no data. The Hopsworks CLI guide covers installing the skills into a repository with hops init.