mcp-kyvos-sample-client 1.0.0a3

MCP Kyvos Sample Client

The mcp-kyvos-sample-client is a sample client implementation that demonstrates how to interact with a Kyvos MCP server. It enables users to send natural language queries using either:

• SSE (Server-Sent Events) for web-based communication, or
• STDIO for command-line interaction.

The client supports both Basic Authentication and OAuth 2.0, with credentials and the Kyvos platform URL specified through a JSON configuration file. It uses Azure OpenAI as the LLM backend.

Installation

Install the MCP Kyvos sample client package from pip:

pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple mcp-kyvos-sample-client==1.7

---

Configuration Overview

The client configuration is defined in a JSON file (e.g., mcp.json) or via environment files. There are two primary properties:

1. clientConfiguration
2. mcpServers

{
  "clientConfiguration": {
    "AZURE_OPENAI_API_KEY": "your-azure-openai-api-key-here",
    "AZURE_OPENAI_ENDPOINT": "https://your-resource-name.openai.azure.com/",
    "AZURE_OPENAI_DEPLOYMENT_NAME": "your-deployment-name",
    "AZURE_OPENAI_API_VERSION": "2025-01-01-preview",
    "AUTH_TYPE": "basic"
  },
  "mcpServers": {
    "my-stdio-server": {
      "type": "stdio",
      "command": "mcp-kyvos-server",
      "args": [
        "--env-file", "/path/to/.env"
      ]
    }
  }
}

Client Credentials

These settings apply globally to the MCP client and control logging and authentication to Azure OpenAI:

Parameter	Description	Example	Required	Default value
log_level	Log level. Options: DEBUG (default), INFO	"INFO"	No	"DEBUG"
log_file	File path for client logs.	"/var/log/mcp/client.log"	No	-
AZURE_OPENAI_API_KEY	API key for Azure OpenAI.	"abc123..."	Yes	-
AZURE_OPENAI_ENDPOINT	Azure OpenAI resource endpoint URL.	"https://your-resource.openai.azure.com/"	Yes	-
AZURE_OPENAI_DEPLOYMENT_NAME	Name of the Azure OpenAI model deployment to use.	"your-deployment-name"	Yes	-
AZURE_OPENAI_API_VERSION	Azure OpenAI API version.	"2025-01-01-preview"	No	"2025-01-01-preview"
AUTH_TYPE	Type of authorization the client uses.	basic or oauth	No	oauth
CLIENT_PORT	The port on which the client receives the OAuth callback from the server.	3001	No	3000
FOLDER_NAME	Folder name to use for getting available semantic models.	"Business Catalog"	No	-

Example:

"clientConfiguration": {
  "LOG_LEVEL": "INFO",
  "LOG_FILE": "/var/log/mcp/client.log",
  "AZURE_OPENAI_API_KEY": "your-azure-openai-api-key-here",
  "AZURE_OPENAI_ENDPOINT": "https://your-resource-name.openai.azure.com/",
  "AZURE_OPENAI_DEPLOYMENT_NAME": "your-deployment-name",
  "AZURE_OPENAI_API_VERSION": "2025-01-01-preview",
  "FOLDER_NAME": "Business_Catalog"
}

---

STDIO Mode

Runs synchronously over standard input/output, ideal for scripts and pipelines.

Connect with stdio:

Field	Description	Examples	Required
type	Server connection type.	"stdio" or "sse"	No
command	The command used to start the server executable. Must be an absolute path or available on the system PATH.	"uv", "python", or any command installed via pip.	Yes
args	Array of arguments passed to the command.	["--kyvos-url", "https://your-kyvos-endpoint", "--verify-ssl", "false"]	Yes
env	Environment variables for the server.	"USERNAME": "user123"	No

Example configuration in mcp.json:

