# 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