Model Context Protocol (MCP) と Kuroco の連携

Kuroco は Model Context Protocol (MCP) を実装しており、LLM クライアントが HTTP 経由で公開 API エンドポイントを呼び出せます。このガイドでは、Kuroco エンドポイントを MCP 経由で公開する方法を 2 つのパートで解説します：

• Kuroco のデータを提供して LLM のレスポンスを充実させる
• LLM を使ってコンテンツを作成・更新する

AI クライアント向けに Kuroco ツールを公開する際の詳細なリファレンスとしてご活用ください。

Kuroco における Model Context Protocol (MCP) とは

MCP は AI クライアントをツールサーバーに接続するためのオープンプロトコルです。Kuroco は MCP サーバーを公開しており、Claude、ChatGPT、IDE アシスタントなどのクライアントが型付きツールとして API を検出し、構造化された入力で呼び出せます。どの API 操作も MCP で公開できます。このドキュメントでは、コンテンツの読み取り・書き込み操作に焦点を当てます。

主な特徴

• HTTP トランスポート: Kuroco の MCP はストリーミング HTTP トランスポートを使用し、MCP 仕様に準拠しています。
• 高度なカスタマイズ性: Kuroco API とカスタム関数を組み合わせて、多様なユースケースに対応したツールを公開できます。
• 既存のエンドポイントで動作: 既存の Kuroco API エンドポイントをそのまま LLM ツールとして公開できます。

制限事項

• 認証: LLM クライアントは公開 API およびアクセストークンで保護されたエンドポイントを利用できますが、すべてのクライアントがヘッダーへのトークン設定をサポートしているわけではありません。各クライアントの対応状況は MCP クライアント設定リファレンスを参照してください。

前提条件

Kuroco 環境

• セキュリティを特権付き静的トークンに設定した API 定義で、MCP サーバーの設定が有効になっていること

• LLM のレスポンスで表示したい、または LLM に作成・更新させたいコンテンツ定義が存在すること

サポートされている LLM クライアント

クライアントの対応状況と設定手順は MCP クライアント設定リファレンス を参照してください。

Kuroco コンテンツで LLM のレスポンスを充実させる

読み取り専用エンドポイント（例：コンテンツリスト・詳細、ニュースリストなど）を MCP ツールとして公開し、LLM が会話中に Kuroco のコンテンツを取得できるようにします。

データスキーマの作成（推奨）

データスキーマの設定は必須ではありませんが、LLM の精度向上のために推奨します。スキーマを設定することで、LLM が渡せるパラメータを明示的に定義でき、必要なパラメータのみに絞ることができます。

これは JSON または Zod スキーマを使用して実現できます。Kuroco 全体で使用できるデータスキーマを作成するには、[オペレーション] → [データ定義] タブにアクセスします。

スキーマを手書きするのは手間がかかるため、「Zod schema」バリデーターの使用を推奨します。JSON・Zod スキーマいずれにも対応しており、Zod スキーマは自動的に変換されます。 データ定義の追加をクリックし、ページ下部の「Zod AI ジェネレーター」をクリックしてツールを開きます。

ここでは、filterクエリを使用して subject フィールド内の文字列を検索できるようにしたいので、AI に次のように指示します： add a field named filter that should contain "subject contains" followed by any string

生成されたスキーマを適用しZod定義を確認すると、入力文字列を subject フィールドに対して正規表現でマッチさせるスキーマが正しく生成されています。ツール右上の「保存して適用」ボタンをクリックすると、生成されたスキーマがKurocoのデータ定義編集画面に反映されます。

最後に、ページ下部の [追加する] をクリックしてデータ定義を追加します。

このチュートリアルで設定した値は以下になります。

項目	値
Name	Tutorial
Slug	(空)
Schema type	Zod schema
Schema	z.object({filter: z.string().regex(/^subject contains .+/).describe('Filter that contains the phrase "subject contains" followed by any string')})

読み取りエンドポイントの作成

エンドポイント一覧画面で [追加] をクリックし、以下を設定します。

フィールド	入力
Path	list
Category → Model → Operation	Content → Topics (v1) → list
Parameters	topics_group_id: (対象グループ ID) filter_request_allow_list：subject

読み取りエンドポイントで MCP を有効化する

