KimaAI Pro’s MCP server lets an AI client, such as Claude, read how the chatbot does and fix it: POST /wp-json/kimaai/v1/mcp (see the MCP REST routes). An administrator switches it on in KimaAI’s MCP settings and issues a token there or with wp kimaai mcp token create.
A tool needs a scope. A token holds one or more: read reads figures and conversations with personal data masked, read:raw reads them unmasked, write changes settings, eval cases and the index, admin holds all of them; write and read:raw include read. A client sees only the tools its token’s scopes allow. Each call is written to the MCP audit log.
usage_stats
- Scope: read
- Tier: premium
Token usage of the chatbot per day (input, output, total and calls) over the last days, and the current month’s total.
| Argument | Type | Required | Description |
|---|---|---|---|
days | integer | no | Number of days to report (default 30). |
knowledge_gaps
- Scope: read
- Tier: premium
The questions visitors asked recently, in clusters, ranked by negative feedback and then by volume: what visitors ask most and where the chatbot struggles. Eval sessions are left out.
| Argument | Type | Required | Description |
|---|---|---|---|
days | integer | no | Look back this many days (default 30). |
min_cluster | integer | no | Minimum cluster size to report (default 2). |
feedback_overview
- Scope: read
- Tier: premium
The feedback figures of a period: helpful and not helpful answers and their rate, the trend per day, and the answers rated down most.
| Argument | Type | Required | Description |
|---|---|---|---|
range | integer | no | Days to include (default 30). Ignored if from/to are given. |
from | string | no | Start date (YYYY-MM-DD), optional. |
to | string | no | End date (YYYY-MM-DD), optional. |
list_conversations
- Scope: read
- Tier: premium
One page of rated answers with their conversation, filtered by rating, comment, provider, model or post. Personal data in the conversations is masked unless the token has read:raw.
| Argument | Type | Required | Description |
|---|---|---|---|
range | integer | no | Days to include (default 30). |
from | string | no | Start date (YYYY-MM-DD), optional. |
to | string | no | End date (YYYY-MM-DD), optional. |
page | integer | no | Page number (default 1). |
per_page | integer | no | Rows per page (10-100, default 25). |
rating | integer | no | Filter by rating: 1 (up), -1 (down), 0 (all). |
has_comment | integer | no | 1 to only include rows with a comment. |
provider | string | no | Filter by AI provider slug. |
model | string | no | Filter by AI model. |
post_id | integer | no | Filter by originating post ID. |
get_incident
- Scope: read
- Tier: premium
The conversation around one rated answer, three turns before and after, with how the answer was found. Masked unless the token has read:raw.
| Argument | Type | Required | Description |
|---|---|---|---|
session_id | string | yes | The chatbot session ID. |
message_id | string | yes | The rated message ID. |
eval_history
- Scope: read
- Tier: premium
The stored eval runs with their scores, to see whether the answers get better.
| Argument | Type | Required | Description |
|---|---|---|---|
limit | integer | no | Return only the most recent N runs (default all, max 30). |
ask_chatbot
- Scope: read
- Tier: premium
Asks the chatbot a question through the real pipeline and returns its answer and the tools it called, to reproduce a reported bad answer. It runs in an internal session that the analytics leave out, and it calls the AI provider.
| Argument | Type | Required | Description |
|---|---|---|---|
message | string | yes | The user question to ask. |
lang | string | no | Language code (e.g. “de”). Recommended: retrieval and tools are language-scoped. |
post_id | integer | no | Originating post ID for page-aware answers (optional). |
inspect_retrieval
- Scope: read
- Tier: premium
Runs the chatbot’s knowledge search for a query and returns the hits with their similarity, the condensed query, the scope (language, post types) and the search’s settings.
| Argument | Type | Required | Description |
|---|---|---|---|
query | string | yes | The query to retrieve for. |
lang | string | no | Language code (e.g. “de”) for language-scoped retrieval. |
diagnose_query
- Scope: read
- Tier: premium
Searches the knowledge for a query and tells what most likely went wrong (content missing, weak or different wording, or content found so the routing needs a look), with a suggested fix.
| Argument | Type | Required | Description |
|---|---|---|---|
query | string | yes | The user query that produced a bad answer. |
lang | string | no | Language code (e.g. “de”). |
check_coverage
- Scope: read
- Tier: premium
Checks an embedding environment’s health and settings and, for a post, how many of its chunks are in the index.
| Argument | Type | Required | Description |
|---|---|---|---|
env | string | no | Embedding environment id (default “default”). |
post_id | integer | no | If set, report how many chunks of this post are embedded. |
get_settings
- Scope: read
- Tier: premium
Lists the settings update_settings can change, with their current values; secrets are masked.
| Argument | Type | Required | Description |
|---|---|---|---|
prefix | string | no | Only paths starting with this (e.g. “chatbot.settings”). Default “chatbot”. |
query | string | no | Only paths/labels containing this substring. |
update_settings
- Scope: write
- Tier: premium
Changes settings by their path. It shows a preview unless confirm is true; an applied change returns a rollbackSessionId for rollback_change.
| Argument | Type | Required | Description |
|---|---|---|---|
operations | array | yes | List of {path, value} or {path, textEdit} operations. |
confirm | boolean | no | Apply the change (default false = preview only). |
rollback_change
- Scope: write
- Tier: premium
Undoes the settings changes made under a rollbackSessionId.
| Argument | Type | Required | Description |
|---|---|---|---|
rollbackSessionId | string | yes | The session id to revert. |
run_eval
- Scope: write
- Tier: premium
Runs the stored eval cases through the chatbot and returns how many passed; the run is stored in the eval history. Each case calls the AI provider.
| Argument | Type | Required | Description |
|---|---|---|---|
only | string | no | Only run cases in this category. |
limit | integer | no | Maximum number of cases to run. |
lang | string | no | Language code for the chatbot requests (e.g. “de”). |
judge | boolean | no | Also run the LLM judge (slower). |
reembed
- Scope: write
- Tier: premium
Embeds content again to fix missing or stale knowledge: one post, a post type, or modified content. A dry run unless confirm is true; on a site whose MCP environment is production it writes only with allow_production too.
| Argument | Type | Required | Description |
|---|---|---|---|
post_id | integer | no | Embed just this post. |
post_type | string | no | Embed this post type. |
force | boolean | no | Re-embed even if unchanged. |
limit | integer | no | Maximum posts to process (default 50). |
env | string | no | Embedding environment id (default “default”). |
confirm | boolean | no | Actually write vectors (default false = dry run). |
allow_production | boolean | no | Required to write vectors when the environment is production; ignored on staging. Without it a confirmed run on production is forced back to a dry run. |
add_eval_case
- Scope: write
- Tier: premium
Adds an eval case that locks in a fix: a question with what the answer must and must not contain. Returns a rollbackSessionId; run run_eval afterwards.
| Argument | Type | Required | Description | |
|---|---|---|---|---|
caseId | string | yes | Unique case id. | |
turns | array | yes | Conversation turns (usually one user question). | |
category | string | no | Category (default “general”). | |
mustInclude | array | no | Assertions the answer must contain (use “a | b” for any-of). |
mustNotInclude | array | no | Strings the answer must not contain. | |
expectedFacts | string | no | Free-text expected facts (for the judge). |