Verdonz MCP Server

MCP server that gives AI agents business context

Connect agents to business meaning, not just to a database.

An agent with a database connection can read your tables. It still does not know which column is revenue, which rows this person may see, or why last quarter was restated. Verdonz answers over the Model Context Protocol with the definitions attached.

Updated September 2026

Verdonz runs a Model Context Protocol server so any MCP client — an agent, an assistant, an application — can list the tools it offers and call them. Those tools reach the semantic layer, dashboards, datasource metadata, and the record of what your AI has already run, under an authenticated caller whose permissions are checked before a tool that changes anything is allowed to run.

The Verdonz MCP server in short

• The Verdonz MCP server is one authenticated JSON-RPC endpoint offering thirteen tools in four groups: semantic layer, dashboards, datasources, and your own logged AI requests.
• Its tools answer through the Verdonz semantic layer, so a metric arrives with its governed definition applied and the permissions of the person asking already enforced, including row-level security for MCP clients.
• It is not a gateway to third-party MCP servers, it implements tools rather than MCP resources or prompts, and its transport is HTTP POST with no streaming.

MCP connection

Endpoint

https://app.verdonz.com/api/mcp on Verdonz cloud. A dedicated instance serves the same path, /api/mcp, on its own host.

Metadata

https://www.verdonz.com/.well-known/mcp.json, a machine-readable description of this server in the MCP Registry server.json format.

Authentication

A Verdonz API key, sent as Authorization: Bearer <api-key> or in a X-Verdonz-API-Key header.

Transport

Streamable HTTP with JSON responses: one JSON-RPC 2.0 request per POST, no SSE stream. The server answers protocol version 2024-11-05.

Methods

initialize, ping, tools/list and tools/call. The server offers tools only, not resources or prompts.

Tool discovery

Call tools/list. Each tool comes back with its name, a description, and a JSON Schema for its arguments.

Connect agents to the systems where the work happens

The Model Context Protocol is a standard way for an AI application to discover what a service can do and then call it. Verdonz uses it to hand agents the parts of the platform that answer business questions.

One endpoint, speaking JSON-RPC over HTTP. A client calls tools/list to see what is available and tools/call to run one. What comes back is data, in the shape the tool declares — there is no Verdonz UI to embed and no SDK to adopt.

AgentsAssistantsApplications

Verdonz MCP server · authenticated

Semantic layerDashboardsDatasource metadataYour AI records

Semantic layer tools

The semantic layer tools let an agent list a source’s metrics and dimensions with their labels, descriptions, synonyms and expected ranges, run a query against a named metric, and trace what that metric is built from. They matter because they are what turns a table into a definition. See the semantic layer.

Dashboard tools

The dashboard tools search dashboards by title or tag, fetch one by id, and list the panels on it with the queries each panel runs. They matter because a question about a number usually starts with a number somebody saw rather than a metric name. Asked why the figure on the revenue board moved, an agent can find that dashboard and read what its panels actually query.

Datasource metadata tools

The datasource metadata tools list the datasources an organization has configured and describe one by id: name, type, database and execution mode. They matter because an agent needs to know which systems exist before it can reason about where an answer lives. Credentials are never returned by either tool. See data integration for how those connections are registered.

Tools over your own AI request records

These tools read your own logged model requests: one lists recent requests with model, latency, tokens, cost and whether each succeeded, was cached or was blocked by a guardrail; the other rolls that up over a time range. They matter because AI spend and reliability are questions the assistant can answer about itself rather than sending someone to a separate report. Asked what last week cost and where the errors were, an agent has the records to answer.

Thirteen tools across those four groups today. Each one declares its own argument schema, and each description states what the tool will not do as well as what it will, because that description is what the model reads before deciding to call it.

Give agents business context, not just access

Most MCP servers hand an agent a connection. The hard part was never the connection — it is that a schema does not say what anything means.

Point an agent at a warehouse and it has to decide for itself which of four amount columns is revenue, whether to exclude refunds, what a customer is when three tables could stand in for one, and which rows this person is entitled to see. It will decide. It will not tell you it guessed, and the answer will look exactly as confident as a right one.

A connection alone

table

transactions

columns

amount, status, created_at

revenue?

the agent decides

