mcp-kyvos-server 2.1.0

mcp-kyvos-server is a server implementation that integrates the Kyvos platform with the Model Context Protocol (MCP). It enables users to query Kyvos semantic models using natural language, translating prompts into executable queries and returning results from Kyvos. The server supports Streamable HTTP, SSE and STDIO communication modes and allows secure authentication using user-provided Kyvos credentials (basic and OAuth2.0).

MCP Kyvos Server

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

• Streamable HTTP: The recommended transport for remote integrations. It operates statelessly over HTTP POST to the /mcp endpoint. Supports Basic and OAuth authorization.
• SSE (Server-Sent Events): A remote transport that keeps a persistent HTTP connection open for streaming. Suitable for clients that require long-lived SSE connections. Supports 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): Primarily used for inter-process communication within the same system. 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.

Note: The MCP specification has deprecated SSE transport for remote integrations. Streamable HTTP is now the recommended transport for all remote MCP server deployments.

---

Tools

The MCP Kyvos server exposes the following tools:

1. kyvos_list_semantic_model

   • Description: Lists available semantic models with schema details.

2. kyvos_semantic_model_details

   • Description: Retrieves column metadata, query generation rules, querying instructions and summary instructions for a specified semantic model.

**Note:**This tool replaces: kyvos_list_semantic_model_columns and kyvos_sql_generation_prompt, serving as a unified interface for retrieving column metadata as well as providing SQL generation guidance and rules.

3. kyvos_execute_query
   • Description: Executes a Spark SQL query on Kyvos.

Installation

Using uv (Recommended)

When using uv, no specific installation is needed. We will use uvx to directly run mcp-kyvos-server.

Note: Make sure you have uv installed. See the uv installation guide.

Using pip

Install the mcp-kyvos-server package from pip:

pip install mcp-kyvos-server

Configuration & 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
Kyvos URL	KYVOS_URL	--kyvos-url <url>	Yes	—	The base URL of the Kyvos server. Example: https://<server-address>:<port>/kyvos
Kyvos Username	KYVOS_USERNAME	--kyvos-username <username>	No	—	The Kyvos account username used to authenticate and log in to the Kyvos application. Required only for no_auth mode
Kyvos Personal Access Token	KYVOS_PERSONAL_ACCESS_TOKEN	--kyvos-personal-access-token <token>	No	—	The personal access token for the provided KYVOS_USERNAME, used for authentication with the Kyvos application. Required only for no_auth mode.
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 <mode>	No	streamable-http	The type of communication transport to use: streamable-http, sse for Server-Sent Events, or stdio for standard input/output
JSON Format	JSON_FORMAT	--json-format <true or false>	No	true	Controls the response format for streamable-http transport. true returns responses as JSON; false returns responses as Server-Sent Events (SSE streams)
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
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
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	basic	Type of authorization to start the server with
Port	—	--port <port>	No	8000	Port on which 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)
Log Level	—	--log-level	No	DEBUG	Specifies the log level to use (e.g., DEBUG, INFO, WARNING, ERROR, CRITICAL).

---

OAuth Callback URL: When configuring oauth as the auth type, you must register the following URL as the Redirect / Callback URI in your OAuth provider's application settings: https://:/auth/callback

Note: The is_folder_name_required parameter has been removed, and providing a folder name is now mandatory for all queries on the MCP server.

The password parameter has been deprecated. Please provide a Kyvos Personal Access Token (PAT) instead. For more details, refer to the following Documentation

Sample .env File

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

KYVOS_URL=https://kyvos.cloud/kyvos
KYVOS_USERNAME=your-username
KYVOS_PERSONAL_ACCESS_TOKEN=your-personal-access-token
KYVOS_DEFAULT_FOLDER=Business Catalog
MCP_SERVER_URL=https://mcp-server:9090

---

AI Space & Semantic Model URL Parameters

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

Query Parameters

Parameter	Description
entityType	Querying mode: AISpace for AI Space queries, or omit for Semantic Model queries.
folderName	Name of the folder containing the semantic model(s) or AI Space.
entityName	When entityType=AISpace: name of the AI Space to query. When querying a Semantic Model: name of the specific semantic model (optional — omit to list all models in the folder).

Mode: AI Space (entityType=AISpace)

Targets semantic models residing within a specific Kyvos AI Space. Both entityName (AI Space name) and folderName are required.

http://<machine_ip>:<port>/mcp?entityType=AISpace&folderName=SalesFolder&entityName=SalesSpace

Mode: Semantic Model (no entityType)

Targets semantic models of a particular folder, or a specific semantic model directly. entityName is optional — if not provided, all semantic models within the given folder will be available for querying.

http://<machine_ip>:<port>/mcp?folderName=SalesFolder&entityName=RevenueSM

Without entityName (all models in folder):

http://<machine_ip>:<port>/mcp?folderName=SalesFolder

Client Configuration Example

{
  "mcpServers": {
    "kyvos-http": {
      "url": "http://<machine_ip>:<port>/mcp?entityType=AISpace&folderName=SalesFolder&entityName=SalesSpace"
    }
  }
}

