MCP Server Reference

Kuroco provides two kinds of Model Context Protocol (MCP) servers. This page summarizes the endpoints, authentication methods, and tool structure of each.

Server	Endpoint	Purpose
Client API MCP server	/rcms-api/{id}/mcp	Exposes Client API endpoints as MCP tools.
Admin MCP server	/direct/rcms_api/admin_mcp/	Exposes the same admin operations as the Admin API as MCP tools.

For MCP client setup (Claude Code, Claude Desktop, Cursor, etc.), see the MCP Client Configuration Reference.

Client API MCP server

An MCP server provided per API (e.g. https://{your-site}.g.kuroco.app/rcms-api/{id}/mcp). When you enable the MCP settings (tool name / input schema / status) on an endpoint, that endpoint is published as an MCP tool.

For detailed setup steps, see Model Context Protocol (MCP) Integration with Kuroco.

Authentication

The connection method follows the API's security setting.

API security	Connection method
None	Connect with the MCP server URL only (no authentication).
Static token / privileged static token	Set the token in the X-RCMS-API-ACCESS-TOKEN header. A client that supports header authentication is required.
OAuth (OAuth Authorization Server, usage = API)	Connect with OAuth authentication. Supported by the Claude.ai connector feature and others.

caution

Public endpoints without authentication are not recommended for production use. See the MCP Client Configuration Reference for details.

For the steps to register a Claude.ai connector using OAuth authentication, see How to Register an MCP Connector in Claude.ai.

Admin MCP server

Kuroco exposes the same admin operations as the Admin API as a JSON-RPC 2.0 MCP server, available at /direct/rcms_api/admin_mcp/. MCP-aware clients can register the endpoint directly — no CLI build is required.

Authentication

Authentication mode is selected by the request host:

Host	Mode	Notes
ROOT_MNG_URL	Admin session cookie	Same login flow as the admin UI; restored automatically by direct.php.
ROOT_API_URL	Bearer token (Authorization header)	Accepts OAuth Authorization Server access tokens (target_domain=AdminMCP, audience-bound per RFC 8707) or privileged static tokens (api_id=-1) issued via AdminMCPServer::generateToken() for tools without OAuth handshake support.

401 responses include an RFC 6750 WWW-Authenticate challenge that points to the protected-resource metadata document:

/.well-known/oauth-protected-resource/direct/rcms_api/admin_mcp/

This endpoint is public (no authentication required) and lets MCP clients discover the Authorization Server. It is also reachable via ?MODE=protected_resource_metadata.

Module-scoped MCP servers

Path segments after /admin_mcp/ bundle one or more admin modules into a single MCP server (one credential per agent), modeled on the GitHub MCP /x/<csv>/readonly pattern:

POST /direct/rcms_api/admin_mcp/                                     # All tools (admin/discovery only)
POST /direct/rcms_api/admin_mcp/x/topics_group_1,topics_group_5,member,services
POST /direct/rcms_api/admin_mcp/x/topics_group_1,topics_group_5/readonly
POST /direct/rcms_api/admin_mcp/x/topics_group                       # Group definition CRUD

Recognized CSV entries (same identifiers as t_ai_agent.admin_mcp_modules):

Entry	Meaning
topics_group_<N>	Topics record controllers scoped to topics_group_id = N. The constructor surfaces N in each tool's topics_group_id enum and rejects calls outside the allowed list.
topics	Same as above with no group restriction. Useful only for admin discovery — tool calls are rejected.
topics_group	Group definition management (CRUD on t_topics_group).
services	Service models (Email, Slack, etc.).
<mt>	Any other admin module (member, ec, batch, etc.).

When modules are specified:

• Write controllers are split by MODE (INSERT / UPDATE / DELETE)
• Read controllers are filtered out when the module has zero records
• Only INSERT is shown for empty modules

Appending /readonly to the path removes write tools from the listing.

Module discovery (REST)

GET /direct/rcms_api/admin_mcp/?MODE=tools

Returns:

{
  "modules": [
    {"module": "topics",   "type": "controller", "tool_count": 8},
    {"module": "member",   "type": "controller", "tool_count": 5},
    {"module": "services", "type": "service",    "tool_count": 4}
  ]
}

MCP protocol surface

JSON-RPC 2.0 over HTTP POST. Supported methods:

Method	Description
initialize	Handshake and protocol version negotiation
notifications/initialized	Client ready notification
ping	Connection check
tools/list	List available admin tools (scoped by module)
tools/call	Execute an admin tool by name

Tool naming uses a folded {mt}-{verb} form. Controller suffix + MODE are mapped to a verb (e.g. INSERT → create, _list_api → list):

Surface	Pattern	Example
List controller ({mt}_list_api), no MODE	{mt}-list	topics-list
List controller with MODE	{mt}-{mode}	topics-accept
List controller, bulk MODE (DELETE etc.)	{mt}-bulk_{mode}	topics-bulk_delete
Specialized list ({mt}_{spec}_list_api)	{mt}-{spec}_list	topics-waiting_for_approval_list
Edit controller, INSERT	{mt}-create	topics-create
Edit controller, UPDATE	{mt}-update	topics-update
Edit controller, DELETE	{mt}-delete	topics-delete
Edit controller, VALIDATE	{mt}-validate	topics-validate
Sub-entity controller (e.g. topics_group_edit_api)	{mt}-{sub}-{verb}	topics-group-create
Fetch helper	{mt}-fetch	topics-fetch
Topics-only describe tool	hardcoded	topics-describe
Service method	{mt}-{method}	Email-send

The complete tool list depends on which controllers your modules expose. Issue a JSON-RPC tools/list against the scoped URL to enumerate.

Example call:

POST /direct/rcms_api/admin_mcp/x/topics_group_1
Authorization: Bearer <token>
Content-Type: application/json

{"jsonrpc":"2.0","method":"tools/call",
 "params":{"name":"topics-create",
           "arguments":{"subject":"Hello","topics_group_id":1}},
 "id":3}

Choosing Admin CLI vs Admin MCP

Use case	Recommendation
Local interactive development with admin login	Admin CLI (kuroco-admin)
Claude Code / Claude Desktop with native MCP support	Admin MCP server
CI / unattended agents with rotated tokens	Admin MCP server (privileged static token)
End-user authorization flows (delegated access)	Admin MCP server (OAuth Authorization Server, target_domain=AdminMCP)
Mixed shell scripting and ad-hoc CLI piping	Admin CLI (kuroco-admin)

For details on the Admin CLI (kuroco-admin), see the Kuroco Skills Reference.

Billing applies to both paths

/direct/rcms_api/admin_api/ and /direct/rcms_api/admin_mcp/ are both routed under /direct/ and are billable in Kuroco. Use module-scoped MCP URLs and /readonly whenever possible to limit unintended write traffic.

Client CLI

For CLI-based access to Kuroco Client API, a separate Client CLI (kuroco-client) is also available. See Kuroco AI Architecture for details.

Related documentation

• Model Context Protocol (MCP) Integration with Kuroco - Setup steps for the Client API MCP server
• MCP Client Configuration Reference - Per-client connection setup
• How to Register an MCP Connector in Claude.ai - Connecting with OAuth authentication
• Kuroco Skills Reference - Details on the Admin CLI and Kuroco Skills