MCP Usage — From the Field

A hands-on field guide to the iKanban MCP surface — 96 tools — written from a real run where every tool below was driven against a live server. It covers what each category is for, the exact parameters (including the ones whose names will trip you up), and the gotchas that 400 you.

The authoritative, always-current tool list lives inside the app: Settings → MCP Servers → MCP Capabilities (served live from the server). This page is the field companion — not an exhaustive index, but how the common tools actually behave.

What the MCP server is (and isn't)

iKanban exposes a Model Context Protocol server for supported agent operations. Some agent workflows also use selected REST routes; a vk_ key is restricted by a route deny-list, and many browser-management routes require a browser session. See Setup and Access before wiring REST calls.

• Read + create + update only. There is no delete over MCP — by design. Anything you create persists; remove it in the web UI.
• You address things by human identifiers. Team ENG, issue key ENG-42. You only need raw UUIDs for projects, sprints, releases, documents, and folders (get them from the matching list_* tool).

1. Connect

claude mcp add --scope user --transport http ikanban-remote \
  https://mcp.i-kanban.com/sse \
  --header "Authorization: Bearer vk_your_key_here"

Generate a key at Settings → API Keys (vk_…). Verify with claude mcp get ikanban-remote → expect ✓ Connected.

Gotcha — transport must be http, not sse. The URL path is /sse for history, but the transport is Streamable HTTP. Register it as sse and it fails silently — ✗ Failed to connect, no tools appear.

2. The tool map

The server exposes 96 tools. The commonly used ones are grouped below. For the complete, always-current list, open Settings → MCP Servers in the app — that is the authoritative catalogue; this table is a curated field subset.

3. Read this first — the param surprises that cost you a round-trip

The tool names are intuitive; several parameters are not. These are the exact ones that 400'd during the field run:

Keep this table open the first time and the 400s never happen.

4. The mental model

Workspace  ──>  Team  ──>  Project  ──>  Issue
                 │           ▲
                 │           └── a Project must be ATTACHED to a Team to hold its issues
                 ├── Sprint   (time-boxed cycle — issues are ASSIGNED to it)
                 └── Release  (ship target — issues are FILED under it; project-scoped)

• Workspace — billing + member seats; plan caps enforced here.
• Team (ENG) — owns issues, projects, sprints, releases, members; has a system AI Agent member.
• Project — created at the workspace level, then attached to a team.
• Issue (ENG-42) — the unit of work.
• Sprint / Release — overlays; issues are attached to them after creation (or, for a release, at creation via release_id).

5. The golden path — create → organize → verify

The end-to-end loop, all through MCP (team ENG, placeholder UUIDs — get real ones from list_*):

// 1. project  (create at workspace level, then ATTACH to the team in the UI)
create_project { "workspace_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", "name": "Backend" }
//    ⚠ a fresh project is NOT attached to a team → create_task 400s
//      "project does not belong to this team". Attach: Team → Projects → add.

// 2. issue  (priority + estimate + task_type REQUIRED; assignee omitted ⇒ team's AI Agent)
create_task { "feature_id": "<from list_features>", "team": "ENG", "project_id": "12345678-1234-1234-1234-123456789012",
              "title": "Wire up rate limiting", "priority": 2, "estimate": 3, "task_type": "feature" }

// 3. sprint  (dates are full ISO-8601 WITH timezone)
create_sprint { "team": "ENG", "name": "Sprint 30",
                "start_date": "2026-07-07T00:00:00Z", "end_date": "2026-07-21T00:00:00Z" }

// 4. assign issues to the sprint  (you CANNOT set a sprint on create_task)
bulk_assign_tasks_to_sprint { "team": "ENG", "sprint_id": "…", "task_ids": ["ENG-42","ENG-43"] }

// 5. project-scoped release, then file the issue under it
create_release { "team": "ENG", "name": "v1.4", "project_id": "12345678-…" }   // ← project_id!
create_task    { …, "release_id": "deadbeef-dead-beef-dead-beefdeadbeef" }

// 6. verify
get_sprint_tasks { "team": "ENG", "sprint_id": "…" }

Release gotcha. create_release without project_id makes a team-wide release (project_id NULL). Passing that release's id to create_task silently nulls — an issue only attaches to a release matching its own project. Always pass project_id when you intend to file issues under it. (Omit release_id entirely and the project's active release is auto-assigned.)

6. Category reference — every tool

👥 Teams & Issues

📋 Tasks & Projects

⚙️ Task Workflow

🏃 Sprints

🚀 Releases

📄 Documents & 📎 File Uploads

Uploads are a 3-move dance: get_document_upload_url → your client PUTs the file to S3 → register_uploaded_document. The MCP server never touches the bytes.

📁 Folders

💬 Comments

📊 Visibility & Analytics

🏷️ Tags

🔧 Context

7. Value cheat-sheet

These are API values. The current workspace invite UI offers Admin/Member; team UI offers Contributor/Maintainer/Viewer/Owner. Workspace Owner/Admin representation is described in Members and Roles. Do not infer a one-to-one UI permission mapping from an API token. | any date | full ISO-8601 with timezone — 2026-07-07T00:00:00Z |

8. Troubleshooting — symptom → cause → fix

That's the field guide — 96 tools live, the common ones exercised above (full list in Settings → MCP Servers). Keep §3 and §7 handy and the tools do exactly what you'd expect.