Enable the dbt Semantic Layer in your dbt Cloud environment and obtain the Environment ID and a service token (or personal access token) from Account Settings in dbt Cloud
Connect to the GraphQL API endpoint at https://semantic-layer.cloud.getdbt.com/api/graphql using the header Authorization: Bearer YOUR_SERVICE_TOKEN and the query parameter environmentId=YOUR_ENV_ID
Introspect available metrics by sending the query { metrics(environmentId: YOUR_ENV_ID) { name description type } } to discover what metrics are defined in your semantic layer
Query metric values with dimensions using the createQuery mutation to create a query, then poll queryResults with the returned queryId; the createQuery payload accepts metrics, groupBy, where, and orderBy fields
Parse the paginated results from queryResults; as of 2025, paginated GraphQL endpoints for metadata queries are available to handle large manifests and avoid timeouts on environments with many models
Known gotchas
The Semantic Layer GraphQL API is a dbt Cloud Team or Enterprise feature; it is not available in dbt Core or the free Developer plan
Metric queries are asynchronous — createQuery returns a queryId and you must poll queryResults until status reaches SUCCESSFUL or FAILED; treating the mutation response as final results will yield empty data
Dimension names in groupBy must exactly match the grain defined in your MetricFlow YAML files; mismatched casing or aliases not declared in the semantic model will return a validation error
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp