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.

This page is about connecting

MCP is one of UTSUROI’s three AI surfaces — the one for driving it from an external AI tool. For what to actually do with it, see AI recipes; to try it inside the app with no setup, see the in-app AI chat.

MCP is the only surface where writes are not gated by an approval step in UTSUROI. The connected AI tool is responsible for what it runs.

The easy way: the official plugin

Before wiring up MCP by hand, try UTSUROI Agent Plugin. Alongside the connection settings it ships an Agent Skill that makes task workflows reliable (Apache 2.0).

Client	Install	Invoke
Codex	codex plugin marketplace add Anti-Pattern-Inc/utsuroi-agent-plugin codex plugin add utsuroi-agent-plugin@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.

Why the bundled Skill matters

On a bare MCP connection the AI works out the call order for itself every time. The bundled utsuroi Skill hands it the conventions up front — resolve board-local IDs before mutating, treat bulk creation as non-atomic — so mixed-up lane names and half-finished bulk creates become much rarer.

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

Endpoint

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

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.

Different from the REST API

The public REST API uses a personal API token (uts_pat_…) plus an X-Tenant-Id header. MCP uses an OAuth access token that already carries the tenant. Do not mix them up.

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.

Board settings are off by default on the consent screen too

mcp:boards.settings is off by default on the connection consent screen, even when the client requests it. You have to turn on Read and update board settings yourself. Existing connections and refresh tokens never gain this permission on their own.

To add it to an existing connection, reauthorize through your client’s MCP authentication controls and select the new permission. If the option is greyed out, the client registration only permits the older task scopes — register the client again, then reconnect. Role restrictions still apply after consent.

When scopes get dropped

Requesting a scope does not guarantee you get it.

• 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 limit, changing the token’s scopes will not help. Fix the role.

Read-only when reading is all you need

For summarizing, reporting or analysis, request only mcp:tasks.read. Without write access, nothing can be changed by mistake.

Available tools

There are 31. See the tool reference for the full list and arguments, and AI recipes for what to actually do with them.

Some operations are deliberately not exposed:

• Physical deletion (archiving works, and archived tasks can be restored)
• Lane-wide bulk mutation

So that an AI cannot do anything irreversible.

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”