Kyvos Model Context Protocol (MCP) Server 2.0.0

✅ Enterprise: AWS, Azure, GCP, and On-Premises

✅ Marketplace: AWS, Azure, and GCP

✅ SaaS: AWS, Azure, and GCP

✅ Single Node Installation (SNI)

This section details the Kyvos Model Context Protocol (MCP) Server, which enables AI applications or agents to connect with the Kyvos platform, submit natural language queries, and retrieve insights from Kyvos semantic models through standardized MCP communication.

The Kyvos MCP Server is a server-side component that connects the Kyvos platform with the Model Context Protocol (MCP) client-server architecture. The server supports both SSE and STDIO communication modes and allows secure authentication using user-provided Kyvos credentials (basic and OAuth2.0). It accepts natural language (NL) queries, translates them into executable SQL, and retrieves results from the Kyvos engine. This setup allows users to query Kyvos semantic models using natural language, enabling AI-driven insights without the need for advanced technical skills.

Note

Kyvos MCP Kyvos Server Version 2.0.0 is compatible with Kyvos 2026.3.x.

Authentication Support

To ensure secure integration and access, the Kyvos MCP Server supports the following authentication mechanisms:

Basic Authentication: Using a valid username and password combination.
OAuth 2.0 Authentication: For token-based secure access, suitable for enterprise-grade deployments.

Supported Deployment Modes

Kyvos MCP Server can be deployed in the following communication modes:

Local Mode
- Server-Sent Events (SSE)
- Standard Input/Output (STDIO)
Remote Mode
- SSE only

This flexibility allows integration in a variety of system architectures, including containerized environments or remote LLM agents.

The MCP Kyvos Server enables agentic applications to interact with the Kyvos platform for querying business data. It supports two transport modes:

SSE (Server-Sent Events): This transport is suited for remote integrations. It uses HTTP requests for communication. It allows servers to handle multiple client connections efficiently. SSE mode supports both Basic and OAuth authorization. OAuth requires users to authenticate using their Kyvos credentials before establishing a connection, providing a secure and standardized login mechanism.
STDIO (Standard I/O): This transport is primarily used for inter-process communication within the same system. It’s particularly suitable for command-line tools and local integrations where the client and server operate within the same process. Only Basic authorization is supported in this mode.

A user poses a natural language (NL) question.
The MCP Client uses an LLM to interpret the question and interacts with the MCP Kyvos Server to retrieve relevant answers.
The server translates the natural language input into an SQL query.
- It communicates with the Kyvos Semantic Model, sending queries and receiving both metadata and data.
- The response is then sent back to the MCP Client, which forwards the final answer to the user.

The Kyvos MCP Server helps you to:

Enable Conversational BI within dashboards and analytical applications.
Provide self-service analytics through natural language without requiring SQL expertise.
Accelerate insight generation for business users using AI-driven query transformation.

MCP Server Tools

The Kyvos MCP Server provides a set of standardized tools accessible to MCP clients:

kyvos_list_semantic_model: Retrieves a list of all available and accessible semantic models for the authenticated user within Kyvos.
kyvos_list_semantic_model_details: Retrieves column metadata for a specified semantic model as:
- Column name
- Associated tags
- Descriptions
- Query generation rules
- Querying instructions
- Summary instructions
kyvos_execute_query: Executes a Spark SQL query on Kyvos and returns a json based result set.

Note

From MCP Kyvos Server PYPI Version 2.0.0, the kyvos_sql generation prompt tool has been deprecated.

Support for No Authentication

The MCP Kyvos Server supports for no authentication mode for scenarios where the client application does not support OAuth, but OAuth-style flow is still required by the integration.

In this mode:

The client does not perform real OAuth authentication
The MCP server authenticates internally using configured Kyvos username and password
The server generates and returns simulated OAuth tokens to the client
This allows OAuth-based workflows to function even when the client lacks native OAuth support

How It Works

When no authentication is enabled:

The client connects as if using OAuth.
The MCP server authenticates to Kyvos using:
- KYVOS_USERNAME
- KYVOS_PASSWORD
The server loads token values from a provided JSON file.
The server returns those tokens to the client as a simulated OAuth response.

This allows clients that only support Basic-style authentication to operate in environments where OAuth mode is expected.

Starting the Server in No-Auth Mode

mcp-kyvos-server --transport sse --server-auth-type no_auth

