agent-work-mcp
A server that orchestrates long-running coding-agent work sessions with budgets, dependency graphs, human decisions, validation, and handoffs.
Start and manage OUTSIDE_MODE (autonomous, budgeted) and DESK_MODE (human-in-the-loop) work sessions
Track a persistent work graph of units with dependencies, estimates, acceptance criteria, and parallel-safe execution
Automatically decide what to do next (execute, wait, plan, or stop) based on budget, readiness, and policy
Report progress, completions with validation evidence, failures, blockers, and checkpoints per unit
Queue and resolve human decisions that block work; independent work continues
Pause, resume, stop, or fail sessions; recover interrupted runs from checkpoints
Generate detailed handoffs and session reports (outcome, budget, decisions, validation, scope changes)
Optional hosted Streamable HTTP server with OAuth 2.1 and bearer-token auth for remote MCP clients
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@agent-work-mcp Start an outside session with a 90-minute budget to complete the login feature."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
agent-work-mcp
Let your coding agent work for hours while you're away, and come back to a clean handoff.
agent-work-mcp is a Model Context Protocol server that
orchestrates agent work. It gives a coding agent (Claude Code, or any MCP client) a
persistent work session with a time budget, a dependency graph of work, a
human decision queue, required validation, and an exact handoff.
It has two modes:
OUTSIDE_MODE: bounded autonomous execution, for when you are away. The agent owns the phase goal until the budget is spent or no meaningful executable work remains. It never stops to ask you a question. It records the question, parks the work that depends on the answer, and keeps going with everything else.
DESK_MODE: human-in-the-loop execution, for when you are back. You start from the handoff, answer the queued decisions (most blocking first), and resume in either mode.
Status: v0.1. The core session lifecycle is implemented and tested end to end: 218 tests, covering the MCP boundary and the built binary over stdio. It is not yet published to npm. GitHub and Todoist integrations are deliberately not part of v0.1.
Contents
Related MCP server: Agent Harness Kit
Why
Coding agents are good at individual tasks and bad at owning an outcome over several hours without supervision. The failure modes are predictable:
Stopping too early. The agent finishes one task and ends its turn, although the budget and plenty of work remain.
Blocking on questions. It asks "JWT or sessions?" and then waits hours for an answer nobody is there to give.
Guessing instead. It makes an architectural or product decision on its own.
Busywork. It invents work to fill the time it was given.
Unverified "done". It declares work finished without checking it.
Lost context. It crashes or runs out of context and leaves no record of where it was.
agent-work-mcp moves the parts an agent can't hold reliably in its context window into a
small, persistent control plane, and enforces the rules on the server rather than only in
a prompt.
How it works
The server is a control plane. It does not run models or edit files. Your agent is the execution plane: it reads the code, makes changes, runs tests, and spawns its own subagents. The agent pulls work from the server and reports back.
flowchart LR
A["Coding agent<br/>(Claude Code, any MCP client)"] -- "MCP tools (stdio)" --> M["mcp/<br/>thin tool layer"]
M --> C["core/<br/>orchestrator · state machine · work graph<br/>decisions · budget · execution policy<br/>handoff · report"]
C --> P[("adapters/persistence<br/>.agent-work/ JSON revisions")]
C --> G["adapters/project<br/>git status + docs"]The OUTSIDE loop, from the agent's point of view:
sequenceDiagram
participant Agent
participant Server as agent-work-mcp
Agent->>Server: start_session(mode: outside, goal, budgetMinutes)
Server-->>Agent: sessionId, repo snapshot, docs to read
Note over Agent: analyze the repository
Agent->>Server: update_work_graph(units, projectContext)
loop until next_work says stop
Agent->>Server: next_work
Server-->>Agent: execute (direct or parallel) · wait · stop
Note over Agent: do the unit, run the checks
Agent->>Server: report_work(completed + validation evidence)
opt human judgment needed
Agent->>Server: request_decision(question, affected units)
Server-->>Agent: independent work that can continue
end
end
Agent->>Server: get_handoffSession states (simplified; the full transition table is in docs/state-model.md):
stateDiagram-v2
[*] --> analyzing: start_session
analyzing --> planning: update_work_graph
planning --> running: next_work (execute)
running --> planning: report_work
planning --> validating: completed work needs validation
validating --> planning: report_work
planning --> waiting_for_human: all remaining work waits on decisions
planning --> blocked: remaining work blocked or failed
planning --> resumable: budget spent, work remains
planning --> completed: everything done and validated
running --> paused: pause_session
paused --> running: resume_session
waiting_for_human --> resumable: record_decision
resumable --> planning: resume_session
blocked --> planning: resume_session
completed --> [*]Guarantees
These rules are enforced by the server, not just stated in a prompt.
Rule | How it is enforced |
A finished task never ends the run |
|
The budget is for the session, not per task | A 4-hour unit may use 4 hours of a 5-hour budget; a 20-minute unit takes 20 minutes and the next work is picked. Estimates never consume budget; only elapsed time does. |
Never invent work to use up budget | Units added after the initial plan need a rationale and appear in the report as mid-session scope. Unused budget is reported as a normal outcome. |
Never invent decisions |
|
Decisions don't stop independent work | A decision gates only its affected units and their dependents. The run halts as |
Parallelism must be earned | Subagents are used only for provably isolated units whose time savings beat the overhead. Remaining budget is not an input: more budget never means more agents. |
Smaller verified change over speculation | Completing a unit requires validation evidence. Before halting with unvalidated work, an integration validation unit runs. |
Survive interruption | State is written as immutable revision files with an atomic compare-and-swap that is safe across processes. Recovery restores in-flight units from their checkpoints. |
Install
Requirements: Node.js 20 or newer, and an MCP client.
git clone https://github.com/yurikaza/agent-work-mcp.gitcd agent-work-mcp && npm install && npm run buildThis produces dist/cli.js, a stdio MCP server. Check it:
node dist/cli.js --versionConnect it to your agent
Claude Code
Run this inside the project you want the agent to work on. The local scope keeps the
registration private to you and to that project, so no machine-specific paths end up in the
project's repository.
claude mcp add agent-work --scope local -e AGENT_WORK_PROJECT_ROOT="$PWD" -- node /absolute/path/to/agent-work-mcp/dist/cli.jsVerify:
claude mcp get agent-workIf your Claude Code is launched from a GUI with a minimal PATH, use the absolute path to
node (which node) instead of node. Start a new Claude Code session afterwards: sessions
that were already open do not pick up new servers.
Other MCP clients
Most clients accept an mcpServers entry like this:
{
"mcpServers": {
"agent-work": {
"command": "node",
"args": ["/absolute/path/to/agent-work-mcp/dist/cli.js"],
"env": { "AGENT_WORK_PROJECT_ROOT": "/absolute/path/to/your/project" }
}
}
}The server speaks the MCP 2026-07-28 revision and also serves clients that open with the
2025-era initialize handshake.
Using OUTSIDE_MODE
Before you leave, ask your agent something like:
Start an agent-work OUTSIDE session. Goal: "finish team invitations (phase 2)". Budget: 180 minutes. Exit criteria: "invites can be sent and accepted". Constraint: "don't touch billing". Follow next_work until it says stop, then give me the handoff.
What happens:
start_sessioncreates the session and returns asessionId, a git snapshot (branch, head, uncommitted files) and the docs to read first. The operating rules for both modes reach the agent through the server's MCPinstructions.Analysis. The agent reads the docs and code, then submits the plan with
update_work_graph. The project context it records (summary, key files, test and build commands) is what makes the later handoff useful:{ "sessionId": "ses_…", "projectContext": { "summary": "Express + Postgres monolith; migrations via knex.", "keyFiles": ["src/app.ts", "src/db/migrations"], "commands": { "test": "npm test", "build": "npm run build" } }, "units": [ { "id": "invite-model", "title": "Invite table and model", "estimateMinutes": 30, "acceptance": ["migration runs up and down"], "touches": ["src/db", "src/models"] }, { "id": "invite-email", "title": "Send invitation email", "dependsOn": ["invite-model"], "estimateMinutes": 40, "touches": ["src/mail"] }, { "id": "invite-accept", "title": "Accept-invite endpoint", "dependsOn": ["invite-model"], "estimateMinutes": 45, "touches": ["src/routes/invites.ts"] } ] }The loop.
next_workreturnsexecute(with a direct or parallel dispatch and the reasons for it),wait(units still in flight),plan(the work graph isn't submitted yet), orstop.Reporting. After each unit the agent calls
report_workwith evidence:{ "sessionId": "ses_…", "unitId": "invite-model", "outcome": "completed", "summary": "Migration and model added", "validation": { "passed": true, "checks": [{ "name": "npm test", "passed": true }] }, "artifacts": ["src/db/migrations/20260919_invites.ts"] }A failing check counts as a failed attempt. After three attempts the unit is marked
failed, and the units that depend on it wait for a human.Questions. When human judgment is needed, the agent calls
request_decisionwith the question, why it matters, options, an optional recommendation, and the affected units. It gets back the independent work that can continue.Integration validation. When no other work is executable, a validation unit runs the full checks across the completed units before the run is allowed to halt.
Stop. The run ends with one of these reasons:
Stop reason
Meaning
Session afterwards
completedEverything done and validated
completedwaiting_for_humanAll remaining work waits on at least one open decision
waiting_for_humanblockedRemaining work is blocked or failed
blockedbudget_exhaustedBudget spent and executable work remains
resumablebudget_insufficientNo ready unit fits the remaining budget
resumable
Using DESK_MODE
When you are back:
Show me the agent-work handoff for the last session and walk me through the open decisions.
The agent calls list_sessions, then get_handoff and get_decisions. You answer, and the
agent records it with record_decision (decidedBy is required). The resolution is
attached to every affected unit, so whoever executes it later sees your answer. Then:
resume_sessionwithmode: "desk"works through the remaining units with you, one at a time;resume_sessionwithmode: "outside"andaddBudgetMinuteshands the work back to autonomy.
You can also start in DESK_MODE directly with start_session(mode: "desk"). DESK_MODE
consumes no autonomous budget and always dispatches one unit at a time.
What a handoff looks like
This is real output from the server (only the session id is shortened). An OUTSIDE session was given 180 minutes. The agent hit a product question, parked the one unit that depended on it, finished and validated everything else, and stopped:
# Handoff: Team invitations
Session `ses_3f9c2a7b…` · mode **outside** · state **waiting_for_human** — 1 remaining unit(s) cannot proceed; waiting on decision(s) dec-1.
Budget: 96m used of 180m (84m left)
Goal: Add team invitations
## Next actions
1. Decide dec-1: Should invitations expire? (blocks 1 unit(s)) → record_decision
## Decisions needed (1)
- **dec-1** [product, blocks 1] Should invitations expire?
- Why it matters: Changes the accept flow and how long a leaked link stays valid.
- Option `7d`: Expire after 7 days
- Option `never`: Never expire
- Agent suggestion (not applied): 7d: limits exposure of forwarded links.
- Blocks: invite-accept
## Blocked / waiting
- invite-accept: Accept-invite endpoint — waiting_on_decision (decision:dec-1)
## Completed
- invite-model: Invite table and model — Migration and model added
- invite-email: Send invitation email — Send invitation email done
- audit-log: Audit log for team changes — Audit log for team changes done
- validate-1: Integration validation #1 — Full suite, build and lint green
## Project context
Express + Postgres monolith; migrations via knex.
Key files: src/app.ts, src/db/migrations
- test: `npm test`
- build: `npm run build`
## Repository
Branch feat/invites @ 9c1e4b7a2d5f; 0 uncommitted file(s)The 84 unused minutes are not a failure. Nothing meaningful was left that did not depend on your answer, so the agent stopped rather than inventing work.
Concepts
Work session and budget
A session is one campaign toward one goal (usually the current project phase) in one
project. In OUTSIDE_MODE it has a total wall-clock budget. The clock runs only while
the session is active (analyzing, planning, running, validating); paused and
halted time is not charged. A unit may start when its estimate fits the remaining budget,
with 25% tolerance and a 10-minute reserve kept for the final validation. Units without an
estimate may start while enough budget remains. Estimates are never limits and never
consume budget.
Work graph
A dependency graph of work units. Each unit has an id, a title, dependsOn edges,
optional decisionIds, an optional estimate, acceptance criteria, and touches (the paths
it changes). The server rejects bad ids, unknown references and cycles, with nothing
applied. It derives each unit's readiness and root causes (for example
decision:dec-1, blocker:deploy, failure:migrate), and schedules units that unblock the
most work first.
Human decisions
A decision is a persistent question with why it matters, options, the agent's recommendation (stored, never applied), and the units it blocks. The queue is sorted by how much work each decision blocks. Only a human resolves it; see docs/decision-model.md.
Execution policy: direct vs parallel
Units are dispatched in parallel only when all of these hold:
the mode is outside;
the units declare
touchesand estimates, and areparallelSafe;they don't share a workstream or overlapping paths with each other or with in-flight work;
the net saving beats the overhead:
Σestimates − max(estimate) − (n − 1) × (10 + 5) ≥ 30minutes.
For example, two isolated 60-minute units run in parallel (net 45m), while two 20-minute units don't (net 5m). The main agent takes the largest unit, subagents take the rest in isolated worktrees, and the main agent integrates and owns validation. It never holds more than one unit.
Validation
Completing a unit requires evidence: at least one check, or an explicit
notApplicableReason. Before a run halts with unvalidated completed work, a session-level
validation unit re-checks the exit criteria and the acceptance criteria of the covered
units together. If that validation fails, fix units run first and then validation re-runs.
A validation unit that fails or is blocked halts the session as blocked for a human.
Interruption and recovery
Every state change is persisted before the tool returns, so any crash leaves a readable
session. A session whose agent has been silent for longer than the stale threshold
(60 minutes, or 1.5× the largest in-flight estimate) shows liveness: stale.
pause_session, stop_session and resume_session recover it without charging the silent
gap, and resume_session returns in-flight units to the queue with their last checkpoint.
Any other call after a silence is treated as the agent carrying on, and the gap is charged.
Over-charging a dead agent only stops the session early, whereas under-charging would
break the budget bound.
Tools
Sixteen high-level tools. All except start_session and list_sessions take the explicit
sessionId handle, because MCP 2026-07-28 has no protocol-level session.
Tool | Purpose |
| Create a session ( |
| Find sessions with state, liveness, budget and open decisions. |
| State, budget, unit counts, in-flight units, runs. |
| Goal, exit criteria, constraints, progress, recorded project context. |
| Units with readiness and root causes, plus edges. |
| Add or update units, cancel or reopen units, record project context. Applied all-or-nothing. |
| Claim the next work: |
|
|
| Queue a question for a human; get the independent work back. |
| The queue, most blocking first. |
| A human's answer (or a withdrawal). |
| Pause; the budget clock stops and claims are kept. |
| Resume from the handoff; optionally switch mode or add budget. |
| End the run and return the report; |
| Where to pick up, as Markdown plus structured data. |
| Outcome, budget use, evidence, decisions, parallelism, next steps. |
Every tool has an input and output schema and annotations. Rule violations come back as
readable tool errors (CODE: message) that the model can act on. The full reference,
including error codes, is in docs/mcp-tools.md.
Hosted (Streamable HTTP)
dist/http.js serves the same 16 tools over Streamable HTTP for use from
Claude Cloud sessions, routines, or any remote MCP client. It is the second
entry point; stdio stays the local default.
AGENT_WORK_TOKEN=<long random secret> AGENT_WORK_STATE_DIR=/data PORT=8787 npm start
curl http://localhost:8787/healthzPOST /mcp— MCP endpoint. RequiresAuthorization: Bearer <token>(orAGENT_WORK_ALLOW_UNAUTHENTICATED=1, never in production).GET /healthz— liveness, no auth.AGENT_WORK_STATE_DIR— where sessions are stored; mount a persistent volume there. There is no project inspector in hosted mode: passprojectContexttoupdate_work_graph, and use a repo URL asprojectRoot.
railway.json describes a Railway service: Railpack build, node dist/http.js,
health check on /healthz. Set AGENT_WORK_TOKEN and mount a volume at
/data with AGENT_WORK_STATE_DIR=/data.
OAuth 2.1
Some clients — claude.ai custom connectors among them — will not carry a static bearer token, so the hosted server also runs the smallest authorization server that satisfies the MCP authorization spec. It is the resource server and its own issuer; there is nothing else to deploy.
Route | What it does |
| RFC 9728 metadata: this server's resource id and issuer. |
| RFC 8414 metadata: endpoints, |
| RFC 7591 dynamic client registration. Public clients only, no client secret. |
| A one-field HTML form. The field is |
|
|
There is one resource owner — you — and one credential, the server secret. The
/authorize form asks for exactly that, so "log in" means "paste the token you
already have". The same secret still works as a static bearer on /mcp, which
is what tests, curl and local clients use.
Access tokens last 1 hour, refresh tokens 30 days, authorization codes 60
seconds. Tokens and codes are stored under <state dir>/auth/ as the SHA-256 of
their value and never in plaintext, so a leaked state directory cannot be
replayed. Refresh tokens rotate: a stolen one is worth at most one use.
To attach it to claude.ai, add https://<host>/mcp as a custom connector and
paste the server secret into the form that opens. Set AGENT_WORK_PUBLIC_URL
in production: without it the issuer and resource identifiers are derived from
the request's Host/X-Forwarded-* headers, which is right for local use but
lets a spoofed Host shape the discovery documents.
Configuration and storage
Variable | Default | Meaning |
| the server's working directory | Default project root for new sessions. |
|
| Where session state is stored. |
| — | Hosted only: bearer token for |
| derived from the request | Hosted only: public origin used as the OAuth issuer and resource id. |
|
| Hosted only: port for |
The state directory writes its own .gitignore, so it never shows up in git status:
.agent-work/
├── .gitignore # "*"
├── sessions/<sessionId>/ # immutable revisions; the last 5 are kept
│ └── <revision>.json
├── projects/<hash>/<n>.json # per-project start sequence (one active session per project)
└── auth/ # hosted only: OAuth clients, codes and tokens (hashed)Each revision is published with an atomic hard link, so two processes can never both
overwrite the same revision, and a crash never leaves a half-written file or a stale lock.
Policy defaults (parallelism thresholds, budget reserve, retry limit, staleness) live in
src/core/policy/policy.ts and can be overridden when you
construct the orchestrator yourself.
Using the core as a library
The orchestration core has no dependency on MCP, so it can back a CLI or another protocol:
import { Orchestrator, FileSessionRepository } from 'agent-work-mcp';
const o = new Orchestrator({
repository: new FileSessionRepository('.agent-work'),
policy: { maxParallel: 2 },
});
const { session } = await o.startSession({ mode: 'outside', goal: 'Ship phase 1', budgetMinutes: 120 });
const next = await o.nextWork(session.sessionId); // { action: 'plan', … } until a graph is submittedDevelopment
npm testnpm run typecheck && npm run buildsrc/
├── core/ # no MCP, no I/O
│ ├── model/ # session types, state machine, work graph, decisions, budget
│ ├── policy/ # execution policy (direct vs parallel), defaults
│ ├── orchestrator.ts, evaluate.ts, handoff.ts, report.ts, views.ts
│ ├── contracts.ts # zod schemas for commands and views
│ └── ports.ts # SessionRepository, Clock, IdGenerator, ProjectInspector
├── adapters/ # file + memory persistence, git/docs inspector
├── mcp/server.ts # tool registration only
└── cli.ts # stdio entry point
test/ # 218 testsThe tests cover the state machine, the work graph, the execution policy, the budget, the full OUTSIDE and DESK lifecycles, decision behavior, interruption and resume, persistence across restarts and concurrent writers, lifecycle invariants under 120 seeded random operation sequences, the MCP surface over an in-memory transport, and the built binary over stdio.
Issues and pull requests are welcome. Please keep the core free of transport and I/O details, and add tests alongside behavior changes.
Limitations
Agent compliance is instructed, not verified. The server enforces its rules, but a real end-to-end run with Claude Code against a test repository has not been automated yet.
"Human" is enforced by state, not identity. Decisions can't be recorded during an active OUTSIDE run. In DESK_MODE the server can't tell whether the human or the agent answered.
Silence is charged unless you recover explicitly. If an agent dies and your first call is not
pause_session,stop_sessionorresume_session, the silent time counts against the budget. Long units should send progress reports at least hourly.Two narrow storage edge cases. A crash in the millisecond between creating a session and claiming its project slot leaves an orphan session that blocks new starts on that project for up to 60 minutes. Pruning of old revisions could, in theory, hide an update if a writer stalls while five or more newer revisions land.
Not on npm yet. Install from source.
Roadmap
An automated end-to-end run with a real agent (headless Claude Code) against a test repository.
MCP prompts that start each mode (
/outside,/desk).Work sources: GitHub issues and Todoist tasks mapped into the work graph.
An
AgentExecutorport so the server can dispatch work to headless agents directly.Streamable HTTP transport for remote use.
Documentation
Document | Covers |
Layers, ports, control flow, durability | |
States, transition table, budget, liveness | |
Units, validation rules, readiness, scheduling, parallelism | |
Raising, resolving and ordering decisions | |
OUTSIDE loop, DESK flow, pause/resume/stop, handoff, report | |
Tool reference and error codes | |
v0.1 plan and technology choices |
License
Available Tools
16 toolsget_decisionsGet decisionsARead-only
The decision queue, most blocking first, with why each matters, options, the agent suggestion and blocked/independent work.
Inputs: sessionId (required), status. Returns: mode, state, decisions, sessionId, +1 more
get_handoffGet handoffARead-only
Exactly where to pick up: state and why, decisions needed (most blocking first), in-flight checkpoints, ready units, blocked units with causes, completed work, project context, repository state and ordered next actions. Start DESK_MODE here.
Inputs: sessionId (required). Returns: mode, notes, phase, state, +15 more
get_phaseInspect phaseARead-only
The phase goal, exit criteria and constraints this session owns, progress toward it, and the project context recorded during analysis.
Inputs: sessionId (required). Returns: phase, state, progress, sessionId, +2 more
get_sessionInspect sessionARead-only
Current state, mode, budget, unit counts, in-flight units and run history of one session.
Inputs: sessionId (required). Returns: session, guidance
get_session_reportGet session reportARead-only
Session report: outcome, budget used and why any was left unused, completed work with validation evidence, unresolved work, decisions, parallel dispatches and their rationale, scope added mid-session, and next steps.
Inputs: sessionId (required). Returns: runs, phase, budget, outcome, +12 more
get_work_graphInspect work graphARead-only
Units with status, derived readiness and root causes (decision:, blocker:, failure:, cancelled:), plus dependency edges. Filter: all | remaining | ready | in_progress | done.
Inputs: sessionId (required), filter. Returns: edges, state, units, sessionId, +1 more
list_sessionsList work sessionsARead-only
List recorded sessions (newest first) with state, budget and open decision counts. Use to find a session to inspect or resume.
Inputs: projectRoot, includeTerminal. Returns: sessions
next_workNext workA
Re-evaluate the graph, budget and policy and claim the next work. action "execute" = do the dispatched units (direct, or parallel with subagents when justified); "wait" = finish in-flight units first; "plan" = analysis/graph needed; "stop" = the run is over (budget spent, waiting for human, blocked, or completed). Call after every report_work. Only "stop" ends an OUTSIDE_MODE run.
Inputs: sessionId (required). Returns: mode, state, action, budget, +6 more
pause_sessionPause sessionA
Pause an active session. Stops the budget clock and keeps in-flight claims. Optional handoff notes.
Inputs: sessionId (required), notes, reason. Returns: session, guidance
record_decisionRecord human decisionA
Record a decision made by a human (or withdraw a question that no longer applies). Only call with the human's explicit answer. Refused while an OUTSIDE_MODE run is active. Releases the units the decision gated.
Inputs: decidedBy (required), sessionId (required), decisionId (required), choice, +2 more. Returns: state, decision, guidance, sessionId, +1 more
report_workReport workA
Report a claimed unit: progress (checkpoint), completed (requires validation evidence), failed, blocked (requires blocker), or released. Completed with failing checks counts as a failed attempt. Then call next_work: a finished unit never ends the session.
Inputs: unitId (required), outcome (required), summary (required), sessionId (required), +4 more. Returns: unit, state, guidance, sessionId, +1 more
request_decisionRequest human decisionA
Queue a question that needs human judgment (architecture, product, scope, security...). Never guess instead. Affected units wait; everything else continues. Returns impact and the independent work that can proceed. Does not block and does not wait for an answer.
Inputs: question (required), sessionId (required), whyItMatters (required), options, +4 more. Returns: state, decision, guidance, sessionId, +1 more
resume_sessionResume sessionA
Resume a paused, halted or interrupted session from its handoff. Optionally switch mode (desk/outside) and add budget. Recovers in-flight units of an interrupted run (they return to pending with their checkpoints). Returns the handoff.
Inputs: sessionId (required), mode, takeover, addBudgetMinutes. Returns: handoff, session, guidance, releasedUnitIds, +1 more
start_sessionStart work sessionA
Start a work session for a project goal. mode "outside" = bounded autonomous run (no human; requires budgetMinutes, the total wall-clock autonomy for the whole session, not per task). mode "desk" = human in the loop. Returns a sessionId handle (pass it to every other tool), a repository snapshot and analysis instructions. Next: analyze the project, then update_work_graph.
Inputs: goal (required), mode (required), phaseTitle, constraints, +3 more. Returns: session, guidance, snapshot, otherSessions
stop_sessionStop sessionADestructive
End the current run. In-flight units are released with their checkpoints and the session is classified (resumable, waiting_for_human, blocked or completed). markFailed: true ends it permanently as failed. Returns the final report.
Inputs: reason (required), sessionId (required), notes, markFailed. Returns: report, session
update_work_graphUpdate work graphA
Add or update units (upsert by id), cancel or reopen units, and record project context (summary, key files, commands). The first call submits the initial plan. Rejected as a whole if ids, references or dependencies are invalid or cyclic. Units added after the initial plan need a rationale. Never add work only to use remaining budget.
Inputs: sessionId (required), units, cancel, reopen, +1 more. Returns: added, state, updated, guidance, +5 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Each tool targets a distinct aspect of session and work-graph management, with clear separation between session lifecycle (start/pause/resume/stop), state inspection (get_session, get_phase, get_handoff, get_session_report), work graph manipulation (get/update_work_graph, next/report_work), and decision handling (request/get/record_decision). No two tools appear to do the same thing.
All 16 tools follow a consistent snake_case verb_noun pattern (e.g., pause_session, update_work_graph, request_decision). The verbs are imperative and match the action taken, with no mixing of conventions or vague generic names.
At 16 tools, the set is slightly above the typical 3–15 range, but each tool serves a distinct and necessary function for managing complex agent work sessions, covering lifecycle, graph, decisions, and reporting. The count feels justified rather than bloated.
The tool surface fully covers the session lifecycle (start, pause, resume, stop), work graph operations (create/update, query, claim, report), decision management (request, query, record), and reporting (handoff, session report). No obvious dead ends or missing operations for the stated domain.
Maintenance
Related MCP Connectors
Design, build and run teams of AI agents with checked handoffs between them.
AI work orchestration for plans, tasks, teams, and coding-agent dispatch.
Hosted runtime for persistent agent teams, durable workflows, memory, schedules, and goals.
One shared project for a team's coding agents: decisions, a task board and handoffs.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceEnables AI coding providers to run structured multi-agent workflows with shared documents, tracked tasks, handoffs, and health-gated completion.29 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI coding providers to run structured multi-agent workflows with specifications, tracked tasks, handoffs, approvals, and health-gated completion across supported coding environments.29 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI coding providers to run structured multi-agent workflows with specs, tracked tasks, handoffs, health gates, and audited repair mode.29 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI coding providers to run structured multi-agent workflows with document drafting, task tracking, handoffs, and health-gated completion.29 npmMIT