which rows?

whatever the credential can read

Through the semantic layer

metric

revenue — defined once

entity

customer — joins declared

grain

month, quarter, year

permissions

resolved from the model

The same question, asked two ways. Illustrative example, not customer data.

The semantic tools answer in the second column. A metric carries its own filter and aggregation, an entity carries the joins that reach it, and the catalog carries the labels and synonyms a person would actually say. That is the same model your dashboards resolve against, so an agent and a report do not disagree. See business context and business metrics.

Expose the right tools to AI

An MCP tool is a named operation with a declared input schema that a client can discover and call. It is the unit an agent actually reaches for.

Verdonz registers its tools at startup from the features that own them, and a duplicate name is a startup failure rather than one quietly shadowing the other. Two features cannot both claim a name and change what an agent executes with no signal anywhere.

Tool	Group	Permission	What it does
list_datasources	Semantic layer	read only	List the configured semantic-layer datasource ids.
list_metrics	Semantic layer	read only	List a datasource’s full metric definitions.
get_metadata	Semantic layer	read only	Describe a datasource’s metrics and dimensions: labels, descriptions, synonyms, types and guardrails.
lineage	Semantic layer	read only	Trace what a semantic object is built from, and what depends on it.
rollup_ddl	Semantic layer	read only	Return the DDL to materialize declared rollups as warehouse-native pre-aggregates.
query	Semantic layer	needs create	Run a semantic query: one metric, optional dimensions, filters, time range and limit.
dashboard.search	Dashboards	read only	Find dashboards by exact title and/or tag.
dashboard.get	Dashboards	read only	Fetch one dashboard’s metadata by id.
dashboard.describe_panels	Dashboards	read only	List a dashboard’s panels and the queries each one runs.
datasource.list	Datasources	read only	List configured datasources: id, name, type and which is default.
datasource.get	Datasources	read only	Describe one datasource by id. Never returns credentials.
llm.list_requests	LLM records	read only	List recent model requests with latency, tokens, cost and outcome.
llm.cost_rollup	LLM records	read only	Summarize spend and reliability over a time range.

The tools advertised by tools/list, with the ones that only read marked. Illustrative example, not customer data.

The read-only marking is not decoration. It is the flag the server checks before it runs anything, and it decides which tools need more than a read credential.

What a call looks like on the wire

Two requests: one to discover what the server offers, one to run a tool. Both are JSON-RPC 2.0 over HTTP POST to the same endpoint, with the API key in an Authorization header.

POST /api/mcp   Authorization: Bearer <api-key>

{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }

{ "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": {
    "name": "list_metrics",
    "arguments": { "datasource": "sales" }
  } }

{ "jsonrpc": "2.0", "id": 2,
  "result": {
    "content": [ { "type": "text", "text":
      "net_revenue - Net revenue, invoiced, excluding tax\nnew_customers - First-time paying accounts" } ]
  } }

Illustrative example, not customer data. Field values are invented; the method names and tool name are real.

Who may call the Verdonz MCP server

The endpoint is not open. A caller arrives with a platform API key or an authenticated session, and one carrying no permissions at all is refused rather than waved through.

Reading needs a read credential. Any tool that changes state or executes a query against a warehouse is re-checked for a create permission at the moment it runs, independently of what the route declared — which is why the read-only marking above is a property the server acts on rather than a label.

That is the shape of it. The control layer in full — how a caller is authenticated, what the authorization check does before a write runs, the limits on request volume, and the metrics the endpoint records — is MCP gateway. What this page covers is the server underneath it: the tools, how a client connects, and what a call returns.

How Verdonz logs what agents did over MCP

A model request that originated through MCP is attributed to it in the request log, alongside the team, the end user, the tokens and the cost — so agent traffic is answerable from the same records as everything else. The endpoint’s own request metrics are covered on MCP gateway, and reading and investigating the records is AI observability.

MCP server, MCP gateway, and AI gateway

Three layers that get used interchangeably and should not be. They solve different problems and can sit alongside one another.

	MCP server	MCP gateway	AI gateway
Connects AI to	Tools and data	Several MCP servers	Models and providers
Primary job	Offer capabilities a client can discover and call	Sit in front of other servers and control reach	Route and control model traffic
The question it answers	What can this agent use?	Which servers may it reach?	Which model handles this request?

