Skip to content

Latest commit

 

History

History
829 lines (611 loc) · 32.4 KB

File metadata and controls

829 lines (611 loc) · 32.4 KB

MCP Server — Veritas Kanban

36 tools · 8 categories · stdio transport · zero external dependencies

The Veritas Kanban MCP server lets any Model Context Protocol client — Claude Desktop, OpenClaw, Cursor, Cline, Codex, or your own tooling — manage tasks, sprints, projects, comments, agents, automation, notifications, and summaries through a single stdio process.


Table of Contents


When to Use the MCP Server

Use the MCP server when:

  • Your AI assistant (Claude Desktop, Cursor, etc.) needs structured tool access to VK — not raw HTTP calls.
  • You want one process that exposes all 36 VK operations with typed inputs and validated outputs.
  • You're building agent orchestration and need task/sprint/automation lifecycle management over MCP.

Don't use it when:

  • You just need a quick REST call — use the REST API directly.
  • You're building a web frontend — use the HTTP API with the TypeScript client.
  • You need WebSocket streaming — the MCP server uses stdio, not SSE/WS.

Architecture

┌─────────────────────────────────────────────────┐
│  MCP Client (Claude Desktop / OpenClaw / etc.)  │
└──────────────────────┬──────────────────────────┘
                       │ stdio (JSON-RPC)
                       ▼
┌──────────────────────────────────────────────────┐
│  MCP Server Process  (mcp/dist/index.js)         │
│                                                  │
│  ┌────────────┐  ┌────────────┐  ┌───────────┐  │
│  │ Tool       │  │ Resource   │  │ Transport  │  │
│  │ Registry   │  │ Provider   │  │ (stdio)    │  │
│  │ (36 tools) │  │ (kanban:// │  │            │  │
│  │            │  │  URIs)     │  │            │  │
│  └──────┬─────┘  └──────┬─────┘  └───────────┘  │
│         │               │                        │
│         └───────┬───────┘                        │
│                 ▼                                 │
│         ┌──────────────┐                         │
│         │ HTTP Client  │                         │
│         │ → VK Server  │                         │
│         └──────┬───────┘                         │
└────────────────┼─────────────────────────────────┘
                 │ HTTP (localhost:3001)
                 ▼
┌──────────────────────────────────────────────────┐
│  Veritas Kanban Server (Express/Hono)            │
│  REST API · Task Store · Sprint Engine           │
└──────────────────────────────────────────────────┘

Key design decisions:

  • Stdio transport only — the MCP server is a child process of the client. No network ports opened.
  • Stateless proxy — every tool call translates to one or more HTTP requests to the VK server. The MCP process holds no state.
  • Zod validation — all tool inputs are validated with Zod schemas before hitting the API.
  • @modelcontextprotocol/sdk v1.27 — uses the official TypeScript SDK.

Quickstart

Prerequisites

  • Node.js ≥ 22
  • The Veritas Kanban server running (pnpm dev or production)
  • pnpm (for building from source)

Local Development

# 1. Start the VK server
cd veritas-kanban
pnpm dev                          # Server on http://localhost:3001

# 2. Build shared code and the MCP server
pnpm --filter @veritas-kanban/shared build
pnpm --filter @veritas-kanban/mcp build

# 3. Configure your MCP client

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "veritas-kanban": {
      "command": "node",
      "args": ["/absolute/path/to/veritas-kanban/mcp/dist/index.js"],
      "env": {
        "VK_API_URL": "http://localhost:3001",
        "VK_API_KEY": "your-agent-api-key"
      }
    }
  }
}

For Cursor, add the same block to .cursor/mcp.json in your project root.

For OpenClaw, add to your OpenClaw MCP config:

{
  "mcpServers": {
    "veritas-kanban": {
      "command": "node",
      "args": ["/absolute/path/to/veritas-kanban/mcp/dist/index.js"],
      "env": {
        "VK_API_URL": "http://localhost:3001",
        "VK_API_KEY": "your-agent-api-key"
      }
    }
  }
}

Omit VK_API_KEY only for read-only localhost checks. Write tools need a key unless localhost bypass grants an agent or admin role.

Verify discovery works:

# Quick smoke test — run the MCP server directly and send a tools/list request
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | \
  VK_API_URL=http://localhost:3001 node mcp/dist/index.js 2>/dev/null | \
  head -1 | jq '.result.tools | length'
# Expected output: 36

Verify read/write auth works:

Run this before giving an assistant MCP write access:

