You're on the dbt Semantic Layer: Keep Every Copy of Every Metric True, for People and AI Agents

Your analytics engineers define metrics in code. Semantic models sit in the same YAML as the dbt models they read; metrics like net_revenue are built on top, reviewed in pull requests and tested in CI. MetricFlow compiles each request into SQL with the right joins and grain, the Semantic Layer serves it to Tableau, Power BI, Excel and Hex, and through the dbt MCP server your agents call query_metrics too. The dbt Semantic Layer is where your metrics are defined. Data Workers is what keeps every copy of them true: it imports your semantic manifest as context, checks each definition against the warehouse, flags the dashboard whose logic has drifted from dbt's, and proposes the fix through your approvals with a receipt.

The definition in dbt is rarely the only one. Finance still has a Tableau workbook with a Net Revenue calculated field written before the Semantic Layer existed. A Power BI model carries its own DAX measure. An agent finds a column called revenue in the warehouse and sums it. Each copy gives a slightly different number. That gap is the job this guide is about.

Key takeaways

• •The Semantic Layer keeps its job. MetricFlow, your semantic models, review, CI and integrations stay as they are. Data Workers works next to them from day one.
• •Your metrics become governed context. Context Wizard imports the semantic manifest your production job writes, each definition with its source, commit and owner.
• •Definitions are checked against the data. Data Workers checks the columns each metric filters and sums, and traces upstream changes to every metric they touch.
• •Drifted copies are found and routed. When a BI calculated field disagrees with the dbt metric, a named owner sees both expressions and every reader, and decides.
• •Fixes go through approvals. Documentation changes go back to your dbt repo as pull requests once your team turns on the GitHub pull-request target; changes in BI tools go to their owners. Every change has a receipt.

The dbt Semantic Layer is where metrics are defined. Data Workers keeps every copy true.

The dbt Semantic Layer does a hard job very well. In dbt's words, it "eliminates duplicate coding by allowing data teams to define metrics on top of existing models and automatically handling data joins." MetricFlow, its engine, is open source under Apache 2.0. It runs on dbt platform Starter, Enterprise and Enterprise+ plans, with native integrations for Power BI, Tableau, Excel, Google Sheets, Hex, Omni, Sigma (in preview) and more, plus GraphQL, JDBC, ADBC and the Python SDK. At dbt Summit in September 2026, Fivetran + dbt Labs listed the Semantic Layer and the dbt MCP server as generally available, alongside dbt v2. The MCP server gives any agent list_metrics, get_dimensions, get_metrics_compiled_sql and query_metrics, self-hosted or from the remote server the dbt platform hosts.

What sits around it decides whether its numbers reach people intact: the BI copies built before it, the warehouse columns each measure reads, the ingestion that fills them, and agents that query the warehouse directly. Data Workers covers that side, with one context, one approval flow and one audit trail.

Here is a morning with Data Workers next to the dbt Semantic Layer. This is an illustration, not a customer case.

The Semantic Layer did exactly what it should: the new definition was reviewed, tested and served. The drift was in a copy dbt doesn't run, and it went through the owner's approval before anything changed.

Why doesn't the dbt Semantic Layer just do this itself?

Because dbt built the Semantic Layer for one job: define a metric once, next to the models it reads, and serve it the same way to every tool that asks. That focus is what makes it trustworthy. dbt keeps extending that model into the repo: dbt Charts (public beta) builds dashboards as YAML next to the models they use.

A Tableau calculated field written against the raw table never asks the Semantic Layer anything, so the Semantic Layer has no way to see it, let alone change it. dbt describes its MCP server as "a read-only access layer that reads metadata, job results, and Semantic Layer data from the dbt platform in real time when a tool is called." When the self-hosted server runs dbt commands, dbt's README is direct: they "could modify your data models, sources, and warehouse objects. Proceed only if you trust the client." Those are sensible boundaries for a product so many agents depend on.

Reconciling a metric across other vendors' BI tools, checking the warehouse underneath, asking a finance owner to decide, and proposing changes in tools dbt doesn't own is a different product with a different liability. It needs blast-radius scoping, approvals that cover a dbt pull request and a Tableau workbook in one incident, rollback for each step and receipts an auditor can read. That is the product Data Workers is.

Every tool owns a slice. Data Workers covers the whole lifecycle

The dbt Semantic Layer owns one slice of the lifecycle outright: defining metrics as code. Each point tool adds another console, contract and handoff. Data Workers covers the whole lifecycle with one context, one approval flow and one audit trail, and builds on the Semantic Layer you already run.

How the dbt Semantic Layer and Data Workers work together

People stay where they are: Claude Code or Cursor for dbt work, Tableau, Hex and Excel for analysis, and any agent on the dbt MCP server. Spellbook Data Catalog (in preview) is where the data team looks: each conflict, proposed change, blast radius, approver and rollback. Underneath, Data Context Wizard keeps one governed context graph, the Data-Agents Swarm's 20+ specialist agents do the work, and the Autonomous Data-Conductor runs each fix end to end (detect, diagnose, fix, review, verify, remember) inside per-domain guardrails.

