mcp-kyvos-server 2.4.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. OAuth requires users to authenticate using their Kyvos credentials before establishing a connection, providing a secure and standardized login mechanism.
• 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.
• 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.

---

Tool Categories

The MCP Kyvos Server exposes tools in two categories,

building_blocks

Use this toolkit when answers to be generated through multiple tool calls and orchestrated workflows.

1. kyvos_get_aispace

   • Description: Returns the list of semantic models in the AI Space with business context, querying context, summary context, and the Knowledge Base catalogue.

2. kyvos_get_semantic_model

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

3. kyvos_execute_query

   • Description: Executes a Spark SQL query on Kyvos.

4. kyvos_search_docs

   • Description: Fetches the content of a specific knowledge base document by name using a natural language question.

5. kyvos_lookup_business_relationships

   • Description: Looks up business relationships context for KPIs, measures, dimensions, and business entities.

insights

Use this toolkit when the client application should delegate query execution to Kyvos end-to-end via Kyvos Dialogs.

1. kyvos_get_aispace

   • Description: Returns information about the AI Space, including its business context.

2. kyvos_get_insights

   • Description: Translates a natural-language question into SQL, executes it against the Kyvos semantic model, and returns results as summary, data or both.

Note: kyvos_list_semantic_model and kyvos_semantic_model_details has been renamed to kyvos_get_aispace and kyvos_get_semantic_model.

The kyvos_get_semantic_model tool now accepts semantic_model_name and folder_name as required input parameters.

Access to Insights mode requires Kyvos Dialogs license.

Important: Direct semantic model querying on the Kyvos MCP Server is being discontinued and replaced by the AI Space flow. This allows you to query across all semantic models within a given AI Space under a single, unified context.

System Requirements

OS Requirements

OS	Processor	Cores	RAM
RHEL/ Amazon linux 2023	Any 64-bit processor	4 cores minimum	8 GB minimum (16 GB recommended)
macOS	Apple M1 or Intel equivalent	4 cores minimum	8 GB minimum (16 GB recommended)
Windows 11	Intel Core i5 or higher	6 cores minimum	16 GB minimum (16 GB recommended)

---

MCP Kyvos Server Version	Kyvos Platform Version
2.1.2	Kyvos 2026.4.1 and above
2.2.0	Kyvos 2026.6 and above
2.3.0	Kyvos 2026.6 and above
2.4.0	Kyvos 2026.9 and above

Required Software

Install the following before proceeding:

• Python 3.10 or higher — version 3.12 is recommended. Verify by running python --version or python3 --version.
• pip — comes bundled with Python. No separate installation needed.
• venv — built into Python 3.3 and above. No separate installation needed.

Setting Up a Virtual Environment (Recommended)

Linux and macOS

# Confirm Python is installed
python3 --version

# Create a virtual environment
python3 -m venv <venv name>

# Activate it
source <venv name>/bin/activate

Windows — Command Prompt

# Confirm Python is installed
python --version

# Create a virtual environment
python -m venv <venv name>

# Activate it
<venv name>\Scripts\activate

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.
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)
Toolkit	TOOLKIT	--toolkit <insights/building_blocks/all>	No	building_blocks	Tool category to expose. building_blocks exposes kyvos_get_aispace, kyvos_get_semantic_model, and kyvos_execute_query. insights exposes kyvos_get_aispace and kyvos_get_insights. all exposes every tool and lets each request choose via the toolkit URL query parameter (insights or building_blocks); if a request omits it, all tools are loaded and kyvos_get_aispace behaves as building_blocks. When the server is set to insights or building_blocks, the request's toolkit query parameter is ignored.
SSL Verification	VERIFY_SSL	--verify-ssl <true or false>	No	true	Enables or disables SSL certificate verification for HTTPS requests to Kyvos. Set to false only when using self-signed or internal CA certificates that are not in the OS trust store. Has no effect when KYVOS_URL is HTTP.
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:8000)
Log Level	—	--log-level	No	INFO	Specifies the log level to use (e.g., DEBUG, INFO, WARNING, ERROR, CRITICAL, NONE).
Log File	—	--log-file <file_path>	No	Platform-specific log location	Path to the log file. Overrides the default platform-specific log location.
Log Max Bytes	LOG_MAX_BYTES	--log-max-bytes <bytes>	No	5242880 (5 MB)	Maximum size in bytes a log file can reach before it is rotated.
Log Max Files	LOG_MAX_FILES	--log-max-files <count>	No	4	Total number of log files to keep on disk, including the active log file (e.g. 4 = 1 active + 3 rotated). Older files beyond this count are deleted on rotation.

---

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 no longer supported. 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
MCP_SERVER_URL=https://mcp-server:8000

---

Querying AI Space

The MCP Kyvos Server supports scoped querying through URL query parameters appended to the /mcp endpoint.

Query Parameters

Parameter	Description
folderName	Name of the folder containing the AI Space.
entityName	Name of the AI Space to query.

Sample URL

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

Client Configuration Example

{
  "mcpServers": {
    "kyvos-http": {
      "url": "http://<machine_ip>:<port>/mcp?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
FOLDER_NAME	Folder containing the semantic model(s) or AI Space.
ENTITY_NAME	Name of the AI Space.

---

Note: The parameters AISpaceName will get deprecated in upcoming versions. Users are encouraged to transition to entityName.

Note: The entityType/ENTITY_TYPE parameter is no longer supported following the removal of direct querying on the Semantic Model. The entity type is now automatically set to AI Space.

Alternatively, kyvos_get_aispace, kyvos_get_insights, and kyvos_search_docs also accept the AI Space and folder as optional tool arguments (aispace_name, folder_name) — useful when the client cannot append query parameters to the URL. If both are provided, the URL query parameter takes precedence.

Configuring OAuth Mode

1. Set Up OAuth on Kyvos

Configure the callback URL in the OIDC provider by adding the following as a registered Redirect/Callback URI, e.g.:

https://<mcp-server-host>:<port>/auth/callback

2. Configure the User in OIDC and Kyvos

• Create/configure the user in the OIDC provider.
• Create the same user in Kyvos.
• Ensure the user details and authentication configuration match between both systems.

3. Configure the MCP Server

1. Install mcp-kyvos-sever and Create/configure the .env file (see Sample .env File) and add:

   MCP_SERVER_URL=https://<mcp-server-host>:<port>
   

   Use the public/external URL of the server, without the /mcp suffix.

2. Start the MCP server with OAuth authentication:

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

3. Configure the MCP server URL in your MCP client, optionally with scoped query parameters:

   https://<mcp-server-host>:<port>/mcp?entityName=<AISpaceName>&folderName=<FolderName>
   

---

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 returns proxy token 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"
       }
     }
   }
   

   AI Space mode:

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

---

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",
           "https://<your-machine-ip>:<port>/mcp"
         ]
       }
     }
   }
   

   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",
           "https://<your-machine-ip>:<port>/mcp"
         ]
       }
     },
     "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-Folder-Name	folderName	Folder containing AI Space.
   Kyvos-Entity-Name	entityName	AI Space name.

   Configuration Example

   Add this to your claude_desktop_config.json:

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

Note: The Kyvos-Entity-Type parameter is no longer supported following the removal of direct querying on the Semantic Model. The entity type is now automatically set to AI Space.

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",
           "https://<your-machine-ip>:<port>/mcp"
         ]
       }
     },
     "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.