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.
The easy way: the official plugin
Section titled “The easy way: the official plugin”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).
Ask your AI to do it (Claude Code, Codex)
Section titled “Ask your AI to do it (Claude Code, Codex)”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-pluginIt 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:
- Sign in in your browser and approve the connection. The AI cannot do this for you.
- 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.
Install with commands
Section titled “Install with commands”| Client | Install | Invoke |
|---|---|---|
| Codex | codex plugin marketplace add Anti-Pattern-Inc/utsuroi-agent-plugincodex 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.
Keeping the plugin up to date
Section titled “Keeping the plugin up to date”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, runclaude plugin marketplace update utsuroi, thenclaude 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=0to 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.
Endpoint
Section titled “Endpoint”POST https://api.utsuroi.nil0.io/mcp- JSON-RPC over HTTP
- SSE is not supported.
GET /mcpreturns405 - The tenant (workspace) comes from the access token’s claims. No
X-Tenant-Idheader
Authentication
Section titled “Authentication”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.
Scopes
Section titled “Scopes”| 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.
When scopes get dropped
Section titled “When scopes get dropped”Some requested scopes are not granted:
- Viewer or guest role →
mcp:tasks.readonly - Workspace in a restricted state (over the Free limit, for example) →
mcp:tasks.readonly - Board access set to “selected boards” →
mcp:boards.settingsis never granted
If the role is the cause, changing scopes will not help. Fix the role.
Available tools
Section titled “Available tools”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).
Troubleshooting
Section titled “Troubleshooting”| 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.