Denodo MCP Server - User Manual

Last modified on: 20 Nov 2025

Download original document


You can translate the document:

Overview

The Denodo Model Context Protocol (MCP) Server is an interface that allows AI models and external applications to interact with the Denodo Platform. It provides a standardized protocol for any client to connect to Denodo's data virtualization engine.

Through a set of structured tools and resources, the MCP Server enables clients to understand the data model and make queries by generating accurate SQL from natural language questions. This approach simplifies the process for AI clients to leverage Denodo's capabilities.

This manual provides a comprehensive guide to the Denodo MCP Server, covering its architecture and configuration.

Features

The Denodo MCP Server provides:

  • Read-only access to Denodo databases

  • The following MCP resources:

  • A resource describing the complete metadata of the database.

  • Individual resources to describe the metadata of each individual view.

  • The following MCP tools:

  • A tool to return the complete metadata of the database.

  • A tool to receive an SQL query and return the results.

  • Dedicated tools for querying every view marked with a certain configurable tag.

  • Notifications for changes to resource and tool lists.

  • HTTP Authentication:

  • Basic

  • Support for Model Context Protocol version 2025-06-18.

Installation and configuration

Installation

The Denodo MCP Server is distributed as a DenodoConnect that can be downloaded on the Support site.

This Denodo MCP Server distribution consists of:

  • Command-line executable scripts for Windows and Linux (/bin folder)

  • Configuration files: application.properties and log4j2.xml (/config folder)

  • Java libraries (/lib folder)

  • Denodo MCP Service application jar: denodo-mcp-server-<version>-jar

  • Denodo driver jar: denodo-vdp-jdbcdriver-dist-<version>-full.jar 

If you need to use a Denodo driver version different to the one that is distributed, you only need to replace this jar with the Denodo driver of the proper version.

For installing it just download the .zip file and extract the service into the desired folder.

To run it, you need Java 17 and the environment variables JAVA_HOME and PATH correctly configured.

After running the script in the /bin folder (you must be in the /bin folder to run the command.), you can use the Denodo MCP Server from a MCP client, using HTTP Basic Authentication or OAuth 2.0 with Denodo-valid credentials.

Denodo MCP Server runs at: http://localhost:8080/<DBNAME>/mcp for Streamable HTTP transport and http://localhost:8080/<DBNAME>/sse for HTTP with SSE transport.

Configuration

The Denodo MCP Server has the following properties in the config/application.properties file:

cors.allowed-origins=*

mcp.tools.view-tag=mcp

mcp.transport.sse.endpoint=/sse

mcp.transport.streamable-http.endpoint=/mcp

spring.ai.mcp.server.keep-alive-interval=PT1H

vdp.datasource.driver-class-name=com.denodo.vdb.jdbcdriver.VDBJDBCDriver

vdp.datasource.jdbcUrl=jdbc:vdb://localhost:9999/?noAuth=true

  • cors.allowed-origins: the default value of the property cors.allowed-origins is *. But this value is not allowed as it is against the CORS specification and may cause security problems.

If you intend to use this server with clients running in a web browser, you must configure the property to include the list of allowed URLs (separate each URL by a comma), from which MCP connections are allowed. For example,  http://foo.com, https://foo.bar.com.

  • mcp.tools.prefix: a prefix can be configured to help name the Server's tools.  The <database_name> is an optional wildcard that can be added to the prefix to help distinguish between toolsets from different databases. By default this prefix is denodo_<database_name>_ .

  • mcp.tools.name-length-limit: sets a character limit for the names of all generated tools. By default, tool names are created with a prefix, the database name and optionally the view name. This can result in very long names that may cause issues in MCP clients with strict length restrictions.

Tool names are automatically truncated to the specified character limit. The default value is 64, and you can disable the limit by setting this property to -1.

  • mcp.tools.view-tag: an individual MCP tool is created for each view with this tag. If not specified, no view-dedicated query tools will be created.

  • mcp.tools.view.default-row-limit: default maximum number of rows returned for dedicated view query tools (like denodo_<database_name>_query_<view_name>). This default is applied unless the user explicitly specifies a different limit or clearly requests all results. Set to -1 or empty to disable the default. The default is 100.

  • mcp.oauth2.authorization-servers: comma-separated list of authorization server URLs that the MCP server exposes as part of its OAuth 2.0 Protected Resource Metadata (RFC9728) implementation.

