MCP をつなぐ

UTSUROI は MCP（Model Context Protocol）サーバーとして動きます。Claude Code など MCP に対応した AI ツールから、ボード・タスク・コメントを直接扱えます。

ここは「つなぎ方」のページです

MCP は UTSUROI の 3つの AI の面のひとつで、外部の AI ツールから使うための接続口です。 つないだあとの使い方はスキルを用意するとスキル集に、 面をまたぐ汎用の使い方は AI 活用レシピに、アプリ内で試すだけなら ブラウザの AI チャット（インストール不要）にあります。

MCP だけは書き込みに UTSUROI 側の承認がありません。実行の責任は接続した AI ツール側にあります。

いちばん簡単な方法: 公式プラグイン

手で MCP 設定を書く前に、UTSUROI Agent Plugin を試してください。接続設定に加えて、タスク操作を安定させるための Agent Skill が同梱されています（Apache 2.0）。

クライアント	インストール	呼び出し
Codex	codex plugin marketplace add Anti-Pattern-Inc/utsuroi-agent-plugin codex plugin add utsuroi-agent-plugin@utsuroi	@UTSUROI または $utsuroi
Claude Code	/plugin marketplace add Anti-Pattern-Inc/utsuroi-agent-plugin /plugin install utsuroi@utsuroi	/utsuroi:utsuroi、または自動
Kiro	Powers パネル → Add Custom Power → Import power from GitHub → リポジトリ URL を入力	タスク関連のキーワードで自動

インストール後は新しいチャットを開いてください。Claude Code が再読み込みを求めたら /reload-plugins を実行します。

Skill が同梱されている意味

素の MCP 接続だと、AI はツールの呼び出し順を毎回自分で考えます。同梱の utsuroi Skill は 「変更の前にボード固有の ID を解決する」「一括作成は非アトミックとして扱う」といった作法を 先に与えるので、レーン名の取り違えや中途半端な一括作成が起きにくくなります。

以下は、プラグインを使わず自分で接続する場合の情報です。

エンドポイント

POST https://api.utsuroi.nil0.io/mcp

• JSON-RPC over HTTP です
• SSE には対応していません。 GET /mcp は 405 を返します
• テナント（ワークスペース）はアクセストークンのクレームから決まります。X-Tenant-Id ヘッダーは不要です

認証

OAuth 2.1 です。ディスカバリ用のメタデータを公開しているので、対応クライアントなら URL を渡すだけで接続できます。

エンドポイント	用途
/.well-known/oauth-protected-resource	保護リソースのメタデータ（RFC 9728）
/.well-known/oauth-authorization-server	認可サーバーのメタデータ
/oauth/register	動的クライアント登録
/oauth/authorize	認可
/oauth/token	トークン発行・更新

トークンの寿命は次のとおりです。

トークン	有効期間
認可コード	5 分
アクセストークン	15 分
リフレッシュトークン	30 日

アクセストークンはステートレスな JWT で即時失効できないため、意図的に短命にしてあります。対応クライアントは自動で更新します。

REST API とは別の仕組みです

公開 REST API はパーソナル API トークン（uts_pat_…）と X-Tenant-Id ヘッダーを使います。 MCP は OAuth のアクセストークンで、テナントはトークンに含まれます。混同しないでください。

スコープ

スコープ	内容	既定
mcp:tasks.read	読み取り系ツール	○
mcp:tasks.write	書き込み系ツール	○
mcp:boards.settings	ボード設定系ツール	オプトイン

mcp:boards.settings は明示的に要求しないと付きません。要求しなければ、該当ツールは tools/list にも現れません。

ボード設定は同意画面でも既定オフ

mcp:boards.settings は、クライアントが要求していても接続の同意画面で既定オフです。 付与するには同意画面で「ボード設定の読み取りと更新」を自分で有効にする必要があります。 既存の接続やリフレッシュトークンが、あとから勝手にこの権限を得ることはありません。

既存の接続に足したい場合は、クライアントの MCP 認証設定から再認可して、新しい権限を選びます。 その選択肢が出てこない場合は、クライアント登録が古いタスク系スコープしか許可していません。 クライアントを登録し直してから接続してください。同意したあとも、ロールによる制限は変わりません。

スコープが自動で落ちる条件

要求しても付与されないケースがあります。

• 閲覧（viewer）または ゲスト のロール → mcp:tasks.read のみ
• ワークスペースが制限状態（Free の上限超過など） → mcp:tasks.read のみ
• ボードアクセスが「選択したボードのみ」 → mcp:boards.settings は付与されません

ロールが足りない場合、トークンのスコープを変えても結果は変わりません。ロール側を直す必要があります。

読ませるだけなら read だけにする

AI に状況を要約させたい、レポートを作らせたいといった用途なら、mcp:tasks.read だけを要求してください。 書き込み権限を渡さなければ、意図しない変更が起きません。

使えるツール

31 個あります。一覧と引数はツールリファレンスにあります。 実際に何をさせると効くかはスキル集へ。立ち上げの分解・優先度付け・ 見積もり・棚卸し・分析の雛形が、コピーしてすぐ使える形で置いてあります。

意図的に公開していない操作もあります。

• 物理削除（アーカイブはできます。復元も可能です）
• レーン単位の一括変更

AI が取り返しのつかない操作をできないようにするためです。

接続がうまくいかないとき

症状	確認すること
405 が返る	GET で叩いていませんか。POST /mcp です
ツールが1つも出ない	スコープが付いていません。ロールと、ワークスペースが制限状態でないかを確認
書き込みツールが出ない	閲覧・ゲストロールでは出ません。mcp:tasks.write を要求していても同じです
ボード設定ツールが出ない	mcp:boards.settings を要求していますか。ボードアクセスが「選択したボードのみ」だと付与されません