The Verdonz MCP server is the first column: a server offering its own tools, with a control layer in front of them described on MCP gateway. What it does not do is the middle column in its wider sense — it does not dial out to other people’s MCP servers, so it will not consolidate a fleet of them. For model traffic, routing, retries and budgets, that is the AI gateway, a different layer again.

What an enterprise MCP server needs beyond the protocol

Running an MCP server is a weekend. Running one that a security review will accept is the rest of the quarter, and most of that work is not protocol work: it is deciding who may call what, making the answers mean the same thing they mean everywhere else, and being able to say afterwards what happened.

Verdonz starts from the other end. The permissions already exist, the metric definitions already exist, and the request log already exists, so exposing them over MCP adds a protocol rather than a second set of rules to keep in sync. Agents built on analytics agents reach the same tools through the same checks.

How the Verdonz MCP server works

Four steps, of which only the third is MCP.

1. Connect the data

   Point Verdonz at the systems you already run: the warehouses Snowflake, Google BigQuery, Databricks on Unity Catalog and Amazon Redshift; the databases PostgreSQL, MySQL and Microsoft SQL Server; and the query engines Presto and Amazon Athena. Queries compile to each dialect and execute there.

2. Define what the numbers mean

   Metrics, entities, relationships and dimensions are declared once in the semantic layer, with the labels and synonyms people actually use.

3. Point an MCP client at the endpoint

   The client authenticates with a platform API key, calls tools/list to discover what is available, and calls tools/call to run one. Any client that speaks MCP over HTTP POST can connect — including Claude Desktop, Claude Code and Cursor, and agents you build yourself against the MCP SDK. The API reference covers credentials and endpoints.

4. Read what happened

   Route metrics cover the calls themselves, and model requests that came through MCP are attributed to it in the request log.

Model Context Protocol, defined

MCP server

An MCP server is a service that uses the Model Context Protocol to make capabilities available to AI applications: it advertises what it can do and executes the calls a client makes. The client is the AI side — an agent, an assistant, an IDE — and the server is whatever holds the capability.

Model Context Protocol

The Model Context Protocol is an open standard for connecting AI applications to external systems, so a client and a server that have never met can agree on how to discover and invoke capabilities. It removes the need for a bespoke integration per pair. Verdonz implements it over JSON-RPC on a single HTTP endpoint.

MCP tools

An MCP tool is a named operation with a declared input schema. A client discovers the available tools, decides which one fits, and calls it with arguments matching that schema. The protocol also defines resources and prompts; Verdonz implements tools.

MCP gateway

An MCP gateway sits between AI clients and several MCP servers, giving one place to control which of them a client can reach. It is a different job from being a server: a server offers capabilities, a gateway governs access to servers that offer them. Verdonz provides a server.

Frequently asked questions

Common questions about MCP servers, and about what Verdonz implements today.

What is Verdonz?

Verdonz is governed AI analytics and business intelligence for business data, dashboards, trusted metrics, and answers whose work can be checked. The MCP server is one capability of AI & Agents in Verdonz; this page covers that capability.

What is an MCP server?

An MCP server is a service that uses the Model Context Protocol to make capabilities available to AI applications. It advertises what it offers so a client can discover it, and executes the calls that client makes. The AI application is the client; the server is whatever holds the tool or the data. In Verdonz, the server holds tools over the semantic layer, dashboards, datasources and AI request records.

What is Model Context Protocol?

The Model Context Protocol is an open standard for connecting AI applications to external systems. It gives a client and a server a shared way to describe and invoke capabilities, so each new pairing does not need a bespoke integration. Verdonz implements it as JSON-RPC over a single HTTP endpoint.

What does an MCP server do in practice?

It answers two kinds of request: tell me what you can do, and do this. In Verdonz the first returns the tools available to that caller with their argument schemas, and the second runs one and returns its result. The Verdonz server implements initialize, ping, tools/list and tools/call, and the MCP gateway page covers how each call is authorized.

What are MCP tools?

An MCP tool is a named operation with a declared input schema that a client can discover and call. Verdonz offers thirteen, in four groups: semantic layer tools for listing metrics, describing a model, running a query and tracing lineage; dashboard tools; datasource metadata tools; and tools over your own logged AI requests and their cost.

