Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Kinetica MCP Server show me the first 10 records from the customers table"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
This project contains the source code for the Kinetica Model Context Protocol (MCP) server, as well as examples of how to configure and run the server.
The Kinetica MCP server exposes tools and resources for interacting with Kinetica's database, SQL-GPT contexts, and real-time monitoring.
Related MCP server: PlanetScale MCP Server
The MCP server has separate modes depending on how you want the LLM to generate SQL. Each mode contains a different set tools to facilitate the workflow. This functionality is controlled by the environment variable KINETICA_TTS_MODE.
Server-side Inference Mode (KINETICA_TTS_MODE=server)
The LLM will choose a SQL context and use Kinetica's native text-to-sql capabilities via the generate_sql() tool.
This requires that you have appropriate SQL contexts configured in Kinetica.
(see SQL-GPT). Available tools are:
list_sql_contexts
generate_sql
query_sql
describe_table
Local Inference Mode (KINETICA_TTS_MODE=local, default)
The LLM will retrieve table descriptions generate its own SQL. This mode will result in more tokens being consumed from table descriptions but it does not require the use of SQL contexts. Available tools are:
resource sql-context://{context_name}
resource table-monitor://{table}
query_sql
describe_table
start_table_monitor
kinetica_sql_prompt
list_tables
get_records
insert_records
list_tables()
List all available tables, views, and schemas in the Kinetica instance. Results will be filtered by the KINETICA_SCHEMA env variable.
describe_table(table_name: str)
Return a dictionary of column name to column type.
query_sql(sql: str, limit: int = 10)
Run a read-only SQL query on the database, returns results as JSON.
get_records(table_name: str, limit: int = 10)
Fetch raw records from a table as a list of dictionaries.
insert_records(table_name: str, records: list[dict])
Insert a list of records into the specified table.
start_table_monitor(table: str)
Start a real-time monitor for inserts, updates, and deletes on a table.
list_sql_contexts()
List available SQL contexts and their corresponding tables.
generate_sql(context_name: str, question: str)
Generate SQL queries using Kinetica's text-to-SQL capabilities.
sql-context://{context_name}
Return a structured view of a SQL-GPT context, including:
context_name: Fully qualified table name.
tables: Table descriptions containing description, table rules, and column comments.
rules: List of defined semantic rules.
samples: One shot training examples.
The server can optionally be configured to support the OAUTH authorization-code workflow. Common variables are:
KINETICA_URL: The Kinetica API URL (e.g. http://your-kinetica-host:9191)
KINETICA_SCHEMA: Filter tables by schema (optional, default=*)
KINETICA_LOGLEVEL: Server Loglevel (optional, default=warning)
KINETICA_TTS_MODE: Indicates the tex-to-sql mode ( server or local )
See conf_tmpl.sh for an example configuration.
If the MCP will allow access from any user you must specify a username/password that it should use when connecting to Kinetica.
KINETICA_USER: Kientica username
KINETICA_PASSWD: Kinetica password
When OAUTH is enabled users will be redirected to the authentication server where they will enter their Kinetica credentials. The authentication server will then redirected back to the MCP server where they will be given an authentication token. This token can be perpetually cached to avoid the need for future authentications. Additionally the MCP server will authenticate with Kinetica using a handshake key that will allow it to impersonate the authenticated user and their permissions.
To enable this you will need:
An Authentication server capable of providing an Authorization Grant.
The kinetica handshake key.
The required parameters to enable set these variables:
KINETICA_OAUTH_HANDSHAKE_KEY: The unencrypted handshake key. This can be found in httpd/etc/gpudb_httpd.conf.
KINETICA_OAUTH_EXTERNAL_HOST: The external of the MCP and OAUTH servers.
Note: It is recommended that you not use
KINETICA_SCHEMAonly when you are using OAUTH2
In this example we will invoke the uv run command to install the mcp-kinetica package automatically when
Claude desktop starts. For this to work we will use uv to create a virtual environment with python >=3.10 that
will be used by the MCP runtime.
If you have not already downloaded Claude desktop you can get it at https://claude.ai/download.
Note: As an alternative you could install the
mcp-kineticawith pip and avoid using UV but it is recommended in the fastmcp documentation.
Make sure you have UV installed.
pip install --upgrade uv Create the python virtual environment.
You must choose a directory <your_venv_path> for the python runtime.
uv venv --python 3.12 <your_venv_path>Make a note of the python and uv paths.
UV and your VENV could be using different python interpreters. Make a note of these paths and save them for the claude config file.
Note: Windows users should activate with
<your_venv_path>/bin/activate.bat
$ source <your_venv_path>/bin/activate
$ which uv
<uv_exe_path>
$ which python
<python_exe_path>Open your Claude Desktop configuration file:
The app provides a shortcut in Settings->Developer->Edit Config.
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json
Add an mcp-kinetica entry to the mcpServers block:
You will need to edit the <uv_exe_path>, <python_exe_path>, and Kinetica connection info.
{
"mcpServers": {
"mcp-kinetica": {
"command": "<uv_exe_path>",
"args": [
"run",
"--python", "<python_exe_path>",
"--with", "setuptools",
"--with", "mcp-kinetica",
"mcp-kinetica"
],
"env": {
"KINETICA_URL": "<http://your-kinetica-host:9191>",
"KINETICA_USER": "<your_username>",
"KINETICA_PASSWD": "<your_password>",
"KINETICA_LOGLEVEL": "INFO",
"KINETICA_SCHEMA": "*",
"KINETICA_TTS_MODE": "server"
}
}
}
}Restart Claude Desktop to apply the changes.
In Claude Desktop open Settings->Connectors and look for an entry named mcp-kinetica.
The MCP Inspector is a web UI used for exploring the features of an MCP Service and simulating the activities of an LLM model. You will need Node.js >= 18 for the inspector.
Clone the GitHub project:
git clone git@github.com:kineticadb/mcp-kinetica.git
cd mcp-kineticaCreate a .env file in your project root with the following keys:
KINETICA_URL=http://<your-kinetica-host>:9191
KINETICA_USER=<your_username>
KINETICA_PASSWD=<your_password>Update Python environment with uv:
[~/mcp-kinetica]$ pip install uv
[~/mcp-kinetica]$ uv syncActivate Python environment:
Windows:
.venv\Scripts\activate.batLinux:
[~/mcp-kinetica]$ source .venv/bin/activateUse fastmcp dev for an interactive testing environment with the MCP Inspector:
[~/mcp-kinetica]$ fastmcp dev mcp_kinetica/mcp_main.py To create a local package in editable mode:
[~/mcp-kinetica]$ fastmcp dev mcp_kinetica/mcp_main.py --with-editable .Launch MCP Inspector in a browser, pointing at the URL output by the
fastmcp command; for instance http://127.0.0.1:6274, given this output:
Starting MCP inspector...
Proxy server listening on port 6277
MCP Inspector is up and running at http://127.0.0.1:6274Note: MCP inspector will default to
uvas the command to run. If not usinguvfor package management, the MCP Inspector parameters can be updated as follows:
Command:
python3Arguments:
mcp_kinetica/mcp_main.py
This section describes how to run unauthenticated test cases under tests/.
Note: The
uvutility is not required.
Clone the GitHub project:
git clone git@github.com:kineticadb/mcp-kinetica.git
cd mcp-kineticaCreate a .env file in your project root with the following keys:
KINETICA_URL=http://<your-kinetica-host>:9191
KINETICA_USER=<your_username>
KINETICA_PASSWD=<your_password>Install the test dependencies:
[~/mcp-kinetica]$ pip install --group test .Run pytest:
[~/mcp-kinetica]$ pytest -rA
[...]
PASSED tests/test_server_ki.py::test_list_contexts
PASSED tests/test_server_ki.py::test_generate_sql
PASSED tests/test_server_li.py::test_create_test_table
PASSED tests/test_server_li.py::test_list_tables
PASSED tests/test_server_li.py::test_describe_table
PASSED tests/test_server_li.py::test_get_records
PASSED tests/test_server_li.py::test_insert_records
PASSED tests/test_server_li.py::test_query_sql_success
PASSED tests/test_server_li.py::test_query_sql_failure
PASSED tests/test_server_li.py::test_create_context
PASSED tests/test_server_li.py::test_get_sql_context
PASSED tests/test_server_li.py::test_get_promptThe fastmcp library allows for authenticated testing on localhost without the need for SSL. This means we can configure the MCP and auth servers with unencrypted ports and connections from localhost will work.
Configure the auth server to use unencrypted ports. For example:
KINETICA_URL=https://172.31.72.27:8082/gpudb
KINETICA_EXTERNAL_HOST=localhost
KINETICA_MCP_URI=http://localhost:8390
KINETICA_HANDSHAKE_KEY='NDMxMTQ5MjAyNS0wOS0xOCAxMjozMDo1MS40MzExNTc='Start the auth server.
[kinetica-auth/bin]$ ./start_auth.shConfigure the MCP server to use unencrypted ports. For example:
KINETICA_URL=http://172.31.72.27:9191
KINETICA_LOGLEVEL=INFO
KINETICA_OAUTH_URL=http://localhost:8380
KINETICA_OAUTH_HANDSHAKE_KEY='NDMxMTQ5MjAyNS0wOS0xOCAxMjozMDo1MS40MzExNTc='
KINETICA_OAUTH_EXTERNAL_HOST=localhost
KINETICA_OAUTH_BASE_URL=http://localhost:8390Start the MCP server.
[kinetica-mcp/bin]$ ./start_mcp.shRun the authentication test:
Your browser should open to a login page. After logging in with a Kinetica user you will be redirected back to the MCP server.
[kinetica-mcp]$ pytest tests/test_oauth.py::test_query_sql_successFor bugs, please submit an issue on Github.
For support, you can post on
stackoverflow under the
kinetica tag or
Slack.
Ask a question on Slack: Slack
Follow on GitHub: Follow @kineticadb
Email us: support@kinetica.com
Return a dictionary of column name to column type.
| Name | Required | Description | Default |
|---|---|---|---|
| table_name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose all behavioral traits. It only states the return type, omitting side effects (likely none), read-only nature, or error behavior. This is insufficient for safe agent invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that efficiently conveys core functionality. While brief, it avoids unnecessary words, though it could incorporate more detail without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema, the description partly covers return values. However, it lacks critical context about parameter semantics and behavioral constraints, making it inadequate for a tool that likely interacts with an external database.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must clarify the single parameter table_name. It does not specify expected format (e.g., schema-qualified, case sensitivity) or provide any additional context beyond the parameter name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a dictionary of column name to column type, which precisely conveys its purpose. It naturally distinguishes from sibling tools like get_records (data retrieval) and list_tables (listing table names) by focusing on schema introspection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as get_records or query_sql. It does not mention prerequisites (e.g., table must exist) or conditions that affect its use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch raw JSON records from a given table.
| Name | Required | Description | Default |
|---|---|---|---|
| table_name | Yes | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure, but it only states 'Fetch raw JSON records'. It does not mention side effects (likely read-only), pagination, error handling, or any constraints beyond the input schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence of 6 words, avoiding any redundancy. While it is extremely short, it does not contain filler and conveys the core action efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 2 parameters and an output schema, the description is too brief. It omits details about pagination, sorting, error behavior, or the meaning of 'raw'. The presence of an output schema does not fully compensate for missing usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description does not elaborate on the parameters. The phrase 'from a given table' only hints at 'table_name', while 'limit' and its default are completely ignored. The description adds essentially no value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Fetch'), resource ('raw JSON records'), and context ('from a given table'), making the tool's purpose understandable. It is distinct from sibling tools like 'describe_table' or 'insert_records', though it does not explicitly contrast itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'query_sql' or 'list_tables'. The description offers no context about preferred use cases or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Insert records into a specified table.
| Name | Required | Description | Default |
|---|---|---|---|
| table_name | Yes | ||
| records | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for behavioral disclosure. It only states 'insert records,' implying a write operation, but lacks details on atomicity, error handling, permissions, or side effects beyond the core action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence with no unnecessary words. However, its brevity sacrifices important information that could be included in a slightly longer description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 required params, output schema exists) and no annotations, the description is insufficiently complete. It omits details about the output schema, error conditions, and validation, which are needed for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only adds 'into a specified table,' which merely echoes the schema. It does not clarify the format of records, required fields, or constraints beyond what is in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (insert) and the resource (records into a table). It is distinct from sibling tools like describe_table, get_records, list_tables, query_sql, and start_table_monitor, which perform different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, context, or exclusions, leaving the agent without decision-making support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available tables, views, and schemas in the database.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states the basic action and does not disclose behavioral traits such as authentication requirements, read-only nature, or performance implications, which an agent would need for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so return values are documented elsewhere. The description covers the essential action of listing all database objects. For a simple list operation, it is largely complete, though it could mention potential size or security notes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, and schema description coverage is 100%. According to guidelines, baseline score for zero parameters is 4. The description adds no parametric detail but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb 'list' and the resource 'all available tables, views, and schemas in the database.' It distinguishes this tool from siblings like describe_table (which describes a specific table) and query_sql (which runs arbitrary queries).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives like describe_table or query_sql. The context of listing all database objects is implied but lacks explicit exclusions or when-not scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a safe SQL query on the Kinetica database.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must disclose behavior. It claims the query is 'safe' but does not clarify what 'safe' means (e.g., read-only, restricted operations, no side effects). Lacks disclosure about permissions, rate limits, or potential impacts. The term 'safe' is vague and insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, direct and concise. However, it could be restructured to front-load key details about safety or usage. No wasted words, but it sacrifices depth for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description lacks essential context: what 'safe' implies, whether SELECT-only, limit behavior, or execution constraints. For a SQL query tool, this minimal description is incomplete and could lead to misuse.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any parameters. The two parameters ('sql' and 'limit') are not described, leaving the agent to infer meaning from names alone. No additional semantics or constraints are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Run a safe SQL query on the Kinetica database,' specifying the action (run query) and resource (Kinetica database). It distinguishes from sibling tools that describe tables, retrieve records, insert records, list tables, or start monitors, as this is the only tool for arbitrary SQL execution.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus siblings like get_records or describe_table. It does not mention when not to use it or provide any usage context. The description only says 'safe SQL query' without elaborating on scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Starts a table monitor on the given Kinetica table and logs insert/update/delete events.
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description must disclose behavioral traits. It mentions logging events but does not specify if the monitor is persistent, how to stop it, performance implications, or any feedback it provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the purpose. It could be slightly more specific but is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of starting a monitor and the absence of annotations or param details, the description is inadequate. It does not cover return values, side effects, or lifecycle, despite an output schema existing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'table' has no description in the schema (0% coverage) and the description does not clarify expected format, table type, or whether it must be a valid existing table.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Starts' and the resource 'table monitor' on a Kinetica table, with the specific action of logging insert/update/delete events. This distinguishes it from sibling tools which are for querying or listing tables.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like describe_table or insert_records. There are no prerequisites or exclusion criteria mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct operation: schema description, record retrieval, insertion, table listing, SQL queries, and table monitoring. There is no overlap in functionality.
All tool names follow a consistent verb_noun pattern (e.g., describe_table, get_records, list_tables), making them predictable and easy to understand.
With 6 tools, the set is well-scoped for a database interface, covering essential operations without being excessive or sparse.
The tool set provides core CRUD (create via insert, read via get_records and query_sql), schema exploration, and monitoring. Missing update and delete operations, but these may be performed via SQL, making it a minor gap.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
List datasets, schemas, run APL queries, and use prompts for exploration, anomalies, and monitoring.
Public tools to understand Dynamik, discover datasets, and connect account-scoped capabilities.
Gateway between LLM agents and world data through eight tools and a bundled endpoint catalog.
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/kineticadb/mcp-kinetica'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