To enable the MCP OAuth2.0 authorization flow in the Denodo MCP Server, its value must match the issuer field configured for OAuth2.0 authentication in VDP (configured through the com.denodo.vdb.security.OauthAuthenticator.jwtIssuer property of VDBConfiguration.properties file).

  • mcp.oauth2.scopes-supported: comma-separated list of OAuth2.0 scopes that the MCP server exposes as part of its OAuth 2.0 Protected Resource Metadata (RFC9728) implementation.

When the MCP OAuth2.0 authorization flow is enabled, MCP clients use this value to request the necessary scopes for an access token from the authorization server.

If the role extraction method is configured to token’s scope (com.denodo.vdb.security.OauthAuthenticator.roleExtraction=SCOPE), the value of this property must match the name of the role name assigned to users accessing the Denodo MCP Server.

  • mcp.transport.sse.endpoint: path where the HTTP with SSE MCP transport will be accessible. The default is /sse.

  • mcp.transport.streamable-http.endpoint: path where the Streamable HTTP MCP transport will be accessible. The default is /mcp.
  • mcp.resources.host: by default, the resources URI host is the same as the one specified in the vdp.datasource.jdbc-url. This property is used to override the default value.

  • mcp.schema-refresh.enabled: this property controls the refresh of the Denodo database schema within the context of an MCP session. When disabled, the server will not detect changes to views and resources, and clients will not be notified of updates to tool and resource lists.

  • spring.ai.mcp.server.keep-alive-interval: to clean inactive sessions from disconnected clients, the Denodo MCP Server periodically sends a ping to determine if a session should be removed. Setting long intervals can lead to memory issues. The default value for this interval is PT1H (1 hour).

  • server.port: Port at which the MCP Server listens to HTTP requests. The default is 8080.

  • vdp.datasource.driver-class-name: The full package name of the Denodo driver class. Its value is com.denodo.vdp.jdbc.Driver.

  • vdp.datasource.jdbc-url: The database URI to access Denodo from the MCP Server. Default is jdbc:vdb://localhost:9999/?noAuth=true.

SSL

Configuring the Denodo MCP Server with HTTPs requires two steps:

  1. Obtaining an SSL certificate

  1. Configuring SSL in Denodo MCP Server

In this section we focus on the second step, as it is the one that affects the MCP Server configuration.

For enabling HTTPS in the Denodo MCP Server you have to add Spring Boot server.ssl.* properties to the config/application.properties file. Here is an example:

# custom port instead of the default 8080

server.port=8443

# path to the key store that holds the SSL certificate

server.ssl.key-store=path_to_keystore.jks

# password used to generate the certificate

server.ssl.key-store-password=secret

# password to access the key in the key store

server.ssl.key-password=another-secret

Cross-Origin Resource Sharing (CORS)

CORS is a W3C specification implemented by browsers that allows you to specify what kind of cross domain requests are authorized.

The Denodo MCP Server default value of the property cors.allowed-origins is *. But this value is not allowed as it is against the CORS specification and may cause security problems.

You must configure the property to include the list of allowed URLs (separate each URL by a comma), from which MCP connections are allowed. For example,  http://foo.com, https://foo.bar.com.

CORS requests from any other origin will be denied with the HTTP code 403 (Forbidden).

NOTE: CORS only needs to be configured if a client running in a web browser is used to access the MCP Server. For desktop applications like VSCode, Cursor, Claude, or others, this configuration is not necessary.

Workspaces Support

The Denodo MCP Server supports Denodo workspaces. They can be used, in control-versioned databases, by including it in the X-Workspace HTTP header. Because HTTP headers are limited to printable ASCII characters, any Unicode characters in the workspace identifier must be percent-encoded, as they are in a URL. The workspace can also be specified as a URL query parameter named workspace.

