---
kind: rest
area: tools-addons
tier: premium
summary: The MCP endpoint that AI clients call with a token, and the admin routes that switch it on and issue tokens.
---

# MCP REST routes

The routes live under `/wp-json/kimaai/v1/`. A call from a logged-in browser sends the WordPress REST nonce, as every WordPress REST call does; a script uses an application password. A route that names a feature is registered only while that feature is not hidden (`app/Features/Features.php`).

Each route says its access. Internal: the route serves KimaAI's own admin screens or chat widget and may change or go away in any release without notice, so code outside KimaAI should not call it. Public: the route keeps its path, its arguments and its answer across releases, and changes only after a deprecation.

The tools the endpoint offers are on the MCP tools page (`docs/reference/mcp-tools.md`). The OAuth endpoints for connectors such as claude.ai (`/.well-known/oauth-*` and `/mcp-oauth/`) are served outside the REST API and are not listed here.

## POST /kimaai/v1/mcp

- Access: public
- Permission: a user with the `kimaai_mcp` capability (administrators get it), by a token from KimaAI, Settings, MCP or `wp kimaai mcp token create`, an OAuth token of a connector, or an application password; the endpoint must be switched on (403 otherwise, 401 without valid credentials)
- Tier: premium
- Feature: none

The MCP server: JSON-RPC 2.0 over HTTP, with the methods `initialize`, `ping`, `tools/list` and `tools/call` and the notifications. `tools/list` offers only the tools the token's scopes allow. A token sends `Authorization: Bearer <token>`; an application password authenticates through WordPress and gets every scope for an administrator, `read` otherwise.

No arguments.

Returns: The JSON-RPC answer; a 401 carries a `WWW-Authenticate` header that points MCP clients to the OAuth metadata.

## GET /kimaai/v1/mcp/admin/overview

- Access: internal
- Permission: an administrator (`manage_options`)
- Tier: premium
- Feature: none

The MCP settings page: whether the endpoint is on, its environment, the scopes, whether the current user may use MCP, and the tokens.

No arguments.

Returns: `settings`, `scopes`, `capabilityOk`, `currentUser` and `tokens` (without their secrets).

## POST /kimaai/v1/mcp/admin/settings

- Access: internal
- Permission: an administrator (`manage_options`)
- Tier: premium
- Feature: none

Switches the MCP endpoint on or off and sets the environment it declares; on production, the `reembed` tool writes only when the call allows it.

| Argument      | Type    | Required | Description                     |
| ------------- | ------- | -------- | ------------------------------- |
| `enabled`     | boolean | yes      | True to switch the endpoint on. |
| `environment` | string  | yes      | `production` or `staging`.      |

Returns: The stored `settings`.

## POST /kimaai/v1/mcp/admin/tokens

- Access: internal
- Permission: an administrator (`manage_options`) who holds the `kimaai_mcp` capability (403 otherwise)
- Tier: premium
- Feature: none

Issues a token for the current user. The token itself is in the answer once and is stored only as a hash.

| Argument | Type   | Required | Description                                                                                      |
| -------- | ------ | -------- | ------------------------------------------------------------------------------------------------ |
| `label`  | string | no       | A name for the token. Default `MCPtoken`.                                                        |
| `scopes` | array  | no       | The scopes: `read`, `read:raw`, `write`, `admin`; `read` when none is valid. Default `["read"]`. |

Returns: Status 201 with `id`, `token`, `scopes` and the `tokens`.

## DELETE /kimaai/v1/mcp/admin/tokens/{id}

- Access: internal
- Permission: an administrator (`manage_options`)
- Tier: premium
- Feature: none

Revokes a token.

| Argument | Type   | Required | Description     |
| -------- | ------ | -------- | --------------- |
| `id`     | string | yes      | The token's ID. |

Returns: `ok` and the `tokens`; 404 for an unknown token.