Scoped Querying in STDIO Mode

Similar to HTTP/SSE mode's URL query parameters, STDIO mode supports scoped querying via environment variables or CLI --env-file.

Environment Variable	Description
ENTITY_TYPE	Querying mode: set to AISpace for AI Space queries. Omit or leave empty for Semantic Model queries.
FOLDER_NAME	Folder containing the semantic model(s) or AI Space.
ENTITY_NAME	When ENTITY_TYPE=AISpace: name of the AI Space. For Semantic Model mode: name of a specific model (optional).

---

Note: The parameters requestType, AISpaceName, and semanticModelName will get deprecated in upcoming versions. Users are encouraged to transition to entityType and entityName.

No-Auth Mode

The MCP Kyvos Server supports for no authentication mode for scenarios where the client application only supports OAuth-based MCP servers, but the user does not want to go through a real OAuth flow.

In this mode:

• The client does not perform real OAuth authentication
• The MCP server authenticates internally using configured Kyvos username and PAT
• The server generates and returns simulated OAuth tokens to the client

---

How It Works

When no_auth is enabled:

1. The client connects as if using OAuth.

2. The MCP server authenticates to Kyvos using:

   • KYVOS_USERNAME
   • KYVOS_PERSONAL_ACCESS_TOKEN

3. The server loads token values from a provided JSON file.

4. The server returns those tokens to the client as a simulated OAuth response.

---

Starting the Server in No Auth Mode

mcp-kyvos-server --transport streamable-http --server-auth-type no_auth --env-file /path/to/.env 

---

When to Use No-OAuth

Use no_auth when:

• Your client (e.g. Claude connector) requires an OAuth-based MCP server
• You do not want to configure or go through a real OAuth flow
• You prefer to authenticate using a username and PAT set directly in the server environment

---

Usage

Streamable HTTP Mode

1. Start the MCP server with streamable-http transport (or omit --transport since it is the default):

   Using env file:

   mcp-kyvos-server --transport streamable-http --env-file /path/to/.env
   

   Or provide arguments directly:

   mcp-kyvos-server --kyvos-url https://your-kyvos-endpoint --kyvos-username user123 --kyvos-personal-access-token your-token
   

2. Configure your client application to point to the /mcp endpoint:

   {
     "mcpServers": {
       "kyvos-http": {
         "url": "http://<machine_ip>:<port>/mcp"
       }
     }
   }
   

   With scoped query parameters:

   http://<machine_ip>:<port>/mcp?folderName=SalesFolder&entityName=RevenueSM
   

   AI Space mode:

   http://<machine_ip>:<port>/mcp?entityType=AISpace&folderName=SalesFolder&entityName=SalesSpace
   

---

SSE Mode

1. Start the MCP server with SSE transport.

   Using env file:

   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 
   

2. Configure your client application to include the SSE server in its MCP server configuration:

   {
     "mcpServers": {
       "kyvos-sse": {
         "url": "http://<machine_ip>:<port>/sse"
       }
     }
   }
   

STDIO Mode

Configure your client application as follows:

Using uvx:

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

Using pip:

{
  "mcpServers": {
    "kyvos-stdio": {
      "command": "python3",
      "args": [
        "-m", 
        "mcp_kyvos_server", 
        "--env-file", 
        "/path/to/.env"
      ]
    }
  }
}

Note: If using a virtual environment, provide the full path to the environment's python executable (/path/to/venv/python3). On Windows, replace python3 with python.

Claude Desktop Usage

STDIO Mode Configuration

Using uvx

Add this to your claude_desktop_config.json:

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

Using pip

If you've installed mcp-kyvos-server via pip:

pip install mcp-kyvos-server

Use Python module directly

{
  "mcpServers": {
    "kyvos-stdio": {
      "command": "python3",
      "args": [
        "-m", 
        "mcp_kyvos_server", 
        "--env-file", 
        "/full/path/to/.env"
      ]
    }
  }
}

Note: If using a virtual environment, provide the full path to the environment's python executable (/path/to/venv/python3). On Windows, replace python3 with python.

---

Streamable HTTP Mode Support (Remote)

Important: Claude Desktop does not natively support Streamable HTTP Mode. It only supports stdio transport.

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

Setup with mcp-remote

1. Install Node.js (v18 or higher) - Download here

