MCP server

The MCP server lets an AI agent, such as Claude Code or Codex, work with your chatbot over the Model Context Protocol. The agent can read the usage figures, the feedback and the questions visitors ask most, test a question against the chatbot and see which content it found. With the right access it can also change settings, run quality checks and sync content again.

The endpoint is off until you switch it on, and each agent connects with a token whose scopes say what it may do.

Set it up

  1. In the KimaAI admin, go to Settings → MCP server. You find it on Connections too, as the MCP server card under Plugins and agents.
  2. Under Connection, turn on Enable the MCP endpoint.
  3. Choose the Environment: Production for your live site, Staging for a copy.
  4. Under Access tokens, give the token a Label, such as the agent’s name.
  5. Tick the Scopes the agent needs. read is enough to look and diagnose.
  6. Select Create token, and copy the token at once: it is shown only this one time.
  7. Connect the agent with the command under How to connect, with your token in place of <token>.
The Connection card of the MCP server page
  1. The endpoint’s address, which the agent connects to. The button beside it copies it.
  2. Enable the MCP endpoint: while it is off, the endpoint refuses every request.
  3. Environment: on Production, an agent that embeds content again only does a dry run, unless it asks for production explicitly.
The access tokens of the MCP server page, with two tokens
  1. Label: a name for the token, so you know which agent uses it.
  2. Scopes: what the token allows.
  3. Create token makes the token and shows it once.
  4. Each token with its scopes, when it was created and when an agent last used it. The token itself is never shown again.
  5. Revoke removes a token: the agent that uses it loses access at once.

How it works

The page’s options are saved as soon as you change them; it has no Save button.

OptionWhat it does
Enable the MCP endpointOpens the endpoint to agents with a valid token. While it is off, every request is refused. Off on a new site.
EnvironmentProduction or Staging. On production, an agent that embeds content again only does a dry run, unless it asks for production explicitly. The other tools work the same in both.
LabelThe token’s name in the list of tokens. Without one, the token is called “MCP token”.
ScopesWhat the token allows, below.

A token has one or more scopes:

ScopeWhat the agent may do
readLook and diagnose: usage, feedback, the questions visitors ask, conversations with personal data masked, retrieval tests.
read:rawRead conversations without masking, personal data included.
writeChange settings, add and run quality checks, sync content again.
adminEverything above.
  • write and read:raw include read. An agent sees only the tools its token’s scopes allow.
  • A setting changed through update_settings is shown first as a preview; the agent applies it in a second step and can roll it back.
  • Tokens are stored as a salted hash, so even someone who reads your database cannot use them. A token acts as the administrator who created it, and stops working when that user loses the kimaai_mcp capability, which administrators get by default.
  • Instead of a token, an agent can connect with a WordPress Application Password (Users → Profile) and Basic authentication. An administrator connected this way has every scope.
  • Tokens can also be created, listed and revoked with WP-CLI (see WP-CLI commands).
  • Every tool an agent calls is written to the MCP audit log, with the token’s label.

The tools, their scopes and their arguments are listed in the MCP tools reference.

Troubleshooting

  • The agent gets “The MCP endpoint is disabled.” Turn on Enable the MCP endpoint.
  • The agent cannot authenticate. Check that the token was copied whole, that it was not revoked, and that it is sent as Authorization: Bearer <token>. If you lost the token, revoke it and create a new one.
  • A yellow note says your account does not hold the MCP capability. Your user lacks kimaai_mcp, so tokens you create do not work. Ask an administrator to grant it.
  • The agent cannot change anything. Its token has only read. Create one with write.

What are your feelings