export VK_API_URL=http://localhost:3001
export VK_API_KEY=your-agent-api-key

# Read check: call list_tasks
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_tasks","arguments":{"status":"todo"}}}' | \
  node mcp/dist/index.js 2>/dev/null | \
  head -1 | jq -e '.result.content[0].text | fromjson | type == "array"'

# Write check: create a temporary task
MCP_TASK_ID=$(echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"create_task","arguments":{"title":"MCP auth smoke test","type":"automation","priority":"low","description":"Temporary task created by MCP auth smoke test."}}}' | \
  node mcp/dist/index.js 2>/dev/null | \
  head -1 | jq -r '.result.content[0].text | capture("Task created: (?<id>[^\\n]+)").id')

# Cleanup
echo "{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"delete_task\",\"arguments\":{\"id\":\"$MCP_TASK_ID\"}}}" | \
  node mcp/dist/index.js 2>/dev/null | \
  head -1 | jq -e '.result.content[0].text | startswith("Task deleted: ")'

Expected result: the read command exits 0, the write command captures a task ID, and cleanup returns true. If tools/list works but create_task fails with 401 or 403, the MCP process is installed but does not have write-capable API auth. Put VK_API_KEY in the MCP client env block and restart the client.

Codex

OpenAI Codex can also use the Veritas Kanban MCP server. This is the recommended setup when Codex should update tasks, read board context, or coordinate through Veritas instead of making ad hoc HTTP calls.

Local development:

codex mcp add veritas-kanban \
  --env VK_API_URL=http://localhost:3001 \
  --env VK_API_KEY=your-agent-api-key \
  -- node /absolute/path/to/veritas-kanban/mcp/dist/index.js

Production or API-key mode:

codex mcp add veritas-kanban \
  --env VK_API_URL=https://kanban.yourdomain.com \
  --env VK_API_KEY=your-agent-api-key \
  -- node /absolute/path/to/veritas-kanban/mcp/dist/index.js

Recommended companion for OpenAI-related development work:

codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp

Pair this with the Codex-specific instructions in AGENTS-TEMPLATE.md, the v4.3 Codex Integration SOP, and the Veritas Cutover Operating Guide when Codex is coordinating with HermesAgent/Hermes Gateway.

Production

When running VK behind a reverse proxy (nginx/Caddy):

{
  "mcpServers": {
    "veritas-kanban": {
      "command": "node",
      "args": ["/opt/veritas-kanban/mcp/dist/index.js"],
      "env": {
        "VK_API_URL": "https://kanban.yourdomain.com",
        "VK_API_KEY": "your-agent-api-key"
      }
    }
  }
}

