Kyvos Model Context Protocol (MCP) Server 2.2.0

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 AI Space through standardized MCP communication.

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

  • Standard Input/Output (STDIO)

• Remote Mode

  • Streamable HTTP

  • Server-Sent Events (SSE)

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:

• Streamable HTTP: The recommended transport for remote integrations. It operates statelessly over HTTP POST to the /mcp endpoint. It also supports Basic and OAuth authorization.

• 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.

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

Open

1. A user poses a natural language (NL) question.

2. The MCP Client uses an LLM to interpret the question and interacts with the MCP Kyvos Server to retrieve relevant answers.

3. 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.

On this page:

• 1 Authentication Support
• 2 Supported Deployment Modes
• 3 MCP Server Tools
• 4 System Requirements
  • 4.1 OS Requirements
  • 4.2 Supported MCP Kyvos Server version with Kyvos version
  • 4.3 Required Software
  • 4.4 Setting Up a Virtual Environment (Recommended)
• 5 Support for No Authentication
  • 5.1 How It Works
  • 5.2 Starting the Server in No-Auth Mode
  • 5.3 When to Use No-Auth
• 6 Support for AI Space 
  • 6.1 Query Parameters
  • 6.2 Sample URL
  • 6.3 Client Configuration Example
  • 6.4 Scoped Querying in STDIO Mode
• 7 Python Requirements
• 8 Installation
• 9 Configuration and Parameters
• 10 Creating .env file
• 11 Usage
  • 11.1 Streamable HTTP
  • 11.2 SSE Mode
  • 11.3 STDIO Mode
• 12 Claude Desktop Usage
  • 12.1 Streamable HTTP Mode Support (Remote)
  • 12.2 Passing Scoped Query Parameters via Headers (Recommended for Claude Desktop)
  • 12.3 Supported Headers
  • 12.4 Configuration Example
• 13 Security and Access Control

The Kyvos MCP Server provides a set of standardized tools accessible to MCP clients. 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: 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: Retrieves column metadata, query generation rules, querying instructions and summary instructions for a specified semantic model.

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

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

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

  1. kyvos_get_aispace: Returns information about the AI Space, including its business context.

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

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.

Linux and macOS

Windows — Command Prompt

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 Personal Access Token.

• The server generates and returns simulated OAuth tokens to the client.

When no authentication 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 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.

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.

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

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

Python >=3.10 is need for Kyvos MCP Server.

Install the mcp-kyvos-server package from pip:

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

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

1. Start the MCP server with streamable-http transport (or omit --transport since it is the default), and do one of the following:

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

   • 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"     }   } }

   1. With scoped query parameters:

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

1. 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

2. 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" } } }

1. Configure your client application. For example:

OR

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

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

1. Install Node.js (v18 or higher) from 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" ] } }}

3. Replace <your-machine-ip> and <port> with the actual address of your Streamable HTTP 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:

4. Delete the .mcp-auth folder.

   • On Linux/macOS:

     ~/.mcp-auth

   • On Windows (Command Prompt):

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

5. Restart the mcp-kyvos-server.

1. 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.

1. Add this to your claude_desktop_config.json:

AI Space Configuration Example

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.