Denodo Privilege Requirements

Users of Denodo MCP Server should have the following Denodo privileges assigned:

  •  At database level

  • Connect

  • At view level

  • Execute: if you do not have Execute access to an entire database, but you have it over some of its elements, the MCP Server will only allow you to query the elements over which you have Execute privileges.

Model Context Protocol

The Denodo MCP Server provides a set of structured tools and resources for interacting with and adding context to language models. These elements allow users to understand and query the Denodo data model in an intuitive way without needing prior technical knowledge of SQL or databases.

Tools

Two general-purpose tools are provided:

  • denodo_<database_name>_get_view_names
  • denodo_<database_name>_get_view_schema
  • denodo_<database_name>_get_database_schema
  • denodo_<database_name>_run_sql_query
  • denodo_<database_name>_validate_sql_query

In addition to these, the server creates a dedicated tool for each view that is tagged with the value of the mcp.tools.view-tag property. These view-specific tools are named like this:

  • denodo_<database_name>_query_<view_name>

NOTE: Some MCP clients don't work well with tools that have the same name. To address this, the Denodo MCP Server automatically prepends the prefix denodo_<database_name>_ to all of its tools to help distinguish them.

denodo_<database_name>_get_view_names

This tool accepts no arguments and returns a JSON array containing the list of all the view names within the specified database. The returned list is essential for identifying the correct view name needed by the denodo_<database_name>_get_view_schema tool.

Result of the denodo_<database>_get_view_names tool for the “bookstore” database

denodo_<database_name>_get_view_schema

This tool accepts a valid view name from the database as its argument and returns the corresponding Virtual DataPort (VDP) schema. The schema is identical to the one returned by the view schema resource.

This tool and the external view schema resource are interchangeable. Either one can be used to retrieve the necessary context for constructing a valid VQL query for the denodo_<database_name>_run_sql_query tool.

Result of the denodo_<database>_get_view_schema tool for the “bookstore”/"books" view

denodo_<database_name>_get_database_schema

Formerly known as denodo_<database_name>_get_available_views. This tool accepts no arguments and returns the complete VDP schema for the views in the current database. The result is identical to the one you would obtain by requesting the database schema resource.

Result of the denodo_<database>_get_database_schema tool for the “bookstore” database

denodo_<database_name>_query_<view_name>

A dedicated tool is created for each view tagged with the value of the mcp.tools.view-tag property. These tools accept two optional arguments: select_clause and where_clause. If neither is specified, all view columns will be retrieved (like a SELECT *), and no rows will be filtered. Additionally, it also supports a limit argument to control the maximum number of results returned by the query.

The tool’s description includes the schema of the view it queries. This eliminates the need to pre-load the database (or view) schema into the chat conversation before execution, unlike the denodo_<database_name>_run_sql_query tool.

Results of denodo_<database>_query_<view_name> tool for the “bookstore”/”books” view

denodo_<database_name>_run_sql_query

This tool accepts a grammatically and contextually correct SQL query as an argument and executes it against the Denodo Virtual DataPort Server, returning the result. It only allows SELECT statements; any other DML or DDL statements are prohibited and will not be executed.

This tool provides more flexibility than the denodo_<database_name>_query_<view_name> tool, as it supports complex queries with clauses such as JOIN, GROUP BY, and HAVING. Therefore, it is recommended in complex queries for powerful models that rarely make errors when generating SQL.

Result of query with JOIN in denodo_<database>_run_sql_query tool for the “bookstore” database

denodo_<database_name>_validate_sql_query

This tool accepts a SQL (VQL) query string for pre-execution validation. It rigorously checks the query's syntax and semantics against the target database, confirming both structural integrity and the existence of all referenced resources (views, fields). The tool returns a JSON response containing the validation status via the is_valid boolean and provides a detailed error_message in case of any failure.

Result of denodo_<database>_validate_sql_query: failed validation due to incorrect field name

Resources

The server provides schema information for both individual views and the entire database.