What Context Wizard does with your metrics. It imports the semantic_manifest.json your production job writes (semantic models, entities, dimensions, measures and metrics) or reads definitions live from the Semantic Layer GraphQL API. Each definition is recorded with its source, time and owner; list_semantic_definitions shows them by domain and source, and trace_cross_platform_lineage follows net_revenue back through fct_orders and the ingestion sync to the billing system. When an agent asks for "revenue" and three definitions match, resolve_metric returns every candidate instead of guessing, and get_authoritative_source names the one the owner approved. Marking a definition authoritative takes a named person.

What Data Workers checks against the warehouse. run_quality_check covers the columns each metric filters and sums; the dbt manifest diff catches an upstream rename before the next build; assess_impact on the schema agent lists every model and metric a change will touch. Moving metric logic between warehouses, the same checks run on each, which keeps dbt metrics consistent across warehouses.

Setup over MCP today. Data Workers runs next to the dbt MCP server in the same client: clone the open-source repository and add start-agent.sh entries, as the client setup docs show. For dbt, use the remote server with a token and your production environment ID, and switch off the SQL toolset if you only want metric and metadata reads.

// Example: .mcp.json for Claude Code (Cursor uses the same mcpServers shape)
{
  "mcpServers": {
    "dbt": {
      "type": "http",
      "url": "https://<your-dbt-host>/api/ai/v1/mcp/",
      "headers": {
        "Authorization": "Token <from your secret store>",
        "x-dbt-prod-environment-id": "<your prod environment id>",
        "x-dbt-disable-toolsets": "sql"
      }
    },
    "dw-context-catalog": {
      "command": "/path/to/dataworkers-claw-community/start-agent.sh",
      "args": ["dw-context-catalog"]
    },
    "dw-schema": {
      "command": "/path/to/dataworkers-claw-community/start-agent.sh",
      "args": ["dw-schema"]
    },
    "dw-quality": {
      "command": "/path/to/dataworkers-claw-community/start-agent.sh",
      "args": ["dw-quality"]
    }
  }
}

dbt recommends a personal access token for the Semantic Layer tools; a service token needs at least Semantic Layer Only, Metadata Only and Developer permissions. OAuth on the remote server is in public beta for Starter, Enterprise and Enterprise+. List the tools with your client's own command (/mcp in Claude Code). Now an engineer can ask "is net_revenue defined the same way everywhere, and is the data under it healthy?" and get dbt's definition, every other copy, the lineage and the latest quality results in one answer.

Where writes go. Documentation goes back to your dbt repository as a pull request when your team turns on the GitHub pull-request target, and your CI and reviewers handle it like any other. Definition changes stay with the metric's owner. BI changes go to the people who own those tools, with the approved definition attached. Data Workers then verifies every copy returns the same number.

One request, L0 to L4. The autonomy ladder is set per domain.

• •L0 manual. Data Workers is connected, not acting. An engineer compares a dashboard with query_metrics by hand.
• •L1 observe. Data Workers imports the manifest after every build, checks the columns under each metric and explains every BI copy that disagrees. Nothing changes.
• •L2 propose. Data Workers drafts the documentation change and sends the BI change to its owner, with the blast radius. The metric owner approves in Spellbook first.
• •L3 act reversibly. For change classes with a proven record, such as updating descriptions after an approved definition change, Data Workers applies the change, verifies it and can roll it back.
• •L4 autonomous. For a trusted class like one domain's documentation sync, Data Workers acts on its own and posts the receipt.

For the safety model behind each step, read is it safe to let AI agents change production data; for where data and credentials live, read where does our data go.

For wiring the whole dbt project, read Data Workers + dbt; for more than one semantic layer, Data Workers with Cube, AtScale, MetricFlow and Ossie. The hub, bring your own context, and the guides for Snowflake semantic views and Ossie semantics show the same pattern. dbt now parses Ossie documents in an osi/ directory into the manifest, so they arrive through the same import. Background: the dbt Semantic Layer as an agent layer.

What changes for your team

Analytics engineers lose hours each week explaining why the dashboard and the notebook disagree and answering "which definition did the agent use?" With Data Workers next to the Semantic Layer, those jobs run on autopilot at the level you set.

• •Incidents. A BI copy that drifts from a changed dbt metric is flagged, traced and settled before it reaches a board deck.
• •Data quality. Every column a metric filters or sums is checked for nulls and new values, with load lag against a recorded baseline.
• •Cloud spend. Cleanups of extracts and marts built for retired dashboard copies are proposed to the owner after a dependency check.
• •Access. A request for a finance metric arrives as a time-boxed grant proposal for its owner, with the policy behind it.
• •Audits. Every definition change carries a named approver, a diff, the checks run and a rollback path.
• •Migrations. BI copies move onto the Semantic Layer in approved waves, verified number by number, with no big-bang cutover.

Keep the dbt Semantic Layer, or consolidate?

Keep the dbt Semantic Layer if you love it; Data Workers works with it from day one. Many teams consolidate once Data Workers runs that slice too.