2. Configure Claude Desktop to use mcp-remote via npx:

   {
     "mcpServers": {
       "mcp-server": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "http://<your-machine-ip>:<port>/mcp",
           "--allow-http"
         ]
       }
     }
   }
   

   Note: Replace <your-machine-ip> and <port> with the actual address of your HTTP server. Use the --allow-http flag if using HTTP-based MCP server URL.

   If your claude_desktop_config.json already contains other settings (e.g., preferences), merge only the mcpServers block into the existing file. For example:

   {
     "mcpServers": {
       "kyvos-http-oauth": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "http://<your-machine-ip>:<port>/mcp",
           "--allow-http"
         ]
       }
     },
     "preferences": {
       ...your existing preferences...
     }
   }
   

   Passing Scoped Query Parameters via Headers (Recommended for Claude Desktop)

   Claude Desktop uses mcp-remote as a stdio-to-http bridge. Because Claude Desktop cannot append query parameters to the mcp URL directly, you can pass scoped query parameters as custom request headers instead. The server reads these headers as a fallback when URL query parameters are absent.

   Note: This requires Node.js v18 or higher and uses npx mcp-remote.

   Supported Headers

   Header	Equivalent URL Query Parameter	Description
   Kyvos-Entity-Type	entityType	Querying mode: set to AISpace for AI Space queries. Omit for Semantic Model queries.
   Kyvos-Folder-Name	folderName	Folder containing the semantic model(s) or AI Space.
   Kyvos-Entity-Name	entityName	AI Space name when entityType=AISpace; specific semantic model name for Semantic Model mode (optional).

   Configuration Example

   Add this to your claude_desktop_config.json:

   {
     "mcpServers": {
       "kyvos-mcp": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "http://<your-machine-ip>:<port>/mcp",
           "--allow-http",
           "--header", "Kyvos-Entity-Type:${KYVOS_ENTITY_TYPE}",
           "--header", "Kyvos-Folder-Name:${KYVOS_FOLDER_NAME}",
           "--header", "Kyvos-Entity-Name:${KYVOS_ENTITY_NAME}"
         ],
         "env": {
           "KYVOS_ENTITY_TYPE":  "AISpace",
           "KYVOS_FOLDER_NAME":  "SalesFolder",
           "KYVOS_ENTITY_NAME":  "SalesSpace"
         }
       }
     }
   }
   

   Note: Only include the headers relevant to your querying mode. For Semantic Model mode, Kyvos-Entity-Type can be omitted. Kyvos-Entity-Name is optional for Semantic Model mode — omit it to query all models in the folder.

   Mode-specific Examples

   AI Space mode:

   "env": {
     "KYVOS_ENTITY_TYPE": "AISpace",
     "KYVOS_FOLDER_NAME": "SalesFolder",
     "KYVOS_ENTITY_NAME": "SalesSpace"
   }
   

   Semantic Model mode (specific semantic model):

   "env": {
     "KYVOS_FOLDER_NAME": "SalesFolder",
     "KYVOS_ENTITY_NAME": "revenue_model"
   }
   

   Semantic Model mode (all models in folder):

   "env": {
     "KYVOS_FOLDER_NAME": "SalesFolder"
   }
   

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.

Note: If you encounter an OAuth authorization error, try the following steps:

1. Delete the .mcp-auth folder

   • On Linux/macOS:

     ~/.mcp-auth
     

   • On Windows (Command Prompt):

     C:\Users\<your-username>\.mcp-auth
     

2. Restart the mcp-kyvos-server

Gemini CLI Usage

STDIO Mode Configuration

To integrate mcp-kyvos-server with Gemini CLI, use the STDIO transport mode. This allows Gemini to spawn and communicate with the MCP Kyvos server locally.

Using uvx

In your Gemini CLI configuration file (e.g., ~/.gemini/config.json), add the following MCP server entry:

{
  "mcpServers": {
    "kyvos-stdio": {
      "command": "uvx",
      "args": [
        "mcp-kyvos-server", 
        "--env-file", 
        "/full/path/to/.env"
      ]
    }
  }, 
  "theme": "Default",
  "selectedAuthType": "oauth-personal"
}

Using pip

If you've installed mcp-kyvos-server via pip:

pip install mcp-kyvos-server

** Use Python module directly**

{
  "mcpServers": {
    "kyvos-stdio": {
      "command": "python3",
      "args": [
        "-m", 
        "mcp_kyvos_server", 
        "--env-file", 
        "/full/path/to/.env"
      ]
    }
  },
  "theme": "Default",
  "selectedAuthType": "oauth-personal"
}

---

Streamable HTTP Mode Support (Remote)

Important: Gemini CLI does not natively support Streamable HTTP mode. It only supports stdio transport.

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

Setup with mcp-remote

1. Install Node.js (v18 or higher) - Download here

2. Configure Claude Desktop to use mcp-remote via npx:

   {
     "mcpServers": {
       "mcp-server": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "http://<your-machine-ip>:<port>/mcp",
           "--allow-http"
         ]
       }
     },
     "theme": "Default",
     "selectedAuthType": "oauth-personal"
   }
   

   Note: Replace <your-machine-ip> and <port> with the actual address of your mcp server. Use the --allow-http flag if using HTTP-based MCP server URL.

Note: If you encounter an OAuth authorization error, try the following steps:

1. Delete the .mcp-auth folder

   • On Linux/macOS:

     ~/.mcp-auth
     

   • On Windows (Command Prompt):

     C:\Users\<your-username>\.mcp-auth
     

2. Restart the mcp-kyvos-server

---

License

This project is licensed under the MIT License.