When to Use No-Auth

Use no_auth when:

The client application does not support OAuth
You need to simulate OAuth behavior
The MCP Kyvos Server provides a no_auth authentication mode.
This is designed for situations where the client application servers without OAuth, yet an OAuth-style flow is necessary for integration.
In MCP server param include --server-auth-type as no_auth.

Support for AI Space

The MCP Kyvos Server supports scoped querying through URL query parameters appended to the `/sse` endpoint. The `type` parameter determines the querying mode.

Query Parameters

Parameter	Description

Parameter	Description
`requestType`	Querying mode: `AI_Space` or `Semantic_Model`. Defaults to `semanticmodel` if not provided.
`AISpaceName`	Name of the Kyvos AI Space to query within. Used when `requestType=AI_Space`.
`folderName'	When `requestType=Semantic_Model`: Name of the folder containing the semantic models. When `requestType=AI_Space`: Name of the folder containing the AI Space.
`semanticModelName`	Name of the specific semantic model to query. Used when `requestT

Mode: AI Space (`requestType=AI_Space`)

Targets semantic models residing within a specific Kyvos AI Space. Both `AISpaceName` and `folderName` are required.
http://<machine_ip>:<port>/sse?requestType=AI_Space&folderName=SalesFolder&AISpaceName=SalesSpace

Mode: Semantic Model (`requestType=Semantic_Model`)

Targets semantic models of a particular folder, or a specific semantic model directly. `semanticModelName` is optional — if not provided, all semantic models within the given folder will be available for querying. If the user intends to query only a particular semantic model, `semanticModelName` can be passed as a parameter; otherwise, only `folderName` is sufficient.
http://:/sse?requestType=Semantic_Model&folderName=SalesFolder&semanticModelName=…

Without `semanticModelName`: http://<machine_ip>:<port>/sse?requestType=Semantic_Model&folderName=SalesFolder

Client Configuration Example

{
  "mcpServers": {
    "kyvos-sse": {
      "url": "http://<machine_ip>:<port>/sse?type=aispace&spaceName=SalesSpace&folderName=SalesFolder"
    }
  }
}

Scoped Querying in STDIO Mode

Similar to SSE mode's URL query parameters (`requestType`, `folderName`, etc.), STDIO mode supports scoped querying via environment variables or CLI `--env-file`.

Environment Variable	Description

Environment Variable	Description
`REQUEST_TYPE`	Querying mode: `AI_Space` or `Semantic_Model`
`FOLDER_NAME`	Folder containing the semantic model(s) or AI Space
`AI_SPACE_NAME`	Name of the Kyvos AI Space. Required when `TYPE=AI_Space`
`SEMANTIC_MODEL_NAME`	Name of a specific semantic model. Used when `TYPE=Semantic_Model`

Python Requirements

The Kyvos MCP Server requires Python version 3.10 or higher.

Installation

Install the mcp-kyvos-server package from pip:

pip install mcp-kyvos-server

Configuration and Parameters

The server can be configured via environment variables or command-line flags. CLI flags override environment variables.

Parameter	Environment Variable	CLI Flag	Required	Default Value	Description