View schema

These resources are identified by the denodo://<host>/<database>/<view_name>/schema URI. The schema provides the view’s name, description, tags and columns (including their datatype, description, tags and subfields).This schema is returned in JSON format.

{

  "view_name": "books",

  "description": "This view contains a comprehensive list of all books available in the bookstore, including their unique identifiers, pricing, inventory levels, and publication details. It serves as a central source of truth for book data, linking to authors and publishers for complete book information.",

  "columns": [

    {

      "name": "title",

      "type": "NVARCHAR",

      "description": "The full title of the book."

    },

    {

      "name": "price",

      "type": "NUMERIC",

      "description": " The sale price of the book. The value is stored with two decimal places.",

      "tags": [

        "currency"

      ]

    },

    ...

  ],

  "tags": [

    "mcp"

  ]

}

Sample schema for books view (denodo://<host>/bookstore/books/schema)

Database schema

Aggregation of all the view schemas in the database. It is identified by the denodo://<host>/<database>/schema URI. They have the same information and format as in the view schema resource.

[

  {

    "view_name": "authors",

    "columns": [

      {

        "name": "id",

        "type": "INTEGER",

        "description": "The unique identifier for each author."

      },

      {

        "name": "author_name",

        "type": "NVARCHAR",

        "description": "The full name of the author."

      }

    ]

  },

  {

    "view_name": "books",

    "description": "This view contains a comprehensive list of all books available in the bookstore, including their unique identifiers, pricing, inventory levels, and publication details. It serves as a central source of truth for book data, linking to authors and publishers for complete book information.",

    "columns": [

      ...

    ],

    "tags": [

      "mcp"

    ]

  },

  ...

]

Sample schema for bookstore database  (denodo://<host>/bookstore/schema)

Transport

The server implements implements two of the standard transport mechanisms for client-server communication defined in the protocol:

Streamable HTTP

This transport protocol replaces the older HTTP with SSE in the newer versions of the specification (since 2025-03-26). It also makes use of Server Sent Events to stream messages and notifications to MCP Clients.

The endpoint for this transport is configured in the mcp.transport.streamable-http.endpoint property. By default, the URL is http://<host>:<port>/<database_name>/mcp.

HTTP with SSE

This was the standard transport protocol defined in the first version of the specification (2024-11-05). It is now provided as an option for backwards compatibility with legacy MCP Clients.

It can be accessed in the endpoint configured in the mcp.transport.sse.endpoint property. By default, the URL is  http://<host>:<port>/<database_name>/sse.

NOTE: If your MCP client doesn't natively support Streamable-HTTP or HTTP-with-SSE, we recommend using the mcp-remote tool. This NPM package acts as an intermediary, enabling clients that only support stdio to connect to the remote Denodo server.

Authentication

Any client using the Denodo MCP Server needs to authenticate itself with Denodo-valid credentials.

The authentication methods available are described below.

Basic

In HTTP Basic the Denodo user name and password are passed as unencrypted base64 encoded text with an Authorization HTTP request header.

 <username>:<password> -> Authorization: Basic YWRtaW46YWRtaW4=

OAuth 2.0

To use OAuth2 as an authentication method, you need to enable OAuth authentication on the Denodo server. The section OAuth Authentication of the Virtual DataPort Administration Guide explains how to do this.

Then, you need to obtain an access token. You can use the OAuth 2.0 credentials wizard in the Design Studio to obtain it. The wizard is available at Tools → OAuth credentials wizards → OAuth 2.0 Wizard.

OAuth 2.0 Credentials Wizard

For detailed instructions on obtaining a token using the credentials wizard, refer to the document: How to get the OAuth access token to connect to Denodo.

Once you have the access token you have to pass it to the Denodo MCP Server with an Authorization request header:

oauth_token -> Authorization: Bearer oauth_token

Dynamic Client Registration

To comply with the Model Context Protocol proposed authorization flow the Denodo MCP Server implements the OAuth 2.0 Protected Resource Metadata (RFC9728) standard.

This enables MCP Clients implementing the OAuth 2.0 Dynamic Client Registration Protocol (RFC7591) to be configured to automatically register themselves as authorization server clients, eliminating the need for manual, error-prone configuration steps.

This functionality is enabled by appropriately configuring the mcp.oauth2.authorization-servers and mcp.oauth2.scopes-supported properties.

For the authorization flow to be successfully configured with the OAuth 2.0 Dynamic Client Registration Protocol (RFC7591), you must ensure that the authorization server specified in the  mcp.oauth2.authorization-servers property supports both RFC 7591 and the OAuth 2.0 Authorization Server Metadata (RFC8414) standards.

Notable identity providers that fully support both RFC 7591 and RFC 8414 include Okta, Ping Identity or Keycloak. As of October 2025, Microsoft Entra ID and Google Identity do not support these protocols.

NOTE: If your Denodo identity provider doesn't support RFC 7591 or RFC 8414, you still can manually configure your MCP client. Most clients allow you to add custom headers, so you can manually get the access token using the OAuth 2.0 Credentials Wizard. Then, configure the MCP client to send this token in an Authorization header.

Limitations

Delays in schema refresh

The Denodo MCP Server is configured by default (see  mcp.schema-refresh.enabled property) to periodically refresh the database schema and check for changes in view metadata.

However, note that this refresh is not immediate. Clients may experience a delay in receiving notifications about view metadata changes until a subsequent request prompts the server to update.

Usage example with VSCode

This example shows the Denodo MCP Server being used with the VSCode editor.

Prerequisites

  • VS Code: Ensure you are running version 1.102 or newer.
  • GitHub Copilot Chat: The extension must be both installed and enabled.

Configuring the server

First, we need to configure our Denodo MCP Server by editing the  mcp.json file. This file can be accessed by using the MCP: Open User Configuration command from the VS Code command-palette:

Opening the mcp.json configuration file through the command palette

For this example, we will connect to a Denodo "bookstore" database to view books information. Our server is running locally in the default port.

This example assumes we have Dynamic Client Registration (DCR) authorization flow enabled, which only requires specifying the server URL and the transport type:

{

  "servers": {

    "denodo-bookstore-server": {

      "url": "http://localhost:8080/bookstore/mcp",

      "type": "http",

    }

  }

}

VSCode configuration with DCR enabled

If we don't have DCR enabled, we can configure the authorization header directly using one of the available authentication mechanisms:

{

  "inputs": [

    {

      "type": "promptString",

      "id": "denodo_oauth_token",

      "description": "Denodo OAuth 2.0 Token",

      "password": true

    }

  ],

  "servers": {

    "denodo-<database_name>-server": {

      "url": "http://localhost:8080/bookstore/mcp",

      "type": "http",

      "headers": {

        "Authorization": "Bearer ${input:denodo_oauth_token}"

      }

    }

  }

}

VSCode configuration example without DCR enabled

Once we have this file saved, we can start the connection using the start button right above the server name:

With Dynamic Client Registration enabled, a browser window will open, prompting you to enter your credentials on your identity provider's login page. Once authenticated, you can begin using the server.

Retrieving a resource for schema information

In VSCode, we can see the list of available resources in the Denodo MCP by executing the MCP: Browse Resources command.

Resources list in VSCode for the "bookstore" database

In this case, we will open the "bookstore" database resource (to view the complete schema of the database), and it will be automatically loaded in the VSCode chat context.

Now, we can ask the agent to provide information about the database:

Using the database schema resource to learn about the available views in the "bookstore" database

Querying the database

To query the database, you can use one of the dedicated query tools available for views tagged with mcp.tools.view-tag tag or the general denodo_bookstore_run_sql_query.

For example, to retrieve books of the "Science" genre published before 2005, you would use a prompt that directs the VSCode agent to execute the denodo_bookstore_query_books tool.

Querying the "books" table with the denodo_bookstore_query_books tool

As shown, in this case it was not necessary to pre-load the database schema into the chat. This is because the dedicated tool already contains the required metadata information within its description.