Kdbai Mcp Server

KDB.AI MCP Server

A KDB.AI MCP (Model Context Protocol) Server that enables interaction with KDB.AI through natural language for seamless vector database operations, vector similarity searches, hybrid search operations, and advanced data analysis.

Built on an extensible framework with configurable templates, it allows for intuitive extension with custom integrations tailored to your specific vector search and AI-powered data needs. The server leverages a combination of curated resources, intelligent prompts, and robust tools to provide appropriate guidance for AI models interacting with KDB.AI.

Table of Contents

• [Supported Environments](#supported-environments)
• [Prerequisites](#prerequisites)
• [Quickstart](#quickstart)
• [Features](#features)
• [MCP Server Installation](#mcp-server-installation)
• [Security Considerations](#security-considerations)
• [Transport Options](#transport-options)
• [Command Line Tool](#command-line-tool)
• [Configure Embeddings](#configure-embeddings)
• [Usage with Claude Desktop](#usage-with-claude-desktop)
• [Prompts/Resources/Tools](#promptsresourcestools)
• [Development](#development)
• [Testing](#testing)
• [Troubleshooting](#troubleshooting)
• [Useful Resources](#useful-resources)

Supported Environments

The following table shows the install options for supported Operating Systems:

| Primary OS | KDB.AI | MCP Server | UV/NPX | Claude Desktop | Alternative MCP Client | | -------------- | ---------- | -------------- | ---------- | -------------------------------- | ----------------------------------------------------------- | | Mac | ✅ Docker | ✅ Local | ✅ Local | ✅ Local (streamable-http/stdio) | ✅ Other clients | | Linux | ✅ Docker | ✅ Local | ✅ Local | ❌ Not supported | ✅ Other clients | | WSL | ✅ Docker | ✅ Local | ✅ Local | ❌ Not supported | ✅ Other clients | | Windows | ✅ Docker | ✅ Local | ✅ Local | ✅ Local (streamable-http only) | ✅ Other clients | | Windows | ✅ Docker | ⚠️ WSL | ✅ Local | ✅ Local (streamable-http only) | ✅ Other clients |

Prerequisites

Before installing and running the KDB.AI MCP Server, ensure you have:

• [Cloned this repo](#clone-the-repository)
• A suitable container runtime installed - we recommend Docker Desktop or Rancher-Desktop
• For Windows users we recommend installing Docker desktop using the WSL2 integration as outlined here
• Signed up for KDB.AI
• Follow the Server Setup Guide to get up and running quickly.
• See supporting KDB.AI documentation for additional information
• UV Installed for running the KDB.AI MCP Server - available on Windows/Mac/Linux/WSL
• Claude Desktop installed or another MCP-compatible client, that will connect to the KDB.AI MCP Server - available on Windows/Mac
• NPX installed - required to use streamable-http transport with Claude Desktop
• npx may not be required if you are using a different MCP Client - consult the documentation of your chosen MCP Client
• npx comes bundled with the nodejs installer - available on Windows/Mac/Linux/WSL
• See [example configuration with streamable-http](#example-configuration-with-streamable-http)

To simplify getting started we recommend running your MCP Client, KDB.AI MCP server and your KDB.AI database in the same internal Network. See [Security Considerations](#security-considerations) for more information.

Quickstart

To demonstrate basic usage of the KDB.AI MCP Server, using an empty KDB.AI database, follow the quickstart steps below.

> Note: Ensure you have followed the necessary [prerequisites steps](#prerequisites)

1. Start your KDB.AI Server - follow the getting started steps from KDB.AI Server setup guide

1. Test connectivity to the KDB.AI Server

If you have setup KDB.AI Server following step 1, your endpoint will be http://localhost:8082, otherwise update to your configured endpoint.

``bash uv run --with kdbai-client --python=3.12 python -c "import kdbai_client as kx; session = kx.Session(endpoint='http://localhost:8082'); print(session.version())" ``

If you see a response like the below, your KDB.AI Server is configured correctly - please proceed to the next step. If you see different version numbers that's ok.

``python {'serverVersion': 'latest', 'clientMinVersion': '1.7.0', 'clientMaxVersion': 'latest'} ``

If you get error message like Error during creating connection..., this usually indicates that either

• KDB.AI Server is not running
• KDB.AI Server is not accepting connection

See the [troubleshooting](#troubleshooting) section for more details

1. [Configure Claude Desktop](#configure-claude-desktop) with your chosen transport.

1. [Configure Embeddings](#configure-embeddings) with your chosen embeddings provider and model.

1. [Start your MCP server](#mcp-server-installation).

If you have configured Claude Desktop with [stdio transport](#example-configuration-with-stdio), then this step is not required. Please move to the next step (Claude Desktop will manage starting the MCP Server for you).

``bash uv run mcp-server ``

1. Start Claude Desktop and verify that the tools and prompts outlined in the [Validate Claude Desktop Config](#validate-claude-desktop-config) section are visible.

1. Create some tables and add some data following the KDB.AI Quickstart Guide

1. Load [kdbaioperationsguidance](#resources) resource. This will give your MCP client some guidance on how to interact with your KDB.AI database.

1. Try the kdbai_table_analysis prompt and generate an analysis prompt for one of your tables.

1. Ask questions in natural language: Interact with your KDB.AI database using plain English. Your MCP client will use one or more of the [available tools](#tools) to answer your questions.

Features

• Similarity Search: Similarity Search on embedded text within vector database, based on index(s) built at the KDBAI server
• Hybrid Search: Hybrid search on sparse and dense indices built at the KDBAI server
• Customizable Query and Search Result Optimization: Customizable query and search including result truncation (query only), filtering, grouping, aggregation, sorting
• Query Guidance for LLM: Comprehensive LLM-ready MCP resource (file://kdbaioperationsguidance) with syntax examples and best practices
• Database Schema Discovery: Explore and understand your database tables and structure using the included MCP resource for quick, intelligent insights.
• Auto-Discovery System: Automatic discovery and registration of tools, resources, and prompts from their respective directories
• Ready-Made Extension Template: Ready-to-use templates for tools, resources, and prompts with best practices and documentation for extending functionality
• Unified Intelligence: Prompts, Tools & MCP Resources Working Together: A powerful combination of intelligent prompts, purpose-built tools, and curated MCP resources—all working together to deliver fast, optimized, and context-aware results.
• HTTP Streamable Protocol Support: Supports the latest MCP streamable HTTP protocol for efficient data flow, while automatically blocking the deprecated SSE protocol.

MCP Server Installation

Clone the repository

git clone https://github.com/KxSystems/kdbai-mcp-server.git
cd kdbai-mcp-server

Run the MCP server

Install dependencies

uv sync

This step is optional, but can be useful when starting the MCP server for the first time or after adding new dependencies.

If you do not run uv sync first, the MCP client can timeout waiting for the dependencies to be installed.

This can be caused by packages like sentence-transformers with large dependencies.

Run the server

uv run mcp-server

Transport Options

For more info on the supported transports see official documentation

• streamable-http
• stdio

> Note: We don't support sse transport (server-sent events) as it has been deprecated since protocol version 2024-11-05.

Security Considerations

To simplify getting started, we recommend running your MCP Client, KDB.AI MCP server, and your KDB.AI database on the same internal network.

Encrypting Database Connections

If you require an encrypted connection between your KDB.AI MCP server and your KDB.AI database, you can enable the following options:

• QIPC with TLS: Use flag --db.qipc-tls=true
• REST with HTTPS: Use flag --db.rest-protocol=https

Both require setting up a TLS/HTTPS proxy (envoy, nginx) in front of KDB.AI as a prerequisite:

• Since the proxy will terminate TLS connections, we recommend that the proxy runs on the same host as your KDB.AI Server
• The proxy will need its own certificates - If you do not have your own certificates you can create self-signed certificates for internal use. See an example of creating self-signed certificates that can be used with your proxy
• For QIPC connections using self signed certificates:
• You will need to specify the location of your self signed CA cert
• Set KX_SSL_CA_CERT_FILE environment variable to point to the CA cert file that your proxy is using
• Alternatively, you can bypass certificate verification by setting KX_SSL_VERIFY_SERVER=NO for development and testing
• For Kubernetes: Consider using a service mesh like istio for simplified certificate management

Encrypting MCP Client Connections

If you require an encrypted connection between your MCP Client and your KDB.AI MCP server:

• The KDB.AI MCP server uses streamable-http transport by default and starts a localhost server at 127.0.0.1:7000. We do not recommend exposing this externally.
• You can optionally setup an HTTPS proxy in front of your KDB.AI MCP server such as envoy or nginx for HTTPS termination
• FastMCP v2 was evaluated for it's authentication features, but will remain temporarily on v1 to preserve broad model compatibility until clients/models catch up, at which point we’ll transition.
• When using stdio transport, this is not required as communication is through standard input/output streams on the same host

Command Line Tool

The KDB.AI MCP Server provides a detailed help text explaining all configuration options.

uv run mcp-server -h
usage: mcp-server [-h] [--mcp.server-name str] [--mcp.log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
                  [--mcp.transport {stdio,streamable-http}] [--mcp.port int] [--mcp.host str] [--db.host str]
                  [--db.port int] [--db.username str] [--db.password SecretStr] [--db.mode {rest,qipc}]
                  [--db.rest-protocol {http,https}] [--db.qipc-tls bool] [--db.database-name str] [--db.retry int]
                  [--db.k int] [--db.vector-weight float] [--db.sparse-weight float] [--db.embedding-csv-path str]

KDB.AI MCP Server that enables interaction with KDB.AI

options:
  -h, --help            show this help message and exit

mcp options:
  MCP server configuration and transport settings

  --mcp.server-name str
                        Name identifier for the MCP server instance [env: KDBAI_MCP_SERVER_NAME] (default:
                        KDBAI_MCP_Server)
  --mcp.log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
                        Logging verbosity level [env: KDBAI_MCP_LOG_LEVEL] (default: INFO)
  --mcp.transport {stdio,streamable-http}
                        Communication protocol: 'stdio' (pipes) or 'streamable-http' (HTTP server) [env:
                        KDBAI_MCP_TRANSPORT] (default: streamable-http)
  --mcp.port int        HTTP server port - ignored when using stdio transport [env: KDBAI_MCP_PORT] (default: 7000)
  --mcp.host str        HTTP server bind address - ignored when using stdio transport [env: KDBAI_MCP_HOST] (default:
                        127.0.0.1)

db options:
  KDB.AI database connection and search configuration

  --db.host str         KDB.AI server hostname or IP address [env: KDBAI_DB_HOST] (default: 127.0.0.1)
  --db.port int         KDB.AI server port number [env: KDBAI_DB_PORT] (default: 8082)
  --db.username str     Username for KDB.AI authentication [env: KDBAI_DB_USERNAME] (default: )
  --db.password SecretStr
                        Password for KDB.AI authentication [env: KDBAI_DB_PASSWORD] (default: )
  --db.mode {rest,qipc}
                        API mode: 'qipc' (fast binary protocol) or 'rest' (HTTP API) [env: KDBAI_DB_MODE] (default:
                        qipc)
  --db.rest-protocol {http,https}
                        Select protocol for REST mode, not considered for QIPC mode [env: KDBAI_DB_REST_PROTOCOL]
                        (default: http)
  --db.qipc-tls bool    Enable TLS for QIPC mode, not considered for REST mode. When using TLS with QIPC you will need
                        to set the environment variable `KX_SSL_CA_CERT_FILE` that points to the certificate on your
                        local filesystem that your TLS proxy is using. For local development and testing you can set
                        `KX_SSL_VERIFY_SERVER=NO` to bypass this requirement [env: KDBAI_DB_QIPC_TLS] (default: False)
  --db.database-name str
                        Default database name to use for operations [env: KDBAI_DB_DATABASE_NAME] (default: default)
  --db.retry int        Number of connection retry attempts on failure [env: KDBAI_DB_RETRY] (default: 2)
  --db.k int            Default number of results to return from vector searches [env: KDBAI_DB_K] (default: 5)
  --db.vector-weight float
                        Weight for vector similarity in hybrid search (0.0-1.0) [env: KDBAI_DB_VECTOR_WEIGHT]
                        (default: 0.7)
  --db.sparse-weight float
                        Weight for text similarity in hybrid search (0.0-1.0) [env: KDBAI_DB_SPARSE_WEIGHT] (default:
                        0.3)
  --db.embedding-csv-path str
                        Path to embeddings csv [env: KDBAI_DB_EMBEDDING_CSV_PATH] (default:
                        src/mcp_server/utils/embeddings.csv)

CLI Configuration Options

The command line options are organized into two main categories:

• MCP Options - Controls the MCP server behavior and transport settings
• Database Options - Configures KDB.AI database connection and search behavior

For details on each option, refer to the [help text](#command-line-tool)

Configuration Methods

Configuration values are resolved in the following priority orde

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: KxSystems
• Source: KxSystems/kdbai-mcp-server
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.