Skip to main content
Glama
Verdonz MCP

Verdonz MCP

Official
by verdonz

Verdonz MCP

Connect AI assistants to governed business data with Verdonz.

Verdonz MCP is an open-source Model Context Protocol server that lets compatible AI clients work with governed metrics, datasets, investigations, and supporting evidence through Verdonz. It runs over stdio and keeps stdout reserved for MCP protocol traffic.

What is Verdonz MCP?

It is a small Node.js server that translates MCP tool calls into governed Verdonz API requests. The underlying Verdonz identity remains the authority for access, permissions, and data visibility.

Related MCP server: semantic-model-kit

Why use it?

  • Give AI assistants a governed path to business data.

  • Keep metric definitions and source context close to answers.

  • Use the same tool surface locally with fictional demo data.

Features

Six tools cover metric discovery, dataset discovery, questions, investigations, and evidence. Production capabilities depend on the connected Verdonz API contract and permissions.

Installation

npm install -g @verdonz/mcp
npx @verdonz/mcp

Quick start

export VERDONZ_API_KEY="your-key"
export VERDONZ_BASE_URL="https://your-verdonz-api.example"
npx @verdonz/mcp

VERDONZ_BASE_URL is required in production mode; this package does not invent a default host.

MCP client configuration

{
  "mcpServers": {
    "verdonz": {
      "command": "npx",
      "args": ["-y", "@verdonz/mcp"],
      "env": {
        "VERDONZ_API_KEY": "YOUR_API_KEY",
        "VERDONZ_BASE_URL": "YOUR_VERDONZ_API_URL"
      }
    }
  }
}

Available tools

  • verdonz_list_metrics — search accessible governed metrics.

  • verdonz_get_metric — retrieve a metric definition and metadata.

  • verdonz_list_datasets — list accessible data sources.

  • verdonz_ask — ask a governed business question.

  • verdonz_investigate — investigate metric movement when supported by the provider.

  • verdonz_get_evidence — retrieve source/lineage evidence when supported.

Example questions

“What changed in revenue last month?” “Which region contributed most to the decline?” “Show me the definition of net revenue.” “What datasets can I access?” “Investigate the drop in conversion rate.” “What evidence supports that conclusion?” Actual capabilities depend on the connected Verdonz environment.

Mock/demo mode

Run VERDONZ_MOCK=true npx @verdonz/mcp to use fictional revenue, conversion rate, active customer, region, and product data without a network connection. No real customer data is included.

Authentication

Set VERDONZ_API_KEY and VERDONZ_BASE_URL as environment variables. The production adapter sends the key as X-Verdonz-API-Key and never logs it.

Architecture

The MCP transport and tool schemas are isolated from a typed VerdonzClient interface. MockClient supplies the local demo; VerdonzApiClient maps confirmed semantic HTTP routes; future API changes stay behind that adapter.

Security

Read SECURITY.md. Use least-privilege keys, keep credentials out of source control, and remember that the MCP server can expose whatever the configured Verdonz identity can access.

Development

npm ci
npm run lint
npm run typecheck
npm test
npm run build
npm pack --dry-run

See docs/VERDONZ_API_INTEGRATION.md for adapter details.

Contributing

See CONTRIBUTING.md.

Roadmap

Validate the production API gateway contract, add a first-class investigation adapter, expand evidence normalization, and add integration tests against a safe Verdonz environment.

License

MIT. See LICENSE.

About Verdonz

Verdonz builds governed AI agents for your business. It connects business data and context so teams and AI can ask questions, understand what changed, and investigate the evidence behind an answer.

Available Tools

6 tools
verdonz_askC

Ask a business question through Verdonz governed semantic data.

Inputs: question (required), context, datasetId, timeRange.

verdonz_get_evidenceC

Retrieve source/lineage evidence for a Verdonz result when supported.

Inputs: metric, resultId, datasetId.

verdonz_get_metricC

Get the definition and metadata for a governed metric.

Inputs: name, metricId, datasetId.

verdonz_investigateC

Investigate why a governed metric changed. Production availability depends on the connected Verdonz API.

Inputs: metric (required), datasetId, timeRange, dimensions, +1 more.

verdonz_list_datasetsC

List governed datasets/data sources available to the identity.

Inputs: limit, search.

verdonz_list_metricsC

List governed metric definitions the identity can access.

Inputs: limit, search, datasetId.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 6 tools

    Disambiguation4/5

    list_metrics/get_metric and list_datasets are clearly distinct, and get_evidence is a well-separated retrieval role. verdonz_ask and verdonz_investigate are the closest pair, but the descriptions (business question vs. root-cause investigation) give enough signal to separate them.

    Naming Consistency4/5

    All tools share the verdonz_ prefix and use a consistent verb-first style (list_, get_, ask, investigate). Minor deviation: ask and investigate omit the noun object that the other four include, but the pattern remains readable and predictable.

    Tool Count5/5

    Six tools is well-scoped for a governed semantic-data Q&A surface, with each tool earning its place (two listers, two getters, one ask, one investigate). Nothing feels padded or missing at this granularity.

    Completeness4/5

    Covers the core read lifecycle: discover datasets and metrics, ask questions, investigate metric changes, and pull evidence/lineage. Minor gaps around deeper lineage traversal or metric comparison exist, but agents can work around them via ask/investigate.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables agents to query governed metrics through MCP, including describing metrics, running deterministic SQL against a warehouse, explaining join path preferences, and searching semantically ambiguous terms.
      8
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to query databases correctly by serving governed context over MCP, including canonical metric definitions, relationships, business meaning, and guardrails, so answers come back with resolved definitions, fired filters, freshness, and a trust score instead of guesses.
      3
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents and their users to ask business questions in plain language and receive governed metric values, breakdowns, share-of-total figures, and the exact parameterized SQL behind them, drawn from a single semantic model rather than ad-hoc SQL. It also lets clients inspect available metrics and their definitions, and preview optimized queries without executing them.
      4
      MIT