What is MCP authentication, and how does it work in Verdonz?

MCP authentication is how a server establishes who is calling before it runs anything. The Verdonz endpoint requires a platform API key or an authenticated session; there is no anonymous access. Identity then drives authorization: reading needs a read credential, and any tool that changes state or executes a query is separately re-checked for create permission when it runs.

How do you secure an MCP server?

Start by requiring authentication, then decide per tool rather than per server: reading a metric definition and executing a query are not the same risk. Fail closed, so a request with no permissions is refused rather than allowed. State each tool’s limits in its description, since that text is what the model reads. Verdonz does these four things; none of them makes an agent safe to point at anything, and what a model is allowed to say and do is a separate control.

What is the difference between an MCP server and an MCP gateway?

A server offers capabilities to AI clients. A gateway is the control layer in front of them, deciding who may reach what. Verdonz provides a server, and applies a control layer over its own tools: every caller is authenticated and writes are authorized before they run. What it does not do is dial out to third-party MCP servers, so it will not put one endpoint in front of a fleet of them.

What is the difference between an MCP gateway and an AI gateway?

They govern different traffic. An MCP gateway sits between AI clients and MCP servers, controlling which tools and services an agent can reach. An AI gateway sits between applications and model providers, controlling which model serves a request and what it may spend. Verdonz provides the second as its AI Gateway; the two solve unrelated problems and neither replaces the other.

What is an MCP registry?

An MCP registry is an inventory of MCP servers an organization knows about, used to discover and manage them. Verdonz does not provide one. It keeps an internal registry of its own tools — which is what tools/list reports, and where a duplicate tool name is treated as a startup failure rather than silently overriding another — but that is a catalog of Verdonz’s own capabilities, not of other people’s servers.

What is MCP governance?

MCP governance is deciding and enforcing which AI clients may use which capabilities, and being able to account for what they did. In Verdonz that means an authenticated caller, a per-tool permission check that is stricter for anything which changes state, refusal by default when no permissions are present, and request records that attribute activity back to MCP.

How does an MCP server connect AI agents to enterprise data?

By offering tools that reach the data rather than handing over a connection string. In Verdonz an agent does not receive database credentials; it calls a tool that runs a query against the semantic layer, so the metric it asks for is the metric the organization defined. The datasource tools describe what is connected without ever returning credentials.

Does Verdonz support MCP resources and prompts?

Not today. The protocol defines resources and prompts alongside tools, and Verdonz implements the tools half: initialize, ping, tools/list and tools/call. A client that depends on resources or prompts will not find them here. Transport is HTTP POST; there is no streaming transport. See how Verdonz controls access to those tools.

Which MCP clients can connect to Verdonz?

Any client that speaks the Model Context Protocol over HTTP POST can connect to the Verdonz MCP server, including Claude Desktop, Claude Code and Cursor, and agents built against the MCP SDK. The Verdonz endpoint is a standard JSON-RPC 2.0 server, so no client-specific integration is needed.

How is an MCP server different from a REST API or a direct SQL connection?

A direct SQL connection hands an agent credentials and the whole database, and the agent still has to know the schema to ask anything. A REST API is narrower but the client must know which endpoint to call and what its fields mean. An MCP server advertises a described set of tools that a client discovers at run time, which is why the Verdonz server can expose a metric by name, check a permission on each tool call, and never release a connection string.

Does the Verdonz MCP server run in my own cloud, or is it hosted?

The MCP endpoint is part of the Verdonz platform rather than a separate service to place, so it follows the same deployment as the rest of your installation: on-premises, in your own cloud account, or in the Verdonz cloud. The data does not move in any of them: the server calls a tool that runs the query in your own connected system and returns the result.

Are MCP tool calls rate-limited or metered?

Rate limiting belongs to the Verdonz MCP gateway, the control layer in front of the endpoint, and the MCP gateway page covers the limits available and how they apply. Cost attribution is separate: MCP-originated model requests are tagged in the Verdonz request log, so spend driven by an agent is answerable alongside the rest of your AI usage rather than estimated. The MCP server itself records route-level metrics rather than a per-tool-call trace.