Architecture of Real-Time Kanban Dashboards for Agent Tasks: MCP Server Design Patterns

Real-time kanban dashboards for agent tasks utilize a self-hosted three-layer architecture combining SQLite persistence, a localhost MCP server with WebSocket capabilities, and a React-based visualization layer to enable multi-agent workflow coordination without external SaaS dependencies.

The anthropics/claude-plugins-community repository implements this design as a pipeline-driven task management system that orchestrates AI coding agents through visual boards. By running entirely on localhost, the architecture satisfies Claude Code plugin security requirements while providing persistent state management and real-time UI synchronization.

Three-Layer MCP Server Architecture

The system separates concerns into distinct layers that communicate through defined protocols, ensuring loose coupling between visualization logic and business rules.

Storage and State Layer

At the foundation, SQLite persists tasks, stages, dependencies, comments, and artifact versions. The MCP server accesses this database through a dedicated data-access layer, ensuring atomic transactions when agents concurrently create or move tasks. This local-first approach eliminates network latency and external API dependencies.

Control Plane and API Layer

The middle layer implements the MCP (Meta-Control-Protocol) server in Python or Node.js, exposing two critical interfaces:

• HTTP endpoints handling REST-style skill commands such as /kanban:create, /kanban:move, and /kanban:status
• WebSocket endpoint at ws://localhost:8765/ws that pushes live updates via events like task_updated

The server validates all requests against configurable stage-gate rules, enforces approval workflows, and manages artifact versioning before committing changes to SQLite.

Visualization and Client Layer

The top layer consists of a React single-page application (or plain HTML/JS) served directly by the MCP server at http://localhost:8765/dashboard. Clients establish persistent WebSocket connections to receive instantaneous updates when agents modify tasks, enabling drag-and-drop interactions and live status badge updates without page refreshes.

Real-Time Data Flow and Event Propagation

The architecture implements a closed feedback loop that synchronizes agent actions with visual state:

1. Skill Invocation — An agent executes a skill command (e.g., /kanban:create title="Add login flow" stage=backlog) which translates into an HTTP POST request to the MCP server.

2. Server Processing — The control plane validates the request against pipeline rules, persists the change to SQLite, and broadcasts a WebSocket event (task_updated) to all connected clients.

3. Client Refresh — Dashboard instances receive the event and update the UI in-place, reflecting new tasks, stage transitions, or dependency graph changes immediately.

4. Feedback Loop — Agents query the current board state via /kanban:status to drive downstream actions, such as triggering tests for all tasks in the implement stage.

Pipeline-Driven Task Management Features

Beyond basic CRUD operations, the MCP server enforces sophisticated workflow semantics through several architectural concepts.

Configurable Stage-Gate Pipelines

Tasks flow through strictly ordered stages: backlog → spec → plan → implement → test → review → done. Each stage defines validation hooks that block progression until specific criteria are met, ensuring quality gates before agents advance work items.

Dependency Tracking and Enforcement

The system supports parent-child task relationships stored in SQLite. The server enforces topological ordering, preventing agents from moving tasks to implementation stages until all dependencies reach completion, and renders these relationships as dependency graphs on the client.

Multi-Agent Approval Workflows

Critical stages such as review require explicit approval from designated agents before progression. The MCP server maintains an audit trail of approval actions in the database and reflects pending approval states in the WebSocket event stream.

Artifact Versioning and Threaded Comments

When tasks reach artifact-producing stages (e.g., generating code diffs), the server snapshots outputs and links them to task records for later audit. Additionally, threaded comments allow agents to attach context (e.g., "need security review") that persists across sessions and appears in real-time to other collaborators.

Implementation Reference and Code Examples

The plugin definition resides in .claude-plugin/marketplace.json#L630, which describes the real-time kanban dashboard capabilities to Claude Code's marketplace system.

Skill Command Examples

Create a new task in the backlog:

/kanban:create title="Add login flow" description="Implement OAuth login" stage=backlog

Advance an existing task through the pipeline:

/kanban:move id=42 stage=plan

Retrieve current board state as JSON:

/kanban:status

Real-Time Client Integration

Connect to the WebSocket endpoint for live updates:

const ws = new WebSocket("ws://localhost:8765/ws");
ws.onmessage = (e) => {
  const event = JSON.parse(e.data);
  if (event.type === "task_updated") refreshTask(event.taskId);
};

External reference implementations such as VibeKanban demonstrate concrete open-source kanban UIs that integrate with this architecture, while prd-to-kanban illustrates pipelines that generate kanban data from PRD documents.

Summary

• The architecture comprises three layers: SQLite storage, an MCP control plane (Python/Node.js), and a React/SPA client served on localhost:8765.
• Real-time synchronization occurs through WebSocket events (task_updated) broadcast from the server to all connected dashboard clients.
• Stage-gated pipelines enforce workflow constraints across seven standard stages from backlog to completion.
• The system supports multi-agent collaboration through dependency tracking, approval workflows, and threaded comments with full audit trails.
• All components run locally without external API keys, as defined in .claude-plugin/marketplace.json#L630.

Frequently Asked Questions

What protocol enables real-time updates in the kanban dashboard?

The MCP server exposes a WebSocket endpoint at ws://localhost:8765/ws that pushes events such as task_updated to connected clients immediately after SQLite transactions commit. This protocol enables sub-second latency between agent actions and UI updates.

How does the architecture support multiple agents working simultaneously?

The SQLite database provides ACID guarantees for concurrent access, while the MCP server's WebSocket broadcasts ensure all agents see state changes instantly. Each agent interacts through the same HTTP API endpoints (e.g., /kanban:move), and the server resolves conflicts through validation hooks and stage-gate enforcement.

What database does the MCP server use for task persistence?

The implementation utilizes SQLite as the primary data store, accessed through a data-access layer within the MCP server. This choice eliminates external database dependencies and aligns with the local-first security model required for Claude Code plugins.

Where is the kanban dashboard plugin defined in the repository?

The plugin metadata and dashboard description are located at .claude-plugin/marketplace.json#L630, which specifies the MCP server configuration, available skill commands, and the localhost URL (http://localhost:8765/dashboard) where the React client is served.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}