For most teams, the answer is to keep it: metrics as code is the right home for definitions. What teams consolidate is the tooling around it: a spreadsheet mapping dashboards to metrics, a pre-board-meeting comparison script, a separate quality tool for the marts, and a Slack thread for every definition argument. Data Workers runs those jobs with one context, one approval flow and one audit trail. Weighing a build on the dbt MCP server? Read build it ourselves with Claude Code and MCP servers: reading metrics over MCP is the easy part; cross-tool comparison, named-owner approvals and rollback are where the work is.

The case for your CFO

The outcome: one number for every metric the business runs on. The board deck, the finance workbook, the analyst's notebook and the AI agent all give the same net_revenue, and each definition has a named owner who signed off.

The risk story is plain. Data Workers reads the Semantic Layer through dbt's own read surfaces; it doesn't edit definitions. Every change it proposes shows its blast radius, goes to a named approver, lands through your normal review flow and tools, is verified and leaves a receipt: who approved it, what it touched, the checks run and how to undo it. Autonomy is set per domain from L0 manual to L4 autonomous and can be dialled back at any time. There is zero migration: dbt, your warehouse and your BI tools stay where they are.

Why now: agents read metrics directly, and every agent that skips the Semantic Layer can compute its own net_revenue. More readers mean more ways for one number to become three. The first win is one domain, finance, imported read-only, with every BI copy of its top metrics compared against dbt. What stays the same: your semantic models, your review process, your BI tools and your warehouse permissions. For the numbers, see the ROI of agentic data operations.

The sentence to repeat upstairs: "dbt defines our metrics once; Data Workers makes sure every dashboard and every agent uses that one definition, and a named owner approves any change."

Getting started

Start with a pilot. Pick the domain whose numbers reach the board, usually finance, import its semantic manifest read-only, and let Data Workers compare every BI copy of those metrics for a few weeks before turning on the first proposals. The pilot path and plans are on the pricing page, and the pilot is credited in full against the first year.

FAQ

Does Data Workers change our MetricFlow definitions? No. Definitions stay with their owners and your dbt review. Data Workers imports them, flags conflicts and proposes documentation changes; a named person decides.

How does Data Workers get our semantic models? From the semantic_manifest.json your production job writes, or live from the Semantic Layer GraphQL API, after every build, so the context matches what is deployed.

How does Data Workers find BI copies that don't use the Semantic Layer? BI tools connect over their own APIs or MCP servers today; your team's assistant exports each calculated field or measure that computes a governed metric, and Data Workers compares it with dbt's definition. Disagreements go to the owner.

Can AI agents query the dbt Semantic Layer and Data Workers at the same time? Yes. Both are MCP servers in the same client: numbers from query_metrics on the dbt side, owner, lineage and data health from Data Workers, in one session.

What happens when two definitions of a metric disagree? Agents see every candidate with its source until the owner approves one as authoritative in Spellbook. The decision is recorded, and the other copies get proposals to match.

Does this work with dbt v2, dbt OSS and dbt v1? Yes. Data Workers reads the semantic manifest and dbt's APIs rather than the engine, so it follows the project whichever version builds it.

Sources

• •dbt Labs, dbt Semantic Layer overview (updated Sep 29, 2026), https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl (checked Oct 2, 2026)
• •dbt Labs, Semantic Layer APIs: GraphQL, JDBC, Python SDK (updated Jul 23, 2026), https://docs.getdbt.com/docs/dbt-apis/sl-api-overview (checked Oct 2, 2026)
• •dbt Labs, Available Semantic Layer integrations (updated Sep 29, 2026), https://docs.getdbt.com/docs/cloud-integrations/avail-sl-integrations (checked Oct 2, 2026)
• •dbt Labs, About the dbt MCP server, self-hosted and remote (updated Jul 23, 2026), https://docs.getdbt.com/docs/dbt-ai/about-mcp (checked Oct 2, 2026)
• •dbt Labs, Set up the remote dbt MCP server (updated Sep 8, 2026), https://docs.getdbt.com/docs/dbt-ai/setup-remote-mcp (checked Oct 2, 2026)
• •dbt Labs, dbt MCP server repository and README (v2.5.0, Sep 28, 2026), https://github.com/dbt-labs/dbt-mcp (checked Oct 2, 2026)
• •dbt Labs, MetricFlow repository (Apache 2.0 from v0.209.0), https://github.com/dbt-labs/metricflow (checked Oct 2, 2026)
• •dbt Labs, Release notes: dbt Summit 2026 product naming updates, dbt v2 GA, Apache Ossie support (Jul to Sep 2026), https://docs.getdbt.com/docs/dbt-versions/release-notes (checked Oct 2, 2026)
• •Fivetran + dbt Labs, dbt Summit 2026 product announcements (Sep 2026), https://www.getdbt.com/blog/dbt-summit-2026-product-announcements (checked Oct 2, 2026)
• •Data Workers, Client setup (open-source docs), https://dataworkers.io/opensource-docs/client-setup/ (checked Oct 2, 2026)
• •Data Workers agent swarm repository: Data Context Wizard MetricFlow importer, dbt Semantic Layer client, semantic definition and authority tools (checked Oct 2, 2026)