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.
- When to Use the MCP Server
- Architecture
- Quickstart
- Configuration Reference
- Tool Catalog
- Resources
- Security Model
- Error Handling & Troubleshooting
- Observability & Telemetry
- Versioning & Compatibility
- FAQ
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.
┌─────────────────────────────────────────────────┐
│ 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.
- Node.js ≥ 22
- The Veritas Kanban server running (
pnpm devor production) - pnpm (for building from source)
# 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 clientAdd 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: 36Verify 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.
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.jsProduction 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.jsRecommended companion for OpenAI-related development work:
codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcpPair 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.
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_KEYso 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 withoutVK_API_KEY, but write tools need a key unlessVERITAS_AUTH_LOCALHOST_ROLEis set toagentoradmin.
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. |
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 |
| 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 | 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.
- status:
todo·in-progress·blocked·done - type:
code·research·content·automation - priority:
low·medium·high
| 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" }
}| 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 }
}| 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) | — |
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"
}
}| 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).
| 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.
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:
- Call
can_delete_sprintfirst to check if any tasks reference the sprint. - If
referenceCount > 0, either reassign those tasks to another sprint or useforce: true. - Call
delete_sprintwith or withoutforcebased 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.
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 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"
}
}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).
- Use
agentrole, notadmin. Theagentrole can create/update/archive tasks and run automations. It cannot manage users or server config. - 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 - Localhost bypass is for dev only. In production, disable it:
VERITAS_AUTH_LOCALHOST_BYPASS=false.
- API keys are passed via the
X-API-Keyheader by the shared VK API client. The server also acceptsAuthorization: Bearer <key>for direct HTTP callers. - The MCP server reads
VK_API_KEYfrom 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.
- No direct file access — all operations go through the VK REST API.
- No shell execution — the
start_agenttool 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.
All tool errors return:
{
"content": [{ "type": "text", "text": "Error: <message>" }],
"isError": true
}| 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 |
# 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 .The MCP server itself is stateless and does not emit telemetry. Observability comes from the VK server:
- Telemetry events —
run.started,run.completed,run.tokensevents via/api/telemetry/events. - Time tracking —
/api/tasks/{id}/time/startand/api/tasks/{id}/time/stop. - Agent status —
/api/agent/statusshows active agents on the VK dashboard. - Squad chat —
/api/chat/squadfor 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 |
| 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).
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?
- Create or edit a file in
mcp/src/tools/. - Define the tool schema and handler.
- Export from the module and import in
mcp/src/index.ts. - 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