Skip to content

Connecting MCP

UTSUROI runs as an MCP (Model Context Protocol) server. Any MCP-capable AI tool — Claude Code among them — can work with your boards, tasks and comments directly.

Before wiring up MCP by hand, try the UTSUROI Agent Plugin. Besides the connection settings, it includes an Agent Skill with conventions for task operations (Apache 2.0).

An AI that runs in your terminal can carry out the install if you hand it one sentence:

Set up https://github.com/Anti-Pattern-Inc/utsuroi-agent-plugin

It reads the repository README and runs the same steps as the table below as commands. Approve the command if it asks. Two steps are left to you:

  1. Sign in in your browser and approve the connection. The AI cannot do this for you.
  2. Reload. In Claude Code run /reload-plugins; in Codex open a new chat.

Kiro needs the on-screen steps in the table and cannot be set up this way. Neither can an AI that cannot run commands, such as a browser chat.

Client Install Invoke
Codex codex plugin marketplace add Anti-Pattern-Inc/utsuroi-agent-plugin
codex plugin add utsuroi@utsuroi
@UTSUROI or $utsuroi
Claude Code /plugin marketplace add Anti-Pattern-Inc/utsuroi-agent-plugin
/plugin install utsuroi@utsuroi
/utsuroi:utsuroi, or automatically
Kiro Powers panel → Add Custom Power → Import power from GitHub → paste the repository URL Automatically, on task keywords

Start a new chat after installing. Run /reload-plugins if Claude Code asks you to reload.

The endpoint URL and these commands are also in the app under Settings → AI integrations (MCP), ready to copy.

The tools always come from the server, so they are current. What can go stale is the Skill (the instructions) bundled with the plugin.

  • Claude Code: third-party marketplaces do not auto-update by default. Turn it on under /plugin → Marketplaces → utsuroi → Enable auto-update; updates then arrive on their own and apply after a restart or /reload-plugins. To update by hand, run claude plugin marketplace update utsuroi, then claude plugin update utsuroi@utsuroi.
  • Update notice: from plugin 0.5.0, Claude Code checks at most once a day, when a session starts, whether a newer version exists and has the AI tell you how to update. It only notifies and never updates by itself. Set the environment variable UTSUROI_PLUGIN_UPDATE_CHECK=0 to turn it off. Versions before 0.5.0 need one manual update.
  • Codex and Kiro: the notice runs only in Claude Code. Refresh the marketplace or re-import the repository from your client’s plugin manager.

What follows is for connecting by hand, without the plugin.

POST https://api.utsuroi.nil0.io/mcp
  • JSON-RPC over HTTP
  • SSE is not supported. GET /mcp returns 405
  • The tenant (workspace) comes from the access token’s claims. No X-Tenant-Id header

OAuth 2.1, with discovery metadata published, so a capable client only needs the URL.

Endpoint Purpose
/.well-known/oauth-protected-resource Protected resource metadata (RFC 9728)
/.well-known/oauth-authorization-server Authorization server metadata
/oauth/register Dynamic client registration
/oauth/authorize Authorization
/oauth/token Issue and refresh tokens

Token lifetimes:

Token Lifetime
Authorization code 5 minutes
Access token 15 minutes
Refresh token 30 days

Access tokens are stateless JWTs and cannot be revoked instantly, so they are deliberately short-lived. Capable clients refresh automatically.

Scope Covers Default
mcp:tasks.read Read tools yes
mcp:tasks.write Write tools yes
mcp:boards.settings Board settings tools opt-in

mcp:boards.settings is only granted if you request it. Without it, those tools do not even appear in tools/list.

Some requested scopes are not granted:

  • Viewer or guest role → mcp:tasks.read only
  • Workspace in a restricted state (over the Free limit, for example) → mcp:tasks.read only
  • Board access set to “selected boards” → mcp:boards.settings is never granted

If the role is the cause, changing scopes will not help. Fix the role.

There are 36. See the tool reference for the full list and arguments, and the skill collection for ready-to-copy templates covering planning, prioritization, estimation, reviews, and analysis.

Physical deletion and lane-wide bulk mutation are deliberately not exposed (What it deliberately cannot do).

Symptom Check
405 Are you using GET? It is POST /mcp
No tools at all No scopes granted. Check the role and whether the workspace is restricted
No write tools Viewer and guest roles never get them, scope request or not
No board settings tools Did you request mcp:boards.settings? Not granted when board access is “selected boards”

To carry decisions and findings into the next AI session, see Build project knowledge.