# Katonic MCP Server tools

The 19 tools the Katonic MCP Server exposes, with their parameters, what each one calls on the public API and how long-running tools behave.

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`](#katonic-chat) | Chat with a named Katonic agent. |
| [`katonic_completions`](#katonic-completions) | OpenAI-compatible chat completions. |
| [`katonic_knowledge_search`](#katonic-knowledge-search) | Semantic search across Katonic knowledge sources. |
| [`katonic_create_document`](#katonic-create-document) | Ingest a document into the Katonic knowledge engine. |
| [`katonic_analyze_data`](#katonic-analyze-data) | Analyze structured data or answer BI questions. |
| [`katonic_list_agents`](#katonic-list-agents) | List available Katonic agents visible to the caller. |
| [`katonic_create_agent`](#katonic-create-agent) | Create a new Katonic agent with a name, system prompt, and model tier. |
| [`katonic_update_agent`](#katonic-update-agent) | Update an existing Katonic agent's configuration. |
| [`katonic_create_session`](#katonic-create-session) | Create a new chat session for multi-turn conversations with an agent. |
| [`katonic_get_history`](#katonic-get-history) | Get the conversation history for a chat session. |
| [`katonic_list_datasets`](#katonic-list-datasets) | List evaluation datasets available to the caller. |
| [`katonic_run_evaluation`](#katonic-run-evaluation) | Run an evaluation of a Katonic agent and return the score. |
| [`katonic_optimize_prompt`](#katonic-optimize-prompt) | Start automated prompt optimization for an agent. |
| [`katonic_quality_trend`](#katonic-quality-trend) | Get the data flywheel quality trend for an agent, average score, p10/p90, regression detection. |
| [`katonic_list_sources`](#katonic-list-sources) | List knowledge sources available in the platform. |
| [`katonic_search_tools`](#katonic-search-tools) | Search the Katonic MCP tool catalog. |
| [`katonic_execute_tool`](#katonic-execute-tool) | Execute a specific MCP tool by server and tool name. |
| [`katonic_get_analytics`](#katonic-get-analytics) | Get usage and cost analytics for the platform. |
| [`katonic_submit_feedback`](#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**

- POST `/public/v1/chat`

**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**

- POST `/public/v1/chat/completions`

**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**

- POST `/public/v1/search`

**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**

- POST `/public/v1/sources/{source_id}/upload`
- POST `/public/v1/sources/{source_id}/ingest`

**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**

- POST `/public/v1/chat/completions`

**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**

- GET `/public/v1/agents`

## `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**

- POST `/public/v1/agents`

## `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**

- PATCH `/public/v1/agents/{agent_id}`

## `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**

- POST `/public/v1/sessions`

## `katonic_get_history` 

Get the conversation history for a chat session.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `session_id` | string | Yes | Session ID. |

**Calls**

- GET `/public/v1/sessions/{session_id}/history`

## `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**

- GET `/public/v1/datasets`

## `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**

- POST `/public/v1/evaluations`
- GET `/public/v1/evaluations/{run_id}`

**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**

- POST `/public/v1/optimize`
- GET `/public/v1/optimize/{job_id}`

**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**

- GET `/public/v1/flywheel/{agent_id}/trend`

## `katonic_list_sources` 

List knowledge sources available in the platform.

No parameters.

**Calls**

- GET `/public/v1/sources`

## `katonic_search_tools` 

Search the Katonic MCP tool catalog.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | Yes | No description. |
| `category` | string | No | No description. |

**Calls**

- GET `/public/v1/tools`

**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**

- POST `/public/v1/tools/execute`

**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**

- GET `/public/v1/analytics/cost`
- GET `/public/v1/analytics/usage`

**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**

- POST `/public/v1/feedback`

## Related

- [Katonic MCP Server](/developers/libraries/mcp-server)
- [Connect a client](/developers/libraries/mcp-server/connect)
- Public API reference

Source: https://docs.katonic.ai/developers/libraries/mcp-server/tools
