Content
# mcp-delegate
A tiny, **dependency-free MCP server** that lets you use the
[delegate-skills](https://github.com/amElnagdy/delegate-skills) delegation loop
(`codex-delegate` / `opencode-delegate`) from inside **Claude Desktop** — so you can say
"delegate this to codex" in a Desktop chat and have it run, then review the diff and commit,
just like in Claude Code.
## Why
Claude Desktop is **not** Claude Code. It does not auto-load skills from
`~/.claude/skills/` or `~/.agents/skills/` — Desktop extends only through **MCP servers**.
`mcp-delegate` is the bridge: it wraps the existing delegate-skills relays (no new logic) and
exposes four tools to Desktop.
## Tools exposed to Claude Desktop
| tool | what it does |
| ------------ | -------------------------------------------------------------------------------------------- |
| `delegate` | Dispatch a brief to codex/opencode via the relay; returns the structured `result.json`. |
| `read_result`| Re-read a run's `result.json` (defaults to the most recent run). |
| `git_diff` | Show the working-tree diff of a repo (what the implementer changed). |
| `git_commit` | Stage + commit verified work — the "land it" step. Only after review + re-running the gates. |
## Prerequisites
- **Node 18+** and **git** on your PATH.
- **delegate-skills installed** (the relays this server wraps):
```bash
npx --yes skills add amElnagdy/delegate-skills -a claude-code -a codex -a opencode -g --copy -y
```
- **codex and/or opencode CLI** installed and authenticated
(`codex login`, `opencode auth login`).
- **Claude Desktop** installed and run once.
## Install
```bash
# 1. Add this skill (copies SKILL.md + server.mjs + wire-config.mjs into your skills dir):
npx --yes skills add AhmedMohamedAbdEllatif/mcp-delegate -a claude-code -g --copy -y
# 2. Wire the server into Claude Desktop (idempotent; preserves the rest of your config):
node ~/.claude/skills/mcp-delegate/wire-config.mjs
# 3. Restart Claude Desktop. Look for the "delegate" server (4 tools).
```
`wire-config.mjs` adds this to `claude_desktop_config.json` (it finds its own sibling
`server.mjs`, so it works from any install path):
```json
"mcpServers": {
"delegate": { "command": "<node>", "args": ["<…/mcp-delegate/server.mjs>"] }
}
```
Manual install (without the `skills` CLI): copy `server.mjs` and `wire-config.mjs` anywhere
stable, then run `node wire-config.mjs` from that directory.
## Usage (in a Desktop chat)
You don't type a slash command — just ask in plain language:
> Delegate this to codex, in `/path/to/repo`: add a JSDoc comment to the index export.
> Don't commit. Then show me the diff.
Claude Desktop will call `delegate`, show the result + touched files, then `git_diff` for
review. After you re-run the project gates yourself, it can `git_commit`.
### `delegate` arguments
`brief` (required), `repo` (required, absolute path), `cli` (`codex` | `opencode`, default
`codex`), `model` (optional for codex; **required** for opencode fresh runs as
`provider/model`), `read_only`, `resume_last`, `timeout` (e.g. `2h`),
`skip_git_repo_check` (codex-only; for dirs not on codex's trusted list).
## Trust posture
- **No dependencies** (Node built-ins only).
- Makes **no network calls**, reads/writes **no credentials**, sends **no telemetry**.
- Shells out **only** to `node <relay.mjs>` and `git`. It cannot run arbitrary shell.
- The relay it launches shells out to `codex` / `opencode`, which **do** authenticate —
exactly as they do at the terminal. Read [`server.mjs`](./server.mjs) before wiring it in.
## Notes / limits
- `delegate` **blocks** until the implementer finishes (minutes to hours). Pass a `timeout`
(e.g. `2h`) to bound it, or cancel the tool call in Desktop.
- For **opencode fresh runs**, `model` is required (`provider/model`).
- For multi-hour runs, prefer starting the relay from a terminal yourself, then ask Desktop
to `read_result` / `git_diff` / `git_commit` against that run's out-dir.
- The relay **never commits** — the orchestrator (Desktop, via `git_commit`) does, after
reviewing the diff and re-running the gates.
## Troubleshooting
- **`delegate` server not in Desktop after restart** — confirm `wire-config.mjs` wrote
`mcpServers.delegate` and the `command` node path resolves; check Desktop's developer logs.
- **Run fails with `401 token_invalidated`** — codex/opencode auth expired; re-run
`codex login` (or `opencode auth login`) and delegate again.
- **`relay not found for cli "…"`** — delegate-skills isn't installed in any searched skill
dir; install it (see Prerequisites).
## Credits & license
Inspired by and built on [amElnagdy/delegate-skills](https://github.com/amElnagdy/delegate-skills).
MIT — see [LICENSE](./LICENSE).
