# Kdbai Mcp Server

> KDB.AI MCP Server that enables interaction with KDB.AI through natural language

- **Type:** MCP server
- **Install:** `agentstack add mcp-kxsystems-kdbai-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [KxSystems](https://agentstack.voostack.com/s/kxsystems)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [KxSystems](https://github.com/KxSystems)
- **Source:** https://github.com/KxSystems/kdbai-mcp-server

## Install

```sh
agentstack add mcp-kxsystems-kdbai-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://modelcontextprotocol.io/clients) |
| **Linux**      | ✅ Docker  | ✅ Local       | ✅ Local   | ❌ Not supported                 | ✅ [Other clients](https://modelcontextprotocol.io/clients) |
| **WSL**        | ✅ Docker  | ✅ Local       | ✅ Local   | ❌ Not supported                 | ✅ [Other clients](https://modelcontextprotocol.io/clients) |
| **Windows**    | ✅ Docker  | ✅ Local       | ✅ Local   | ✅ Local (streamable-http only)  | ✅ [Other clients](https://modelcontextprotocol.io/clients) |
| **Windows**    | ✅ Docker  | ⚠️ WSL         | ✅ Local   | ✅ Local (streamable-http only)  | ✅ [Other clients](https://modelcontextprotocol.io/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](https://docs.docker.com/desktop/) or [Rancher-Desktop](https://docs.rancherdesktop.io/getting-started/installation)
  - For Windows users we recommend installing Docker desktop using the WSL2 integration [as outlined here](https://docs.docker.com/desktop/features/wsl/)
- [Signed up for KDB.AI](https://docs.kx.com/kdb-ai-latest/KDB_AI/Get_Started/kdb-ai-server-setup.htm#sign-up)
  - Follow the [Server Setup Guide](https://docs.kx.com/kdb-ai-latest/KDB_AI/Get_Started/kdb-ai-server-setup.htm) to get up and running quickly.
  - See supporting [KDB.AI documentation](https://docs.kx.com/kdb-ai-latest/KDB_AI/home.htm) for additional information
- [UV Installed](https://docs.astral.sh/uv/getting-started/installation/) for running the KDB.AI MCP Server - available on Windows/Mac/Linux/WSL
- [Claude Desktop installed](https://claude.ai/download) or another MCP-compatible client, that will connect to the KDB.AI MCP Server - available on Windows/Mac
- [NPX installed](https://nodejs.org/en) - 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](https://nodejs.org/en) 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](https://docs.kx.com/kdb-ai-latest/KDB_AI/Get_Started/kdb-ai-server-setup.htm)

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

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

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

5. [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
   ```

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

7. Create some tables and add some data following the [KDB.AI Quickstart Guide](https://docs.kx.com/kdb-ai-latest/KDB_AI/Get_Started/quick-start.htm)

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

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

10. 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://kdbai_operations_guidance) 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

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

### Run the MCP server

#### Install dependencies

```bash
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

```bash
uv run mcp-server
```

## Transport Options

For more info on the supported transports see official documentation

- [streamable-http](https://modelcontextprotocol.io/docs/concepts/transports#streamable-http)
- [stdio](https://modelcontextprotocol.io/docs/concepts/transports#standard-input%2Foutput-stdio)

> Note: We don't support [sse](https://modelcontextprotocol.io/docs/concepts/transports#server-sent-events-sse-deprecated) 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](https://www.envoyproxy.io/), [nginx](https://nginx.org/)) 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](https://www.digitalocean.com/community/tutorials/how-to-create-a-self-signed-ssl-certificate-for-nginx-in-ubuntu-20-04-1) 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](https://istio.io/) 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](https://www.envoyproxy.io/) or [nginx](https://nginx.org/) 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.

```bash
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](https://github.com/KxSystems)
- **Source:** [KxSystems/kdbai-mcp-server](https://github.com/KxSystems/kdbai-mcp-server)
- **License:** Apache-2.0

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-kxsystems-kdbai-mcp-server
- Seller: https://agentstack.voostack.com/s/kxsystems
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.