Skip to main content

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​

ToolWhat it does
katonic_chatChat with a named Katonic agent.
katonic_completionsOpenAI-compatible chat completions.
katonic_knowledge_searchSemantic search across Katonic knowledge sources.
katonic_create_documentIngest a document into the Katonic knowledge engine.
katonic_analyze_dataAnalyze structured data or answer BI questions.
katonic_list_agentsList available Katonic agents visible to the caller.
katonic_create_agentCreate a new Katonic agent with a name, system prompt, and model tier.
katonic_update_agentUpdate an existing Katonic agent's configuration.
katonic_create_sessionCreate a new chat session for multi-turn conversations with an agent.
katonic_get_historyGet the conversation history for a chat session.
katonic_list_datasetsList evaluation datasets available to the caller.
katonic_run_evaluationRun an evaluation of a Katonic agent and return the score.
katonic_optimize_promptStart automated prompt optimization for an agent.
katonic_quality_trendGet the data flywheel quality trend for an agent, average score, p10/p90, regression detection.
katonic_list_sourcesList knowledge sources available in the platform.
katonic_search_toolsSearch the Katonic MCP tool catalog.
katonic_execute_toolExecute a specific MCP tool by server and tool name.
katonic_get_analyticsGet usage and cost analytics for the platform.
katonic_submit_feedbackSubmit feedback (rating + optional comment) on a conversation session.

katonic_chat​

Chat with a named Katonic agent. Returns the agent's response.

ParameterTypeRequiredDescription
agent_idstringYesAgent slug or UUID.
messagestringYesUser message.
session_idstringNoOptional 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.

ParameterTypeRequiredDescription
modelstringYesModel ID (e.g. gpt-4o-mini, claude-sonnet-4-5).
messagesarrayYesChat messages.
temperaturenumberNoDefault 0.7.
max_tokensintegerNoDefault 4096.

Calls

Notes

  • Calls the chat completions route with the model and messages you pass.

Semantic search across Katonic knowledge sources. Returns ranked passages.

ParameterTypeRequiredDescription
querystringYesSearch query.
top_kintegerNoNumber of results. Default 5.
source_idsarrayNoLimit 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.

ParameterTypeRequiredDescription
titlestringYesNo description.
contentstringYesDocument text content.
source_idstringYesFile_upload knowledge source id (from katonic_list_sources).
metadataobjectNoOptional 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.

ParameterTypeRequiredDescription
questionstringYesAnalysis question.
datastringNoCSV or JSON data to analyze.
output_formatstringNoOne 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.

ParameterTypeRequiredDescription
statusstringNoOne of published, draft, all. Default "published".
tagstringNoFilter by tag.

Calls

katonic_create_agent​

Create a new Katonic agent with a name, system prompt, and model tier.

ParameterTypeRequiredDescription
namestringYesAgent display name.
system_promptstringNoSystem prompt for the agent.
descriptionstringNoAgent description.
model_tierstringNoOne of fast, balanced, powerful, economy. Default "balanced".
tagsarrayNoTags.

Calls

katonic_update_agent​

Update an existing Katonic agent's configuration.

ParameterTypeRequiredDescription
agent_idstringYesAgent ID to update.
system_promptstringNoNew system prompt.
descriptionstringNoNew description.
model_tierstringNoOne of fast, balanced, powerful, economy.

Calls

katonic_create_session​

Create a new chat session for multi-turn conversations with an agent.

ParameterTypeRequiredDescription
agent_idstringYesAgent to create session for.

Calls

katonic_get_history​

Get the conversation history for a chat session.

ParameterTypeRequiredDescription
session_idstringYesSession 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.

ParameterTypeRequiredDescription
agent_idstringYesNo description.
dataset_idstringYesEval dataset ID.
evaluator_idsarrayNoNo description.
waitbooleanNoWait 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.

ParameterTypeRequiredDescription
agent_idstringYesAgent to optimize.
dataset_idstringYesEval dataset for scoring.
evaluator_idsarrayNoEvaluators to use.
max_iterationsintegerNoMax optimization iterations. Default 3.
auto_publishbooleanNoAuto-publish best result. Default false.
waitbooleanNoWait 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.

ParameterTypeRequiredDescription
agent_idstringYesAgent 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.

ParameterTypeRequiredDescription
querystringYesNo description.
categorystringNoNo 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.

ParameterTypeRequiredDescription
server_idstringYesMCP server id, the 'server_id'/'mcpId' from katonic_search_tools.
tool_namestringYesThe tool 'name' from katonic_search_tools.
argumentsobjectNoNo 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.

ParameterTypeRequiredDescription
typestringNoAnalytics 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.

ParameterTypeRequiredDescription
session_idstringYesSession to rate.
ratingintegerYesRating 1-5.
commentstringNoOptional comment.

Calls

Describes the platform as of .

Was this page helpful?