1. エンドポイントの設定を開き、MCP 設定セクション/タブに移動します。
2. [ツール名]に一意でわかりやすい名前を入力します。（例：search_topics_by_subject）
3. [入力データ定義]で前の手順で作成したスキーマを選択します。出力データ定義はオプションです（このチュートリアルでは使用しません）。
4. [ステータス]のトグルをオンにしてツールを公開します。

ヒント

• ツール名は何をするかが名前から分かるように具体的にしてください（例：search_topics_by_subject）。
• 一覧取得・詳細取得など用途が異なる場合は、それぞれ個別のエンドポイントに MCP を設定してください。

備考

最適な結果を得るために、エンドポイントのサマリーと説明を整備してください。

LLM を使用してコンテンツを作成・更新する

書き込み可能なエンドポイント（例：コンテンツ作成/更新）を MCP ツールとして公開し、対応クライアントからコンテンツを作成・編集できるようにします。

データスキーマの作成（推奨）

GET エンドポイントと同様の手順で、コンテンツ定義に適したスキーマを生成します。 データ定義を以下のように登録します。

z.object({
  subject: z.string(),
  open_flg: z.number().int().gte(0).lte(1),
  ext_1: z.string()
});

書き込みエンドポイントの作成

コンテンツ追加エンドポイント

エンドポイント一覧画面で [追加] をクリックし、以下を設定します。

フィールド	入力
Path	topics-create
Category → Model → Operation	Content → Topics (v1) → insert
Parameters	topics_group_id: (対象グループ ID)

[追加] をクリックして保存します。

コンテンツ更新エンドポイント

エンドポイント一覧画面で [追加] をクリックし、以下を設定します。

フィールド	入力
Path	topics-update/{topics_id}
Category → Model → Operation	Content → Topics (v1) → update
Parameters	topics_group_id: (対象グループ ID)

書き込みエンドポイントで MCP を有効化する

1. エンドポイントの設定を開き、MCP 設定セクション/タブに移動します。
2. [ツール名]に一意でわかりやすい名前を入力します。（例：create_blog_post、update_blog_post）。
3. [入力データ定義]で前の手順で作成したスキーマを選択します。出力データ定義はオプションです（このチュートリアルでは使用しません）。
4. [ステータス]のトグルをオンにしてツールを公開します。。

注意

書き込み操作には認証が必要です。使用する LLM クライアントが MCP 設定でリクエストヘッダーを設定できることを確認してください。対象クライアント用のトークンを API の Swagger UI で生成し、クライアント側の設定でヘッダーに指定します。

備考

最適な結果を得るために、エンドポイントのサマリーと説明を整備してください。

Claude Code を使用した MCP サーバーのテスト

Claude Code はリモート HTTP トランスポートとヘッダー認証に対応しており、読み取り・書き込み操作を手軽にテストできます。

まず、API のトークンを生成します。対象 API の Swagger UI にアクセスし、ページ右上の [生成] ボタンをクリックして必要な情報を入力し、生成されたトークンをコピーします。

次に、MCP サーバーの URL を確認します。MCP サーバーを有効にした API 設定画面を開き、表示されている URL をコピーします。

次のコマンドで Kuroco MCP サーバーを Claude Code に登録します：

claude mcp add --transport http kuroco https://your-kuroco-domain.com/mcp --header "X-RCMS-API-ACCESS-TOKEN: <your-token>"

登録後、Claude Code のチャットから Kuroco のコンテンツを取得したり、コンテンツの作成・更新ができます。

読み取りの例：

北海道の食べ物について教えてください。

書き込みの例：

タイトルが「テスト投稿」、ext_1 が「これはテスト投稿です」の記事を作成してください。

ヒント

エンドポイントのサマリーと説明が適切に設定されていれば、「Kuroco のデータから」などと明示しなくても、Claude Code は自動的に適切な MCP ツールを選択して呼び出します。

MCP ツールが正しく登録されているか確認するには：

claude mcp list

テスト後に MCP サーバーを削除するには：

claude mcp remove kuroco

クライアント設定

各クライアントの詳細な設定手順は以下を参照してください。 MCP クライアント設定リファレンス

主要なチャット・コーディング系クライアント（Claude、ChatGPT Apps、Copilot、Codex / Cursor / Zed、GitHub Copilot、Jan、カスタム実装）向けの設定手順をまとめています。