Content
# delega-mcp
MCP server for [Delega](https://delega.dev) — 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:
```
[#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:
```
[#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:
```
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`:
```
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:
```
[#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.
## Links
- [Delega](https://delega.dev) — Main site
- [GitHub](https://github.com/delega-dev/delega-mcp) — Source code
- [API Docs](https://delega.dev/docs) — REST API reference
## License
MIT