Important: In production, always set VK_API_KEY so the MCP server authenticates with the VK API. Without it, requests rely on localhost bypass (which won't work remotely). Local writes: Read-only localhost calls may work without VK_API_KEY, but write tools need a key unless VERITAS_AUTH_LOCALHOST_ROLE is set to agent or admin.


Configuration Reference

The MCP server is configured via environment variables passed from the MCP client config.

Variable Default Description
VK_API_URL http://localhost:3001 Base URL of the Veritas Kanban server
VK_API_KEY (none) API key for authenticated requests. Required when not on localhost.

VK Server Environment Variables (relevant to MCP)

These are set in server/.env, not in the MCP client config:

Variable Default Description
PORT 3001 Server port
VERITAS_AUTH_ENABLED true Enable/disable authentication
VERITAS_AUTH_LOCALHOST_BYPASS true Allow unauthenticated localhost requests
VERITAS_AUTH_LOCALHOST_ROLE read-only Role for unauthenticated localhost (read-only, agent, admin)
VERITAS_ADMIN_KEY (required) Admin API key (≥ 32 characters)
VERITAS_API_KEYS (none) Additional API keys. Format: name:key:role,name2:key2:role2
CORS_ORIGINS http://localhost:3000,... Allowed CORS origins
TRUST_PROXY (unset) Set when behind a reverse proxy

Auth Modes

Mode Config Use Case
Localhost bypass VERITAS_AUTH_LOCALHOST_BYPASS=true Local development. MCP server on same machine as VK.
API key (agent) VK_API_KEY=<key> + key in VERITAS_API_KEYS with agent role Production. MCP server may be remote.
API key (admin) VK_API_KEY=<admin-key> Full access. Use sparingly.
Auth disabled VERITAS_AUTH_ENABLED=false Testing only. Never in production.

Recommended default: Localhost bypass for local dev, agent-role API key for production.


Tool Catalog

Task Management (6 tools)

Tool Description Required Inputs Key Options
list_tasks List all tasks, optionally filtered (none) status, type, project, sprint
get_task Get task by ID (supports partial match) id
create_task Create a new task title type, priority, project, sprint
update_task Update task fields id title, description, status, type, priority, project, sprint
archive_task Archive a completed task id
delete_task Permanently delete a task id
Examples

List high-priority tasks:

{
  "name": "list_tasks",
  "arguments": { "status": "in-progress", "project": "rubicon" }
}

→ Returns JSON array of matching tasks.

Create a task:

{
  "name": "create_task",
  "arguments": {
    "title": "Fix auth token refresh",
    "type": "code",
    "priority": "high",
    "project": "rubicon",
    "sprint": "sprint-1"
  }
}

→ Returns Task created: task_20260302_abc123\n{...task JSON...}

Update task status:

{
  "name": "update_task",
  "arguments": { "id": "abc123", "status": "done" }
}

→ Partial IDs work — matches the last 6+ characters.

Input Enums

  • status: todo · in-progress · blocked · done
  • type: code · research · content · automation
  • priority: low · medium · high

Agent Control (2 tools)

Tool Description Required Inputs Key Options
start_agent Start a coding agent on a task id agent (claude-code, amp, copilot, gemini)
stop_agent Stop a running agent id

Constraints: Only works on tasks with type: "code" that already have a git worktree attached.

Examples

Start Claude Code on a task:

{
  "name": "start_agent",
  "arguments": { "id": "abc123", "agent": "claude-code" }
}

→ Returns attempt ID and worktree path.

Stop a running agent:

{
  "name": "stop_agent",
  "arguments": { "id": "abc123" }
}

Automation (4 tools)

Tool Description Required Inputs Key Options
list_pending_automation List tasks pending automation (none)
list_running_automation List currently executing automations (none)
start_automation Start automation for a task id sessionKey
complete_automation Mark automation complete or failed id result, failed
Examples

Start automation:

{
  "name": "start_automation",
  "arguments": { "id": "abc123" }
}

→ Returns task title, attempt ID, and description.

Mark as failed:

{
  "name": "complete_automation",
  "arguments": { "id": "abc123", "result": "Timeout after 30s", "failed": true }
}

Notifications (3 tools)

Tool Description Required Inputs Key Options
create_notification Create a notification (Teams delivery) type, title, message taskId
get_pending_notifications Get pending notifications (none)
check_notifications Scan tasks and create notifications (none)

Notification Types

info · error · milestone · high_priority · agent_complete · agent_failed · needs_review · task_done

Examples

Create a milestone notification:

{
  "name": "create_notification",
  "arguments": {
    "type": "milestone",
    "title": "Sprint 3 Complete",
    "message": "All 12 tasks archived. Velocity: 34 points.",
    "taskId": "abc123"
  }
}

Summaries (2 tools)

Tool Description Required Inputs Key Options
get_summary Board overview (status counts, projects, high-priority) (none)
get_memory_summary Task summary formatted for agent memory files (none) hours (default: 24)
Examples

Get last 48 hours of activity:

{
  "name": "get_memory_summary",
  "arguments": { "hours": 48 }
}

→ Returns markdown-formatted summary (completed tasks, active high-priority, project progress).


Sprint Management (9 tools)

Tool Description Required Inputs Key Options
list_sprints List all sprints (none) includeHidden
get_sprint Get sprint by ID id
create_sprint Create a new sprint label description
update_sprint Update sprint fields id label, description, isHidden
delete_sprint Delete a sprint id force
can_delete_sprint Check if sprint can be deleted id
reorder_sprints Reorder sprints orderedIds
get_archive_suggestions Sprints ready to archive (none)
close_sprint Archive all completed tasks in sprint id
Examples

Create a sprint:

{
  "name": "create_sprint",
  "arguments": { "label": "Sprint 4", "description": "Auth hardening & MCP docs" }
}

Safe delete check:

{
  "name": "can_delete_sprint",
  "arguments": { "id": "sprint-3" }
}

→ Returns { "canDelete": true, "referenceCount": 0 } or tells you how many tasks still reference it.

Close a sprint (archive completed tasks):

{
  "name": "close_sprint",
  "arguments": { "id": "sprint-3" }
}

→ Returns count and IDs of archived tasks.

Force Delete Behavior

The delete_sprint tool supports a force flag that controls how deletion handles referenced items.

Default behavior (force: false or omitted):

When a sprint is referenced by one or more tasks (i.e., tasks have sprint: "sprint-id"), the delete is blocked. The server checks for references via can_delete_sprint internally and returns a response indicating the item cannot be deleted along with the reference count. This prevents accidental data loss — tasks would lose their sprint assignment.

Recommended workflow:

  1. Call can_delete_sprint first to check if any tasks reference the sprint.
  2. If referenceCount > 0, either reassign those tasks to another sprint or use force: true.
  3. Call delete_sprint with or without force based on the check.
// Step 1: Check
{ "name": "can_delete_sprint", "arguments": { "id": "sprint-3" } }
// → { "allowed": true, "referenceCount": 0 }  OR  { "allowed": false, "referenceCount": 5 }

// Step 2: Delete (safe)
{ "name": "delete_sprint", "arguments": { "id": "sprint-3" } }

// Step 2 alt: Force delete (skips reference check)
{ "name": "delete_sprint", "arguments": { "id": "sprint-3", "force": true } }

Force behavior (force: true):

The reference check is skipped entirely. The sprint is deleted regardless of how many tasks reference it. Tasks that referenced the deleted sprint will retain their sprint field value, but it will point to a non-existent sprint (orphaned reference). This is useful for cleanup scenarios where you know the references are stale or the tasks will be updated separately.

This applies to all managed lists (sprints, projects, task-types) — they all use the same ManagedListService base class with identical force delete semantics. The MCP server supports force delete on /api/projects/:id?force=true and /api/task-types/:id?force=true as well.


Project Management (7 tools) New in v4.0

Full project lifecycle management from MCP — create, organize, and track projects without leaving your agent context.

Tool Description Required Inputs Key Options
list_projects List all projects (none) includeHidden
get_project Get a project by ID id
create_project Create a new project label description, color
update_project Update project fields id label, description, isHidden
delete_project Delete a project id force
get_project_stats Task counts and status breakdown id
reorder_projects Reorder projects in the sidebar orderedIds
Examples

Create a project:

{
  "name": "create_project",
  "arguments": {
    "label": "Rubicon",
    "description": "Industrial safety AI platform",
    "color": "#8B5CF6"
  }
}

Get project task breakdown:

{
  "name": "get_project_stats",
  "arguments": { "id": "rubicon" }
}

→ Returns:

{
  "id": "rubicon",
  "label": "Rubicon",
  "total": 24,
  "byStatus": { "todo": 8, "in-progress": 5, "blocked": 2, "done": 9 }
}

Reorder projects:

{
  "name": "reorder_projects",
  "arguments": { "orderedIds": ["rubicon", "brainmeld", "dealmeld"] }
}

Force-delete a project with tasks still assigned:

{
  "name": "delete_project",
  "arguments": { "id": "old-project", "force": true }
}

Comment Management (3 tools) New in v4.0

Comment tools for task discussion threads, enabling agents to participate in async review notes.

Tool Description Required Inputs Key Options
add_comment Add a comment to a task taskId, text agent
list_comments List comments for a task taskId
delete_comment Delete a task comment by ID taskId, commentId
Examples

Add a code review comment:

{
  "name": "add_comment",
  "arguments": {
    "taskId": "task_20260321_abc",
    "text": "Auth token refresh looks good. One nit: the 5-minute buffer could be configurable.",
    "agent": "TARS"
  }
}

List comments on a task:

{
  "name": "list_comments",
  "arguments": { "taskId": "task_20260321_abc" }
}

→ Returns array of { id, content, author, createdAt, updatedAt }.

Delete a comment:

{
  "name": "delete_comment",
  "arguments": {
    "taskId": "task_20260321_abc",
    "commentId": "cmt_xyz789"
  }
}

Resources

The MCP server also exposes MCP Resources — read-only data accessible via kanban:// URIs:

URI Description
kanban://tasks All tasks (JSON)
kanban://tasks/active Tasks with status in-progress or blocked
kanban://task/{id} Individual task by ID

Resources are useful for MCP clients that support resource browsing (e.g., Claude Desktop's resource panel).


Security Model

Principle of Least Privilege

  1. Use agent role, not admin. The agent role can create/update/archive tasks and run automations. It cannot manage users or server config.
  2. One key per integration. Create separate API keys for each MCP client:
    VERITAS_API_KEYS=cursor-mcp:vk_cur_abc:agent,claude-desktop:vk_cd_xyz:agent
    
  3. Localhost bypass is for dev only. In production, disable it: VERITAS_AUTH_LOCALHOST_BYPASS=false.

Token Boundaries

  • API keys are passed via the X-API-Key header by the shared VK API client. The server also accepts Authorization: Bearer <key> for direct HTTP callers.
  • The MCP server reads VK_API_KEY from its environment and includes it in every HTTP request to VK.
  • Keys never appear in MCP tool inputs/outputs — they stay in the transport layer.

What the MCP Server Cannot Do

  • No direct file access — all operations go through the VK REST API.
  • No shell execution — the start_agent tool tells VK to start an agent; it doesn't spawn processes itself.
  • No outbound network — the MCP server only talks to VK_API_URL. It has no internet access.

Error Handling & Troubleshooting

Error Response Format

All tool errors return:

{
  "content": [{ "type": "text", "text": "Error: <message>" }],
  "isError": true
}

Common Errors

Error Cause Fix
Task not found: abc123 ID doesn't match any task Check the ID — partial match needs ≥ 6 characters
Can only start agents on code tasks Tried start_agent on a non-code task Change task type to code first
Task needs a worktree first start_agent on a task without git worktree Create a worktree via the VK UI or API before starting an agent
fetch failed / ECONNREFUSED VK server not running Start the server: pnpm dev
401 Unauthorized Invalid or missing API key Check VK_API_KEY in MCP config and VERITAS_API_KEYS in server .env
Unknown tool: <name> Typo in tool name Check the Tool Catalog for exact names

Debugging

# Run MCP server with stderr visible (it logs to stderr)
VK_API_URL=http://localhost:3001 VK_API_KEY=your-agent-api-key node mcp/dist/index.js

# Test a specific tool via stdin
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_tasks","arguments":{}}}' | \
  VK_API_URL=http://localhost:3001 node mcp/dist/index.js 2>/dev/null | jq .

# Check VK server health
curl -s http://localhost:3001/api/health | jq .

Observability & Telemetry

The MCP server itself is stateless and does not emit telemetry. Observability comes from the VK server:

  • Telemetry eventsrun.started, run.completed, run.tokens events via /api/telemetry/events.
  • Time tracking/api/tasks/{id}/time/start and /api/tasks/{id}/time/stop.
  • Agent status/api/agent/status shows active agents on the VK dashboard.
  • Squad chat/api/chat/squad for agent coordination messages.

Configure telemetry retention in server/.env:

Variable Default Description
TELEMETRY_RETENTION_DAYS 30 Days to keep event files
TELEMETRY_COMPRESS_DAYS 7 Days before NDJSON files are gzip-compressed

Versioning & Compatibility

Component Version Notes
MCP server package 4.0.0 Matches VK server version
MCP SDK 1.27.1 @modelcontextprotocol/sdk
MCP protocol 2024-11-05 Latest stable spec
Node.js ≥ 22 Matches the repo runtime
TypeScript 6.0+ Build dependency only

Breaking change policy:

  • Tool names and required inputs are stable within a major version.
  • New tools may be added in minor versions.
  • Tool removal or input schema changes only happen in major versions.
  • The MCP server version tracks the VK server version (@veritas-kanban/mcp).

FAQ

Q: Does the MCP server need its own port? No. It communicates via stdio (stdin/stdout). The MCP client spawns it as a child process. No ports needed.

Q: Can I run multiple MCP server instances? Yes. Each MCP client spawns its own instance. They're stateless — no coordination needed.

Q: What happens if the VK server is down? Tool calls will fail with connection errors (ECONNREFUSED). The MCP server stays alive and will work again once VK is reachable.

Q: Can I use this with non-Claude MCP clients? Yes. Any MCP-compatible client works — Cursor, Cline, Continue, Zed, or custom implementations. The config format may differ slightly per client.

Q: How do I add a new tool?

  1. Create or edit a file in mcp/src/tools/.
  2. Define the tool schema and handler.
  3. Export from the module and import in mcp/src/index.ts.
  4. Rebuild: cd mcp && pnpm build.

Q: Is there an SSE/HTTP transport option? Not currently. The server uses stdio only. If you need HTTP transport, use the VK REST API directly.

Q: How do partial task IDs work? The findTask utility matches the last N characters of a task ID (minimum 6). If multiple tasks match, it returns the first match. Use more characters for precision.


Last updated: 2026-05-11 · VK v4.3.1 · 36 tools / 8 categories