@task-boards/mcp-server

MCP stdio server for Task Boards — integrates with IDE MCP clients for agent orchestration.

Quick start

npx @task-boards/mcp-server

Or install globally:

npm install -g @task-boards/mcp-server
task-boards-mcp

Bundled Cursor skills

Six English Agent Skills ship inside the npm package for orchestrator workflows. Install them into Cursor's skills directory — no API token required.

| Command | Target | | ----------------------------------------- | --------------------------------- | | task-boards-mcp skills install | {workspaceRoot}/.cursor/skills/ | | task-boards-mcp skills install --global | ~/.cursor/skills/ |

From the monorepo after build:

node packages/mcp-server/build/cli.js skills install

Skill catalog

| Skill | Focus | | -------------------------- | ----------------------------------------------------------- | | task-boards-setup | MCP config, env vars, WORKSPACE_ROOT | | task-boards-orchestrator | Poll loop, run_orchestrator_once, timeout, single-sleeper | | task-boards-work-items | WI CRUD, move, estimation, SERVICE assignee | | task-boards-agent-runs | ack → complete, AGENTIC_SDLC outcomes | | task-boards-attention | IDE attention, 7 categories, in-awaiting distinction | | task-boards-git-sync | sync_git_releases, work-item:{uuid}, subagents |

Re-run skills install after upgrading @task-boards/mcp-server to refresh skill content. Install is idempotent — existing skills are overwritten.

Environment variables

| Variable | Required | Default | Description | | ----------------------- | ---------------- | --------------------------------- | -------------------------------------------------------------------------------------- | | TASK_BOARDS_API_URL | No | https://task-boards.com/backend | Task Boards backend base URL | | TASK_BOARDS_API_TOKEN | Yes (production) | — | API token with read / write scopes | | WORKSPACE_ROOT | No | — | Workspace root for sync_git_releases, sync_project_subagents, and attachment paths |

IDE / MCP configuration

Add to your IDE MCP config (example: .cursor/mcp.json) or MCP settings:

{
  "mcpServers": {
    "task-boards": {
      "command": "npx",
      "args": ["-y", "@task-boards/mcp-server"],
      "env": {
        "TASK_BOARDS_API_URL": "https://task-boards.com/backend",
        "TASK_BOARDS_API_TOKEN": "<your-api-token>",
        "WORKSPACE_ROOT": "/path/to/your/repo"
      }
    }
  }
}

Orchestrator tools

For chat-based orchestrator loops (not CLI):

In-app guide: client-agnostic orchestrator loop, Claude Desktop config, and other IDE dispatch patterns — /guide/mcp-orchestrator (Task Boards UI, sign-in required). IDE Task() flow: /guide/agentic-prompts.

Architecture: internal dispatch port and runtime adapters — see ARCHITECTURE.md and ADR-013. MCP tool names/schemas are unchanged (AC-4).

| Tool | Purpose | | ------------------------ | --------------------------------------------------------------------------------------------------- | | run_orchestrator_once | Resolve project (optional), long-poll with claim, return orchestrator hints — preferred entry point | | wait_for_agent_runs | Long-poll when projectId is already known | | sync_git_releases | Sync work-item commits after timeout or run completion | | sync_project_subagents | Write project custom subagents to .cursor/agents/{slug}.md before Task dispatch with custom slugs | | report_agent_attention | Set requiresAttention on an ACKNOWLEDGED run; message replaces prior on same run | | clear_agent_attention | Clear IDE attention after human resolves blocker in the IDE |

Defaults: timeout=120 seconds (max 300), pollInterval=2, limit=1 (max 10 runs per claim).

Both poll tools return items, inflightRuns, and an orchestrator object.

| Top-level field | When | Description | | --------------- | ------ | ----------------------------------------------------------------- | | items | always | Newly claimed runs (PENDING→DISPATCHED) | | inflightRuns | always | Recovered DISPATCHED/ACKNOWLEDGED from list (orphan recovery) | | timedOut | always | true only when deadline reached with no claimed and no inflight |

orchestrator shape:

| Field | When | Description | | ------------------ | ---------- | ------------------------------------------------------------------------------------ | | phase | always | idle (timeout / no runs) or processing (claimed or inflight runs) | | pollResultSource | always | claimed | inflight | idle | | sleeperPolicy | always | Single-sleeper rules (singleBlockingPoll, noParallelPoll, noDuplicateWake) | | nextSteps | always | Action hints; idle includes inflight check + do not clear attention on timeout | | inflightSummary | processing | Counts for recovered runs when inflightRuns non-empty | | processRuns | processing | Per-run agentRunId, workItemId, phase, source, steps, optional attention | | attentionSummary | processing | blockedRunCount, blockedAgentRunIds, resolveBeforeNewDispatch | | runLifecycle | processing | Phase list + ideAttentionVsWorkflowAwaiting (IDE attention ≠ in-awaiting) |

Per-run source: "claimed" = fresh claim; "inflight" = orphan recovery from list.

Per-run attention (when requiresAttention: true): phase, message, detectedCategory, reportGuidance (replace semantics), clearGuidance, templateCategories.

Message format for report_agent_attention: [{category}] {detail} — categories: shell, git, network, smart-mode, mcp, file, other. Re-reporting replaces the stored message (latest wins).

On timedOut: true, phase is idle; hints suggest sync_git_releases then polling again. Do not call clear_agent_attention on timeout — the board badge remains until resolved.

When agent runs reference project custom subagent slugs (not built-in IDE subagents), call sync_project_subagents(projectId) before Task(subagent_type=…) so the IDE can resolve the slug from {workspaceRoot}/.cursor/agents/.

Example:

{ "projectId": "f9ee1002-2b17-4803-9a7d-949741b9fd8d" }

Returns { "synced": ["my-project-analyst"], "skipped": [], "directory": "/path/to/repo/.cursor/agents" }.

Configure custom subagents and role bindings in the web UI (Project Settings → Agents, AGENTIC_SDLC only). See in-app guide /guide/project-agents.

run_orchestrator_once accepts optional projectId (resolves via .task-boards.yaml / .cursor/rules when omitted) and optional workspaceRoot. It does not call sync_git_releases automatically.