io.github.delega-dev/delega

Official

by delega-dev · TypeScript

Task management API for AI agents. Create, delegate, and track tasks via MCP.

Task management API for AI agents to create, delegate, and track tasks.

Topics

ai-agentsmcp-servermodel-context-protocoltask-managementdelegadelegationmcp

README.md8 KBView on GitHub

delega-mcp

MCP server for Delega — the task handoff layer for AI agents.

Connect any MCP-compatible client (Claude Code, Cursor, Codex, etc.) to Delega and manage tasks, projects, and agents through natural language.

Install

bash

npm install -g @delega-dev/mcp

Configure

Add to your MCP client config (e.g. Claude Code claude_code_config.json):

json

{
  "mcpServers": {
    "delega": {
      "command": "npx",
      "args": ["-y", "@delega-dev/mcp"],
      "env": {
        "DELEGA_API_URL": "https://api.delega.dev",
        "DELEGA_AGENT_KEY": "dlg_your_agent_key_here"
      }
    }
  }
}

Environment Variables

Variable	Default	Description
`DELEGA_API_URL`	`https://api.delega.dev`	Delega API endpoint. Defaults to the hosted API; custom `/api`-style endpoints (e.g. `http://localhost:18890`) are an advanced override.
`DELEGA_AGENT_KEY`	(none)	Agent API key for authenticated requests. Preferred for MCP configs; if both key env vars are set, this one wins.
`DELEGA_API_KEY`	(none)	Fallback alias accepted so the MCP, CLI, and SDK can share one env var when needed.
`DELEGA_REVEAL_AGENT_KEYS`	`0`	⚠️ Development only. Set to `1` to print full API keys in tool output. Never enable in production: a prompt-injected agent could exfiltrate keys from `register_agent` or `list_agents` responses.

Use https://api.delega.dev as the URL.

Security Notes

Non-local DELEGA_API_URL values must use https://.
Agent keys are passed through environment variables rather than command-line arguments, which avoids process-list leakage.
MCP tool output redacts full agent API keys by default.
Do not set DELEGA_REVEAL_AGENT_KEYS=1 in production. This flag exists for initial setup only. In production, a prompt-injected agent could exfiltrate keys from register_agent or list_agents tool output. Keys are returned once at creation time; register a replacement agent if you need a new key.

Tools

Tool	Description
`list_tasks`	List tasks, filter by project, label, due date, completion
`get_task`	Get full task details including subtasks and task links
`link_task`	Attach a branch, commit, PR, or URL link to a task
`list_task_links`	List branch, commit, PR, and URL links attached to a task
`create_task`	Create a new task
`list_recurrences`	List recurring task templates
`create_recurring_task`	Create a recurring task template (`daily`, `weekly`, `monthly`, or `yearly`)
`update_recurrence`	Update a recurring task template, including pausing/resuming with `active`
`delete_recurrence`	Delete a recurring task template; existing spawned task instances remain
`update_task`	Update task fields (incl. `assigned_to_agent_id`)
`assign_task`	Assign a task to an agent (or pass `null` to unassign)
`delegate_task`	Delegate a task: create a child task linked to a parent (parent status flips to `delegated`). Use this for multi-agent handoffs — `assign_task` does not create a delegation chain.
`get_task_chain`	Return the full delegation chain for a task (root + descendants, sorted by depth)
`update_task_context`	Merge keys into a task's persistent context blob (deep merge, not replace), recording provenance source
`get_task_context`	Read a task's persistent context blob, optionally with per-key provenance
`get_context_history`	Read the append-only provenance ledger for a task's context
`find_duplicate_tasks`	Check whether proposed task content is similar to existing open tasks (TF-IDF + cosine similarity). Call before `create_task` to avoid redundant work.
`get_usage`	Return quota + rate-limit info. Hosted API only (`api.delega.dev`); custom endpoints receive a clear error.
`claim_task`	Claim the next available task from the queue for exclusive processing (work-queue semantics). Lease-based: default 300s, configurable 30-3600. Returns the task or reports an empty queue. Hosted API only.
`heartbeat_task`	Extend the lease on a claimed task. Call periodically while working so the claim isn't reclaimed. Hosted API only.
`release_task`	Release a claimed task back to the queue without completing it. Hosted API only.
`set_task_state`	Report `working`, `waiting_input`, or `errored` on a claimed task without extending the lease. Hosted API only.
`complete_task`	Mark a task as completed
`delete_task`	Delete a task permanently
`add_comment`	Add a comment to a task
`list_projects`	List all projects
`get_stats`	Get task statistics
`list_agents`	List registered agents
`register_agent`	Register a new agent (returns API key), optionally with a role preset
`set_agent_role`	Set an agent's role: `worker`, `coordinator`, or `admin` (admin key required)
`delete_agent`	Delete an agent (refused if agent has active tasks)
`list_webhooks`	List all webhooks (admin only)
`create_webhook`	Create a webhook for event notifications, including `task.linked` (admin only)
`delete_webhook`	Delete a webhook by ID (admin only)