{
  "clientConfiguration": {
    "LOG_LEVEL": "INFO",
    "LOG_FILE": "/var/log/mcp/analytics-stdio.log",
    "AZURE_OPENAI_API_KEY": "your-azure-openai-api-key-here",
    "AZURE_OPENAI_ENDPOINT": "https://your-resource-name.openai.azure.com/",
    "AZURE_OPENAI_DEPLOYMENT_NAME": "your-deployment-name",
    "AZURE_OPENAI_API_VERSION": "2025-01-01-preview"
  },
  "mcpServers": {
    "my-stdio-server": {
      "type": "stdio",
      "command": "mcp-kyvos-server",
      "args": [
        "--kyvos-url", "https://your-kyvos-endpoint",
        "--kyvos-username", "user123",
        "--kyvos-password", "secret",
        "--kyvos-prompt-file", "./prompt.txt",
        "--kyvos-default-folder", "/shared/folder",
        "--verify-ssl", "false"
      ]
    }
  }
}

Or via environment file:

{
  "clientConfiguration": {
    "AZURE_OPENAI_API_KEY": "your-azure-openai-api-key-here",
    "AZURE_OPENAI_ENDPOINT": "https://your-resource-name.openai.azure.com/",
    "AZURE_OPENAI_DEPLOYMENT_NAME": "your-deployment-name"
  },
  "mcpServers": {
    "my-stdio-server": {
      "type": "stdio",
      "command": "mcp-kyvos-server",
      "args": [
        "--env-file", "/path/to/.env"
      ]
    }
  }
}

Or set env vars:

{
  "clientConfiguration": {
    "AZURE_OPENAI_API_KEY": "your-azure-openai-api-key-here",
    "AZURE_OPENAI_ENDPOINT": "https://your-resource-name.openai.azure.com/",
    "AZURE_OPENAI_DEPLOYMENT_NAME": "your-deployment-name"
  },
  "mcpServers": {
    "my-stdio-server": {
      "type": "stdio",
      "command": "mcp-kyvos-server",
      "args": [],
      "env": {
        "KYVOS_URL": "https://your-kyvos-endpoint",
        "KYVOS_USERNAME": "user123",
        "KYVOS_PASSWORD": "secret"
      }
    }
  }
}

---

SSE Mode

Provides a persistent stream of responses from the MCP Kyvos server using HTTP SSE protocol.

Connect with sse:

Field	Description	Examples	Required
type	Server connection type.	"sse"	No
url	URL of the SSE server.	"http://<machine_ip>:<port>/sse"	Yes
username	Username for HTTP Basic Auth.	"user123"	No
password	Password for HTTP Basic Auth.	"secret"	No

Note: Username and password will be base64 encoded and passed as a Basic Auth token in the Authorization header.

Note: The type parameter is optional. If a url is provided, the client will automatically detect the type as sse; if a command is provided, it will detect stdio mode.

Tip: Ensure that the MCP server is running before starting the client in SSE mode.

{
  "clientConfiguration": {
    "LOG_LEVEL": "DEBUG",
    "LOG_FILE": "/var/log/mcp/analytics-sse.log",
    "AZURE_OPENAI_API_KEY": "your-azure-openai-api-key-here",
    "AZURE_OPENAI_ENDPOINT": "https://your-resource-name.openai.azure.com/",
    "AZURE_OPENAI_DEPLOYMENT_NAME": "your-deployment-name",
    "AZURE_OPENAI_API_VERSION": "2025-01-01-preview"
  },
  "mcpServers": {
    "analytics-sse": {
      "type": "sse",
      "url": "http://<machine_ip>:port/sse",
      "username": "user123",
      "password": "secret"
    }
  }
}

---

For reference on the MCP Kyvos server and its supported command-line arguments, see mcp-kyvos-server.

---

Running the Client

To start the MCP Kyvos sample client using a configuration file, run:

mcp-kyvos-sample-client --config /path/to/mcp.json

---

Note: On error like "Your input exceeds the context window of this model" use the command /clear to reset the context. All previous context will be lost after using this command.

License

This project is licensed under the MIT License.