Parameter	Environment Variable	CLI Flag	Required	Default Value	Description
Kyvos URL	`KYVOS_URL`	`--kyvos-url <url>`	Yes	—	The base URL of the Kyvos server instance.
Kyvos Username	`KYVOS_USERNAME`	`--kyvos-username <username>`	Yes	—	The Kyvos account username used to authenticate and log in to the Kyvos application. It will be overridden if using OAuth or basic-auth flow.
Kyvos Password	`KYVOS_PASSWORD`	`--kyvos-password <password>`	Yes	—	The corresponding password for the provided `KYVOS_USERNAME`, used for authentication with the Kyvos application. It will be overridden if using OAuth or basic-auth flow.
Default Folder	`KYVOS_DEFAULT_FOLDER`	`--kyvos-default-folder <folder>`	No	—	Folder containing multiple semantic models used for querying and metadata management in the Kyvos platform.
Transport	—	`--transport <stdio or sse>`	No	`stdio`	The type of communication transport to use: `stdio` for standard input/output or `sse` for Server-Sent Events.
SSL Verification	`VERIFY_SSL`	`--verify-ssl <true or false>`	No	`false`	Flag to enable or disable SSL certificate verification when making HTTP requests to Kyvos. Set to `true` to enforce verification or `false` for self-signed certs.
Max Rows	`MAX_ROWS`	`--max-rows <max rows>`	No	1000	Limit the number of rows in the query response
Environment File	—	`--env-file <file_path>`	No	—	Path to an `.env` file from which to load environment variables, if not provided via arguments.
SSL Key	`SSL_KEY_FILE`	`--ssl-key-file <file_path>`	No	—	Path to the SSL private key file used to enable HTTPS on the server.
SSL Certificate	`SSL_CERTIFICATE_FILE`	`--ssl-certificate-file <file_path>`	No	—	Path to the SSL certificate file used to enable HTTPS on the server.
Auth type	`SERVER_AUTH_TYPE`	`--server-auth-type <basic/oauth/no-auth>`	No	`oauth`	Type of authorization user want to start the server
Port	—	`--port <port>`	No	8000	Port on which user want to run the server.
MCP Server URL	`MCP_SERVER_URL`	`--mcp-server-url <url>`	Yes	-	The full URL where the MCP server will run (e.g., http://mcp.server:9090)
MCP Kyvos Server Database Path	`MCP_KYVOS_DB_PATH`	-	No	HOME_PATH/.mcp_kyvos_server	The path where the MCP server database will be created.
Log Level	-	--log-level	No	DEBUG	Specifies the log level to use (e.g., DEBUG, INFO, WARNING, ERROR, CRITICAL).

Creating .env file

To create a .env file with the required parameters for your MCP-Kyvos server:

KYVOS_URL=https://kyvos.cloud/kyvos
KYVOS_USERNAME=your-username
KYVOS_PASSWORD=your-password
KYVOS_DEFAULT_FOLDER=Business Catalog
MCP_SERVER_URL=http://<machine_ip>:<port>

Usage

SSE Mode

Start the MCP server with SSE transport.
mcp-kyvos-server --transport sse --env-file /path/to/.env
or provide arguments directly:
mcp-kyvos-server \ --kyvos-url https://your-kyvos-endpoint \ --kyvos-username user123 \ --kyvos-password pass123
Configure your client application to include the SSE server in its MCP server configuration. For example:
{ "mcpServers": { "kyvos-sse": { "url": "http://<machine_ip>:<port>/sse" } } }

STDIO Mode

Configure your client application. For example:

{
  "mcpServers": {
    "kyvos-stdio": {
      "command": "mcp-kyvos-server",
      "args": [
        "--env-file", "/path/to/.env"
      ]
    }
  }
}

OR

  {
    "mcpServers": {
      "kyvos-stdio": {
        "command": "mcp-kyvos-server",
        "args": [
          "--kyvos-url", "https://your-kyvos-endpoint",
          "--kyvos-username", "user123",
          "--kyvos-password", "pass123",
          "--kyvos-prompt-file", "./kyvos_prompt.txt"
        ]
      }
    }
  }

Claude Desktop Usage

SSE Mode Support (Remote)

Important

Claude Desktop does not natively support SSE (Server-Sent Events). It only supports stdio transport.

To connect Claude Desktop to a remote SSE MCP server, use mcp-remote, a CLI tool that bridges remote SSE servers to local stdio clients.

To setup with mcp-remote, perform the following steps.

Install Node.js (v18 or higher) from here.
Configure Claude Desktop to use mcp-remote via npx:
{ "mcpServers": { "mcp-server": { "command": "npx", "args": [ "mcp-remote", "<http://<your-machine-ip>>:<port>/sse", "--allow-http" ] } } }
Replace <your-machine-ip> and <port> with the actual address of your SSE server. Use the --allow-http flag if using HTTP-based MCP server URL. After saving the configuration file, completely quit Claude Desktop and restart it. The application needs to restart to load the new configuration and start the MCP server.
If you encounter an OAuth authorization error, try the following steps:
Delete the .mcp-auth folder.
- On Linux/macOS:
  ~/.mcp-auth
- On Windows (Command Prompt):
  C:\Users\<your-username>\.mcp-auth
Restart the mcp-kyvos-server.

Data Security and Access Control

Kyvos enforces all existing data security policies and access privileges based on the authenticated user's profile. The MCP server ensures that only authorized users can access specific semantic models, metadata, and business data, in alignment with the organization’s governance and role-based access controls.

For a sample client implementation to interact with Kyvos MCP server, refer to Kyvos Sample Client.