MCP をつなぐ
UTSUROI は MCP(Model Context Protocol)サーバーとして動きます。Claude Code など MCP に対応した AI ツールから、ボード・タスク・コメントを直接扱えます。
いちばん簡単な方法: 公式プラグイン
Section titled “いちばん簡単な方法: 公式プラグイン”手で MCP 設定を書く前に、UTSUROI Agent Plugin を試してください。接続設定に加えて、タスク操作の作法をまとめた Agent Skill が入っています(Apache 2.0)。
AI に頼む(Claude Code・Codex)
Section titled “AI に頼む(Claude Code・Codex)”ターミナルで動く AI なら、次の一文を渡すだけで導入を進めてくれます。
https://github.com/Anti-Pattern-Inc/utsuroi-agent-plugin を設定してAI がリポジトリの README を読み、下の表と同じ手順をコマンドで実行します。コマンドの実行を確認されたら許可してください。人がやることは次の 2 つです。
- ブラウザでサインインして、接続を許可します。 ここは AI には代われません。
- 再読み込みします。 Claude Code は
/reload-plugins、Codex は新しいチャットを開きます。
Kiro は画面操作(下の表)が必要で、AI に頼めません。ブラウザの AI チャットのようにコマンドを実行できない AI も対象外です。
コマンドで入れる
Section titled “コマンドで入れる”| クライアント | インストール | 呼び出し |
|---|---|---|
| Codex | codex plugin marketplace add Anti-Pattern-Inc/utsuroi-agent-plugincodex plugin add utsuroi@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 を実行します。
アプリの 設定 → AI連携 (MCP) にも、接続先 URL とこのコマンドがあり、コピーできます。
プラグインを最新に保つ
Section titled “プラグインを最新に保つ”ツールは常にサーバー側の最新版が使われます。古くなるのは、プラグインに同梱された Skill(手順書)です。
- Claude Code: 公式以外のマーケットプレイスは、既定では自動更新されません。
/plugin→ Marketplaces →utsuroi→ Enable auto-update をオンにすると、更新が自動で取り込まれます。反映は再起動か/reload-pluginsです。手動で更新するなら、claude plugin marketplace update utsuroiのあとにclaude plugin update utsuroi@utsuroiを実行します。 - 更新の通知: プラグイン 0.5.0 以降は、Claude Code の起動時に 1 日 1 回だけ新しい版の有無を確認し、あれば AI が更新方法を知らせます。通知だけで、勝手に更新はしません。止めるには環境変数
UTSUROI_PLUGIN_UPDATE_CHECK=0を設定します。0.5.0 より前の版は、一度だけ手動で更新してください。 - Codex と Kiro: 通知は Claude Code のみです。各クライアントのプラグイン管理から、マーケットプレイスを更新するか、リポジトリを取り込み直します。
以下は、プラグインを使わず自分で接続する場合の情報です。
エンドポイント
Section titled “エンドポイント”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 で即時失効できないため、意図的に短命にしてあります。対応クライアントは自動で更新します。
| スコープ | 内容 | 既定 |
|---|---|---|
mcp:tasks.read |
読み取り系ツール | ○ |
mcp:tasks.write |
書き込み系ツール | ○ |
mcp:boards.settings |
ボード設定系ツール | オプトイン |
mcp:boards.settings は明示的に要求しないと付きません。要求しなければ、該当ツールは tools/list にも現れません。
スコープが自動で落ちる条件
Section titled “スコープが自動で落ちる条件”要求しても付与されないケースです。
- 閲覧(viewer)または ゲスト のロール →
mcp:tasks.readのみ - ワークスペースが制限状態(Free の上限超過など) →
mcp:tasks.readのみ - ボードアクセスが「選択したボードのみ」 →
mcp:boards.settingsは付与されません
ロールが原因なら、スコープを変えても結果は変わりません。ロールを直してください。
使えるツール
Section titled “使えるツール”36 個あります。一覧と引数はツールリファレンスにあります。 実際に何をさせると効くかはスキル集へ。立ち上げの分解・優先度付け・ 見積もり・棚卸し・分析の雛形が、コピーしてすぐ使える形で置いてあります。
物理削除とレーン単位の一括変更は、意図的に公開していません(AI でできないこと)。
接続がうまくいかないとき
Section titled “接続がうまくいかないとき”| 症状 | 確認すること |
|---|---|
405 が返る |
GET で叩いていませんか。POST /mcp です |
| ツールが1つも出ない | スコープが付いていません。ロールと、ワークスペースが制限状態でないかを確認 |
| 書き込みツールが出ない | 閲覧・ゲストロールでは出ません。mcp:tasks.write を要求していても同じです |
| ボード設定ツールが出ない | mcp:boards.settings を要求していますか。ボードアクセスが「選択したボードのみ」だと付与されません |
作業の決定や学びを次の AI に引き継ぐには、プロジェクトのナレッジを育てるをご覧ください。