Task output format

Task-returning tools (list_tasks, get_task, create_task, update_task, assign_task) render each task with assignment metadata when available:

code

[#42] Ship the release
  Description: Cut RC, tag, push to npm
  Project: Delega
  Labels: release
  Priority: 3
  Due: 2026-04-20
  Assigned to: Coordinator (#7)
  Created by: planner (#3)
  Completed: no

Assigned to / Created by / Completed by lines are emitted only when the underlying field is populated. Custom /api-style endpoints return a nested agent object so the assignee renders as <display_name> (#id); the hosted api.delega.dev API returns the raw agent ID so it renders as #<id>.

Tasks that are part of a delegation chain also surface the chain metadata:

code

[#def] Draft intro
  Status: delegated
  Assigned to: Drafter (#3)
  Created by: Coordinator (#7)
  Delegation: depth 1, parent #abc, root #abc
  Delegated by: Coordinator (#7)
  Completed: no
  Context keys: step, findings (2)

Single-task tools (get_task, create_task, update_task, assign_task, delegate_task, update_task_context) use a detail render that pretty-prints the full context blob (truncated at 2000 chars). list_tasks uses the concise list render which shows Context keys: … instead.

get_task also shows attached task links when present:

code

  Links:
    branch: delega-dev/delega-api phase-3-github — https://github.com/delega-dev/delega-api/tree/phase-3-github
    pr: delega-dev/delega-api 42 — https://github.com/delega-dev/delega-api/pull/42

Delegation chains

get_task_chain returns the full parent/child chain for any task in the chain. Output is indented by delegation_depth:

code

Delegation chain (root #abc, depth 2, 2/4 complete):
  [#abc] Write report (depth 0, delegated)
    [#def] Draft intro (depth 1, completed)
    [#jkl] Draft conclusion (depth 1, pending)
      [#ghi] Research sources (depth 2, completed)

Nodes are sorted by depth then creation order (matching the API's response ordering).

Recurring tasks

Recurring task tools manage templates. The hosted scheduler creates normal task instances from those templates; completing an instance does not delete or pause the recurrence.

list_recurrences, create_recurring_task, and update_recurrence render templates with their rule, next due timestamp, active state, skip-if-open behavior, and available agent metadata:

code

[#weekly-report] Weekly report
  Rule: weekly, weekday 1
  Timezone: America/Chicago
  Next due: 2026-06-22T14:00:00Z
  Active: yes
  Skip if open: yes
  Assigned to: Reporter (#7)

Hosted API

Delega is a hosted service. Point DELEGA_API_URL at https://api.delega.dev — free up to 1,000 tasks/month.

License

MIT

Install

Configuration

Environment variables

DELEGA_API_KEYrequiredsecret

Agent API key from your Delega dashboard (delega.dev/dashboard)

DELEGA_API_URL

Delega API endpoint. Defaults to https://api.delega.dev (the hosted API). Custom /api-style endpoints are an advanced override.

claude_desktop_config.json

{
  "mcpServers": {
    "delega": {
      "command": "npx",
      "args": [
        "-y",
        "@delega-dev/mcp@1.13.0"
      ],
      "env": {
        "DELEGA_API_KEY": "<YOUR_DELEGA_API_KEY>",
        "DELEGA_API_URL": "<YOUR_DELEGA_API_URL>"
      }
    }
  }
}