Natural Language Interaction via Model Context Protocol (MCP) - BETA¶

This page describes how the MCP Server connects kdb Insights Enterprise to MCP clients, and how to enable the server and configure each supported client.

Overview¶

The MCP Server integration connects kdb Insights Enterprise to any client that supports Model Context Protocol (MCP). This setup lets both users and AI models interact with kdb Insights Enterprise using natural language through AI-powered applications such as Claude Code, Claude Desktop, and Codex.

The following functional areas are supported, with more to come:

How it works¶

You submit a natural language request through an MCP client application. The LLM determines which tools, prompts, or resources to invoke. The selected action passes to the MCP Server running in your kdb Insights Enterprise deployment, which routes the call to the relevant service and returns a structured result.

Compatibility¶

The MCP Server is compatible with kdb Insights Enterprise 1.20 and later.

The following MCP clients are supported:

Claude Code
Claude Desktop
Codex CLI
Codex Desktop

Note

Codex's OAuth support has a known bug, so use Codex CLI version 0.141.0 or earlier.

Prerequisites¶

Before you configure an MCP client, make sure that you meet the following requirements:

The MCP Server is enabled in your deployment, as described in Enable the MCP Server.
You have a user account for kdb Insights Enterprise and can reach the deployment in a browser.

Enable the MCP Server¶

The MCP Server is disabled by default. To deploy an MCP server as part of the base deployment, add the following to your values.yaml file, as described in the Install configuration guide.

global:
  kxi-mcp: 
    enabled: true

Configure your MCP client¶

The MCP endpoint is https://<INSIGHTS URL>/mcp, where <INSIGHTS URL> is the hostname of your kdb Insights Enterprise deployment. All clients authenticate against this endpoint with OAuth using the pre-registered insights-app client, which is managed by the Keycloak instance in your deployment.

To use the feature, connect with one of the following supported MCP clients.

Claude Code¶

Add the MCP server:
```
claude mcp add --transport http --client-id insights-app kxi https://<INSIGHTS URL>/mcp
```
The --client-id flag is required because the endpoint does not support OAuth dynamic client registration.
Authenticate:
```
claude mcp login kxi
```
A browser opens with the kdb Insights Enterprise login page.

On a remote or headless machine, use claude mcp login kxi --no-browser to print the authorization URL instead, then paste the redirect URL back at the prompt.
Enter your credentials and log in.
Check that a success landing page appears and that Claude Code logs a successful authentication.
Confirm that the server is connected:
```
claude mcp get kxi
```
The command reports ✔ Connected. You can also run the /mcp command inside a Claude Code session to see the server status and its available tools.

Note

You can skip the claude mcp login step and run the /mcp command inside a Claude Code session instead, which starts the same browser login flow.

Claude Desktop¶

Configure Claude Desktop by editing its configuration file.

Create a file called kxi-oauth-client.json with the contents:
```
{"client_id":"insights-app"}
```
Note the absolute path to this file; the following steps refer to it as <PATH>.

Go to Developer → Edit Config and add the following mcpServers entry to the top-level object of claude_desktop_config.json:

{
  "mcpServers": {
    "kxi": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://<INSIGHTS URL>/mcp",
        "--static-oauth-client-info",
        "@<PATH>/kxi-oauth-client.json"
      ]
    }
  }
}

If the file already contains other servers under mcpServers, add the kxi entry alongside them rather than replacing the block.

Fully restart the application.

A browser opens with the kdb Insights Enterprise login page.
Enter your credentials and log in.
Return to Claude Desktop.
Check that kxi appears under + → Connectors in the chat window.

Note

The @ prefix on @<PATH>/kxi-oauth-client.json tells mcp-remote to read the client information from a file rather than parse the argument as inline JSON. Use an absolute path, and on Windows use forward slashes or escaped backslashes so the value remains valid JSON.

Codex CLI¶

Add the MCP server with Codex:

codex mcp add kxi --url https://<INSIGHTS URL>/mcp --oauth-client-id=insights-app

