Katonic MCP Server tools
The server exposes 19 tools. Every tool calls the public API with the key you connected with, so the key’s scopes decide what a tool may do, and a tool the key cannot use fails with the gateway’s error in the tool result. Tool names and parameters are what tools/list returns on this build; call it from your client for the list your deployment serves.
Tools
| Tool | What it does |
|---|---|
katonic_chat | Chat with a named Katonic agent. |
katonic_completions | OpenAI-compatible chat completions. |
katonic_knowledge_search | Semantic search across Katonic knowledge sources. |
katonic_create_document | Ingest a document into the Katonic knowledge engine. |
katonic_analyze_data | Analyze structured data or answer BI questions. |
katonic_list_agents | List available Katonic agents visible to the caller. |
katonic_create_agent | Create a new Katonic agent with a name, system prompt, and model tier. |
katonic_update_agent | Update an existing Katonic agent's configuration. |
katonic_create_session | Create a new chat session for multi-turn conversations with an agent. |
katonic_get_history | Get the conversation history for a chat session. |
katonic_list_datasets | List evaluation datasets available to the caller. |
katonic_run_evaluation | Run an evaluation of a Katonic agent and return the score. |
katonic_optimize_prompt | Start automated prompt optimization for an agent. |
katonic_quality_trend | Get the data flywheel quality trend for an agent, average score, p10/p90, regression detection. |
katonic_list_sources | List knowledge sources available in the platform. |
katonic_search_tools | Search the Katonic MCP tool catalog. |
katonic_execute_tool | Execute a specific MCP tool by server and tool name. |
katonic_get_analytics | Get usage and cost analytics for the platform. |
katonic_submit_feedback | Submit feedback (rating + optional comment) on a conversation session. |
katonic_chat
Chat with a named Katonic agent. Returns the agent's response.
| Parameter | Type | Required | Description |
|---|---|---|---|
agent_id | string | Yes | Agent slug or UUID. |
message | string | Yes | User message. |
session_id | string | No | Optional session ID for multi-turn. |
Calls
Notes
- Calls the chat route with the agent, message and optional session, and returns the reply.
katonic_completions
OpenAI-compatible chat completions. Serves the models the administrator has enabled in the gateway catalogue for the caller's organisation.
| Parameter | Type | Required | Description |
|---|---|---|---|
model | string | Yes | Model ID (e.g. gpt-4o-mini, claude-sonnet-4-5). |
messages | array | Yes | Chat messages. |
temperature | number | No | Default 0.7. |
max_tokens | integer | No | Default 4096. |
Calls
Notes
- Calls the chat completions route with the model and messages you pass.
katonic_knowledge_search
Semantic search across Katonic knowledge sources. Returns ranked passages.
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Search query. |
top_k | integer | No | Number of results. Default 5. |
source_ids | array | No | Limit to specific sources. |
Calls
Notes
- Calls the search route. On the current build the source filter is sent under a field name the search route does not read, so results are not limited to the sources you name.
katonic_create_document
Ingest a document into the Katonic knowledge engine. Requires a file_upload knowledge source, get one from katonic_list_sources (connector_type == 'file_upload') and pass its id as source_id.
| Parameter | Type | Required | Description |
|---|---|---|---|
title | string | Yes | No description. |
content | string | Yes | Document text content. |
source_id | string | Yes | File_upload knowledge source id (from katonic_list_sources). |
metadata | object | No | Optional metadata. |
Calls
Notes
- There is no title-and-text ingest route, so the tool uploads the content as a text file to the file-upload source you name, then triggers ingest. Find a source id with the list sources tool.
katonic_analyze_data
Analyze structured data or answer BI questions. Returns analysis and optional chart spec.
| Parameter | Type | Required | Description |
|---|---|---|---|
question | string | Yes | Analysis question. |
data | string | No | CSV or JSON data to analyze. |
output_format | string | No | One of text, json, chart. Default "text". |
Calls
Notes
- Runs as a chat completion with the question and data you pass rather than through a dedicated analysis service.
katonic_list_agents
List available Katonic agents visible to the caller.
| Parameter | Type | Required | Description |
|---|---|---|---|
status | string | No | One of published, draft, all. Default "published". |
tag | string | No | Filter by tag. |
Calls
katonic_create_agent
Create a new Katonic agent with a name, system prompt, and model tier.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Agent display name. |
system_prompt | string | No | System prompt for the agent. |
description | string | No | Agent description. |
model_tier | string | No | One of fast, balanced, powerful, economy. Default "balanced". |
tags | array | No | Tags. |
Calls
katonic_update_agent
Update an existing Katonic agent's configuration.
| Parameter | Type | Required | Description |
|---|---|---|---|
agent_id | string | Yes | Agent ID to update. |
system_prompt | string | No | New system prompt. |
description | string | No | New description. |
model_tier | string | No | One of fast, balanced, powerful, economy. |
Calls
katonic_create_session
Create a new chat session for multi-turn conversations with an agent.
| Parameter | Type | Required | Description |
|---|---|---|---|
agent_id | string | Yes | Agent to create session for. |
Calls
katonic_get_history
Get the conversation history for a chat session.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | Session ID. |
Calls
katonic_list_datasets
List evaluation datasets available to the caller. Use this to obtain a dataset_id for katonic_run_evaluation or katonic_optimize_prompt.
No parameters.
Calls
katonic_run_evaluation
Run an evaluation of a Katonic agent and return the score. Get dataset_id from katonic_list_datasets.
| Parameter | Type | Required | Description |
|---|---|---|---|
agent_id | string | Yes | No description. |
dataset_id | string | Yes | Eval dataset ID. |
evaluator_ids | array | No | No description. |
wait | boolean | No | Wait for completion. Default true. |
Calls
Notes
- With wait true, the default, the tool polls the run every five seconds for up to five minutes and returns the finished run, or a timeout error carrying the run id.
katonic_optimize_prompt
Start automated prompt optimization for an agent. Uses eval feedback loop to improve the system prompt. Get dataset_id from katonic_list_datasets.
| Parameter | Type | Required | Description |
|---|---|---|---|
agent_id | string | Yes | Agent to optimize. |
dataset_id | string | Yes | Eval dataset for scoring. |
evaluator_ids | array | No | Evaluators to use. |
max_iterations | integer | No | Max optimization iterations. Default 3. |
auto_publish | boolean | No | Auto-publish best result. Default false. |
wait | boolean | No | Wait for completion. Default true. |
Calls
Notes
- With wait true, the default, the tool polls the job every ten seconds for up to ten minutes and returns the finished job, or a timeout error carrying the job id.
katonic_quality_trend
Get the data flywheel quality trend for an agent, average score, p10/p90, regression detection.
| Parameter | Type | Required | Description |
|---|---|---|---|
agent_id | string | Yes | Agent to check quality for. |
Calls
katonic_list_sources
List knowledge sources available in the platform.
No parameters.
Calls
katonic_search_tools
Search the Katonic MCP tool catalog.
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | No description. |
category | string | No | No description. |
Calls
Notes
- Lists the tenant’s tools and filters them by your query on the client side; each result also carries a server_id you can pass straight to the execute tool.
katonic_execute_tool
Execute a specific MCP tool by server and tool name. Discover both via katonic_search_tools: pass its 'server_id' (== the catalog 'mcpId') and 'name' fields here.
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | MCP server id, the 'server_id'/'mcpId' from katonic_search_tools. |
tool_name | string | Yes | The tool 'name' from katonic_search_tools. |
arguments | object | No | No description. |
Calls
Notes
- Both server_id and tool_name are required; the tool returns a clear error rather than failing when one is missing.
katonic_get_analytics
Get usage and cost analytics for the platform.
| Parameter | Type | Required | Description |
|---|---|---|---|
type | string | No | Analytics type. One of usage, cost. Default "usage". |
Calls
Notes
- type cost reads the cost breakdown; anything else reads the usage summary.
katonic_submit_feedback
Submit feedback (rating + optional comment) on a conversation session.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | Session to rate. |
rating | integer | Yes | Rating 1-5. |
comment | string | No | Optional comment. |
Calls