Log in with Codex:
```
codex mcp login kxi
```
A browser opens with the kdb Insights Enterprise login page.
Enter your credentials and log in.
Check that a success landing page appears and that Codex logs a successful authentication.
Run Codex and check the status with the /mcp command.

Codex Desktop¶

Configure Codex Desktop using either the settings panel or its configuration file.

Using the settings panel¶

Create a file called kxi-oauth-client.json with the contents:
```
{"client_id":"insights-app"}
```
Note the absolute path to this file; the following steps refer to it as <PATH>.
Go to Settings → Integrations → Plugins → MCPs → Add → Add MCP server.
Enter a name.
Set Command to launch to npx.
Add the following arguments, one per cell:
- mcp-remote
- https://<INSIGHTS URL>/mcp
- --static-oauth-client-info
- @<PATH>/kxi-oauth-client.json
Click Save.

Using configuration¶

Create a kxi-oauth-client.json file, as described in step 1 of Using the settings panel.
Open ~/.codex/config.toml.

Add the following lines:

[mcp_servers.<NAME>]
command = "npx"
args = ["mcp-remote", "https://<INSIGHTS URL>/mcp", "--static-oauth-client-info", "@<PATH>/kxi-oauth-client.json"]

Example use case: deploy and inspect a package¶

This example shows how a single session moves from finding a package to querying the data it produces, without switching tools or writing any code. Each step is a natural language request, which the MCP Server routes to the package manager, the monitoring service, or the query service as required.

The example package is called sp-py-eg and contains two stream processor pipelines and a database. Substitute your own package name as you follow along.

Find the package:
```
Show me any packages with sp-py in the name
```
The response lists each version that has been pushed, with its size and the user who deployed it.
Check whether it is running:
```
Is it deployed?
```
The response confirms that the versions exist in the package manager but that none of them are currently deployed.
Deploy it:
```
Let's deploy it
```
Because several versions are available, you are asked which one to use before anything is deployed. Once you confirm, the response lists the components that are initializing and flags any non-fatal warnings, such as tables that do not set attrDisk or attrOrd.
Check the status and logs:
```
Let's check the status. Are there any logs we should look at?
```
The response reports the state of each pod, including the aggregator, resource coordinator, storage manager, data access, and sequencer, together with a summary of recent log activity and any restarts.
Wait for the deployment to settle:
```
Keep checking until everything is in a healthy state
```
Status is re-checked until every component reports as running, which distinguishes a deployment that is still starting up from one that is genuinely failing.
Find tables that hold data:
```
Are there any tables associated with that package that have data we could query?
```
The response lists the tables registered by the package, identifies which of them contain rows, and returns a sample of the data with its columns.
Run a user-defined analytic (UDA):
```
Are there any UDAs associated with that package?
Run it with today's date as the start date
```
The response lists the UDAs labeled to the package, then runs the one you choose and returns the aggregated result.
Inspect what the pipeline is doing:
```
Show me the code running in the pipeline
```
The response returns the source of the pipeline and explains how it produces the data you just queried.

Note

Where a request is ambiguous, you are asked to choose before anything changes. In the example above, several versions of the package have been pushed, so the version to deploy is confirmed with you before the deployment starts.

Troubleshooting¶

Incompatible auth server: does not support dynamic client registration¶

The client attempted to register itself with the authorization server automatically. Supply the pre-registered client ID instead: pass --client-id insights-app to claude mcp add, or reference kxi-oauth-client.json through --static-oauth-client-info for the desktop clients.

Redirect URI mismatch¶

The OAuth client requires a redirect URI that was registered in advance. Add --callback-port <PORT> to the claude mcp add command and register http://localhost:<PORT>/callback as a redirect URI on the insights-app client.

Server shows Needs authentication¶

The server configuration was saved, but the OAuth flow has not completed. Run claude mcp login kxi, or run the /mcp command inside a session and log in. To start again from a clean state, run claude mcp logout kxi first.