API surface — MCP tools, REST endpoints, and coverage

The current catalog of MCP tools and REST endpoints exposed by the Studio Host, plus which surface (the VS Code extension, autonomous agents, or neither) actually reaches each one. Ground truth (verified directly against source, not the tables below — the tables illustrate shape/category, not an exhaustive per-tool listing): 117 nm_v1_* MCP tools, 72 of them dispatched in-process to autonomous agents, 15 nms_v1_* external-caller tools, and 214 REST routes.

Frozen design principles, request/response schemas, and the error envelope format live in the internal MCP v1 contract — this page is the practical, currently-verified catalog and supersedes tool counts anywhere they’ve drifted.

External caller surface (`nms_v1_*`)

These 15 tools are the recommended entry point for external MCP clients — Claude Code, Cursor, scripts, CI agents. They cover the full human-in-the-loop lifecycle at a goal-centric level, without requiring knowledge of work units, branches, or the internal DAG.

Naming: nms_v1_* (NodalMerge Studio v1) vs. nm_v1_* (NodalMerge v1). The extra s marks the Studio-level abstraction layer. Both namespaces share the same host and the same error envelope format.

Goal management

Tool	Purpose
`nms_v1_goal_run`	Start a new goal — creates a work unit, execution session, and enqueues the orchestrator in one call. Returns `goalId` and `sessionId`.
`nms_v1_goal_list`	List all goals with current status.
`nms_v1_goal_status`	Detailed status for one goal, including pending clarifications, an unresolved failure if the goal is dead-lettered (with which recovery actions currently apply), and session state.
`nms_v1_goal_cancel`	Cancel a goal and its entire subtree. Completed or merged work units are left untouched.
`nms_v1_goal_requeue`	Un-cancel a goal and resume it — the inverse of `nms_v1_goal_cancel`. A leaf work unit is re-queued for a worker; a fan-out parent re-attempts reconciliation. Optional override params resupply LLM credentials without starting a new orchestrator loop.
`nms_v1_goal_pause`	Pause a goal and all its active agents.
`nms_v1_goal_resume`	Resume a paused goal. Optionally inject a steering message.
`nms_v1_goal_recover`	Recover a dead-lettered goal — `action` is one of `retry`, `retry_with_context`, `continue` (`MaxIterationsExceeded` only), or `replan`. Resolves the goal’s own latest dead-letter entry internally; no entry ID needed.

Clarifications

Tool	Purpose
`nms_v1_clarification_respond`	Answer a pending agent clarification request.

Results

Tool	Purpose
`nms_v1_results_get`	List merge proposals for a goal with status, summary, confidence, and files touched.
`nms_v1_results_apply`	Apply an approved proposal (`ReadyForReview` or `Approved`).

Repository registration

Tool	Purpose
`nms_v1_repo_register`	Register a local git repository path. Returns a `repositoryId`. Idempotent.
`nms_v1_repo_list`	List all registered repositories and their IDs.

Workspace / feedback

Tool	Purpose
`nms_v1_workspace_status`	Goal counts by status, active agent count, pending clarification count.
`nms_v1_feedback_record`	Record a human feedback note as a durable Constraint artifact.

Typical external-caller flow

nms_v1_repo_register        → repositoryId
nms_v1_goal_run             → goalId, sessionId
poll nms_v1_goal_status     → check status / pendingClarifications
nms_v1_clarification_respond (if needed)
nms_v1_results_get          → proposalId when status = ReadyForReview
nms_v1_results_apply        → done

REST equivalents exist for all these operations (/studio/goals, /studio/merges, /studio/repositories, /studio/clarifications), but the nms_v1_* MCP surface is the preferred path for MCP-native clients.

How the transports relate

VS Code Extension  ──HTTP──▶  REST endpoints  ──┐
                                                  ├──▶  Shared command services  ──▶  NodalMerge DAG
External MCP client ──MCP───▶  MCP tools  ───────┘
Orchestrator/Worker loops ──in-process call──▶  same MCP tool handlers

A capability that has both a REST endpoint and an MCP tool calls the same command service either way — they can’t drift in behavior. Agents never make HTTP calls to their own host’s REST API; they call the tool dispatcher in-process. A REST endpoint with no frontend caller can still be heavily used — just by agents, via the MCP tool it shares a command service with.

MCP tool catalog (117 tools — categories below are not exhaustive)

✅ = dispatched in-process to orchestrator/worker agents · — = MCP-client, REST, or extension only.

Projection

Tool	Dispatched	Purpose
`nm_v1_projection_get`	✅	Get a projection by type and compression level
`nm_v1_projection_list`	—	List available projection types and levels

Work unit

Tool	Dispatched	Purpose
`nm_v1_workunit_create`	✅	Create a work unit (goal + branch, optional parent/scope/deps/reviewPolicy)
`nm_v1_workunit_get`	✅	Get a work unit by id
`nm_v1_workunit_update`	✅	Update status or assigned agent
`nm_v1_workunit_list`	✅	List work units, optionally filtered by branch

Task

Tool	Dispatched	Purpose
`nm_v1_task_create`	✅	Create a task (intent only) under a work unit
`nm_v1_task_update`	✅	Update task title/description/status/priority
`nm_v1_task_list`	✅	List tasks, optionally by work unit
`nm_v1_task_assign`	✅	Assign a task to an agent

Branch

Tool	Dispatched	Purpose
`nm_v1_branch_create`	✅	Create a branch
`nm_v1_branch_checkout`	—	Check out a branch
`nm_v1_branch_list`	✅	List branches
`nm_v1_branch_status`	✅	Branch status for agents

Merge

Tool	Dispatched	Purpose
`nm_v1_merge_propose`	✅	Submit a proposal — diff, lineage, execution event, status transition
`nm_v1_merge_validate`	✅	Validate a draft proposal, moves it to ReadyForReview
`nm_v1_merge_review`	✅	Approve/reject (supports `automated=true` for the reviewer-agent path)
`nm_v1_merge_apply`	✅	Apply an approved proposal — runs review-policy/promotion-branch gate logic

Dead-letter

Tool	Dispatched	Purpose
`nm_v1_dead_letter_list`	—	List every dead-letter entry across all work units
`nm_v1_dead_letter_get`	—	Get a single dead-letter entry by its own entry ID
`nm_v1_dead_letter_by_work_unit`	—	Get the latest dead-letter entry for a work unit, if any
`nm_v1_dead_letter_history`	—	Full failure history for a work unit, oldest first
`nm_v1_dead_letter_retry`	—	Retry a dead-lettered work unit (optional credential override)
`nm_v1_dead_letter_retry_with_context`	—	Retry with a human correction folded into the goal, bypassing the attempt cap
`nm_v1_dead_letter_replan`	—	Re-plan a failed fan-out slice into fresh sub-slices; original marked `Cancelled`
`nm_v1_dead_letter_continue`	—	Resume the same work unit with reconstructed prior context (`MaxIterationsExceeded` only)

Deliberately not dispatched to orchestrator/worker agents — these are human-initiated recovery actions on an already-failed, already-exited work unit, not something a running agent would ever call on itself. The recommended external-caller flow reaches the same capability through nms_v1_goal_status (surfaces an unresolved failure and which actions apply) and nms_v1_goal_recover (resolves the goal’s own latest entry internally — no entry ID needed) instead of these detailed, entry-ID-based tools.

Replay

Tool	Dispatched	Purpose
`nm_v1_replay_range`	—	Inspect a history range for a branch
`nm_v1_replay_rollback`	—	Roll back a branch to a known-good state
`nm_v1_replay_inspect`	—	Human-friendly replay summary

State / Known Good

Tool	Dispatched	Purpose
`nm_v1_state_markKnownGood`	—	Mark current branch state as known-good
`nm_v1_state_findKnownGood`	—	Find known-good states for a branch
`nm_v1_state_checkoutKnownGood`	—	Restore a branch to a known-good state

Snapshot

Tool	Dispatched	Purpose
`nm_v1_snapshot_get`	✅	Agent execution snapshot (goal, task, failure count, next action)
`nm_v1_snapshot_compare`	—	Compare two agents’ snapshots

Agent

Tool	Dispatched	Purpose
`nm_v1_agent_spawn`	✅	Spawn an agent for a work unit
`nm_v1_agent_pause`	—	Pause an agent
`nm_v1_agent_resume`	—	Resume a paused agent
`nm_v1_agent_status`	✅	Get agent status
`nm_v1_agent_stop`	✅	Stop an agent

Agents cannot pause/resume themselves or each other — those are human/extension-only actions today.

Tool	Dispatched	Purpose
`nm_v1_workspace_read` / `_write` / `_delete` / `_list` / `_diff` / `_exists`	✅ all	Branch-scoped file operations (write/delete respect `fileScope`)
`nm_v1_workspace_summary`	✅	Control-tower summary (active work units, agents, merges, failures)
`nm_v1_workspace_symbol_definition` / `_symbol_references` / `_symbol_implementation`	✅ all	Compiler-backed symbol navigation
`nm_v1_workspace_build` / `_test` / `_exec` / `_run` / `_run_stop`	✅ all	Run build / test / build+test+lint / app run / run-stop on a branch
`nm_v1_workspace_exec_status`	✅	Latest persisted execution result for a branch
`nm_v1_workspace_path`	✅	Branch working-directory filesystem path
`nm_v1_workspace_profile_get` / `_profile_rescan`	✅ both	Detected project roots/stacks and resolved build/test/run command profile

Routing rule: when semantic tools are allowed in a profile, they are the authoritative path for symbol definition/reference/implementation questions. Use nm_v1_workspace_search for text/content questions, not symbol relationship resolution.

Scheduler

Tool	Dispatched	Purpose
`nm_v1_scheduler_enqueue`	✅	Queue a work unit for a profile (parallel execution, used by Experiments)
`nm_v1_scheduler_pending`	✅	List pending scheduler queue items
`nm_v1_clarification_request`	✅	Request human clarification and optionally pause execution

Intent

Tool	Dispatched	Purpose
`nm_v1_intent_record`	✅	Record a change intent for conflict detection

Artifact

Tool	Dispatched	Purpose
`nm_v1_artifact_record`	✅	Record a knowledge note (Research/Decision/Constraint)
`nm_v1_artifact_query`	✅	Search artifacts by type/keyword across a work unit’s ancestry
`nm_v1_artifact_list`	✅	Full artifact chain for a work unit, ancestors included by default

Goal, Decision, Evidence, Trajectory, Hypothesis (Phase 6.7+)

Namespace	Tools	Purpose
`nm_v1_goal_*`	`create`, `list`	Decision-centric goal nodes
`nm_v1_decision_*`	`record`, `list`	Record Accepted/Rejected/Deferred/Superseded against a proposal
`nm_v1_evidence_*`	`attach`, `list`	Attach/list build/test evidence for a work unit
`nm_v1_trajectory_*`	`create`, `replay`	Record lifecycle phases; replay in Linear / BranchExplorer / Counterfactual mode
`nm_v1_hypothesis_*`	`fork`, `list`	Fork a work unit/proposal with a typed fork (Code/Reasoning/Model/Research/Architecture/Library/Product)
`nm_v1_reasoning_*`	`record`	Record a reasoning commit from an orchestration step
`nm_v1_model_*`	`compare`, `replay`	Compare two proposals’ diverged files/overlap; list all proposals for a work unit grouped for model comparison

None of these are dispatched to autonomous agents yet.

Phase 7 — REST-only, no MCP tool at all

Capability	REST endpoint	Why it matters
Experiments (create/list/get)	`POST/GET /studio/experiments`, `GET /studio/experiments/{id}`	An MCP client (or an agent) cannot launch a multi-fork experiment on its own
Steering (redirect, fork-from-node)	`POST /studio/steering/redirect`, `POST /studio/steering/fork-from-node`	An agent cannot steer itself or another agent — human/extension only
Counterfactuals (create)	`POST /studio/counterfactuals`	Read-only counterfactual viewing exists via `nm_v1_trajectory_replay` (mode=Counterfactual); creating one does not have a tool
Review Policy on create	`reviewPolicy` field on `POST /studio/workunits`	`nm_v1_workunit_create` has no `reviewPolicy` parameter — MCP-created work units always default to `HumanRequired`
Promotion branches	`usePromotionBranch`/`candidateBranchId` on `POST /studio/options`, `POST /studio/branches/candidate/promote`	No tool to toggle or promote
Fork from Known Good	`POST /studio/state/{stateId}/fork`	An MCP client/agent can checkout (mutate) a known-good state via `nm_v1_state_checkoutKnownGood`, but can’t fork a new work unit from one without writing its own `seedFromBranchId`-style call

REST endpoint catalog (214 routes)

Grouped by resource area; StudioRestEndpoints.cs is the single file that registers all of these.

Workspace files & execution

branchId is a query parameter on every one of these, not a route segment — branch IDs like merge/{workUnitId} contain a literal /, which a {branchId} route segment can never match.

POST /studio/workspace/build|test|exec|run?branchId=... — trigger build / test / build+test+lint / run on a branch
POST /studio/workspace/run/stop?branchId=... — stop one/all branch run processes
GET /studio/workspace/exec/latest?branchId=... — latest execution result
GET /studio/workspace/exec/output?branchId=...&resultId=... — cached stdout/stderr for a past result
GET /studio/workspace/path?branchId=... — branch working directory path
GET /studio/workspace/profile?branchId=... — detected workspace roots/stacks/commands
POST /studio/workspace/profile/rescan?branchId=... — refresh detected workspace profile
POST /studio/workspace/switch — force a repository resync against current disk content (see Guides → Repository virtualization)

Work units, tasks, agents, merges, branches

Work units: GET/POST /studio/workunits, GET /studio/workunits/{id} (+/children, /artifacts, /orchestration-events, /intents, /conflict-report, /proposal-dag), POST /studio/workunits/{id}/cancel, POST /studio/workunits/{id}/requeue (un-cancel and resume; optional credential overrides), POST /studio/stop-all
Tasks: GET /studio/tasks, GET /studio/tasks/{id}, POST /studio/tasks, PUT /studio/tasks/{id}, POST /studio/tasks/{id}/assign
Agents: GET /studio/agents (?all=true for all), POST /studio/agents/spawn, GET /studio/agents/{id}/status, POST /studio/agents/{id}/pause|resume|stop
Merges: GET/POST /studio/merges, GET /studio/merges/{id} (+/constituents, /file-changes), POST /studio/merges/{id}/validate|review|apply (review body: { decision: "Approved"|"Rejected" } — there is no separate /accept//reject route), GET /studio/merges/compare?ids=, POST /studio/merges/{id}/branch, POST /studio/merges/{id}/restore-workspace
Branches: GET /studio/branches, POST /studio/branches, POST /studio/branches/{id}/checkout, GET /studio/branches/{id}/status, POST /studio/branches/candidate/promote
Candidate & task conflicts (reconciliation — see Concepts → Trust & autonomy § Reconciling candidate conflicts): GET /studio/branches/candidate/conflicts, POST /studio/branches/candidate/conflicts/{id}/reconcile, POST /studio/branches/candidate/conflicts/{id}/resolve, GET /studio/workunits/{id}/task-conflicts, POST /studio/workunits/{id}/task-conflicts/{conflictId}/reconcile, POST /studio/workunits/{id}/task-conflicts/{conflictId}/resolve. The work unit’s own /proposal-dag (listed above) now also surfaces reconciliation edges, and GET /studio/merges/{id}/constituents resolves a reconciled proposal back to its source proposals.

Known-good states & cache management

POST /studio/state/markKnownGood, GET /studio/state/knownGood/{branchId}, POST /studio/state/checkoutKnownGood, POST /studio/state/{stateId}/fork (fork a new work unit seeded from a checkpoint’s snapshot branch — the extension’s “Fork from Known Good”)
Branch directory cache (WorkspaceCacheManager, REST-only — see Guides → Repository virtualization): POST /studio/cache/evict?workUnitId=..., POST /studio/cache/materialize?workUnitId=..., POST /studio/cache/evict/orphaned, POST /studio/cache/gc?dryRun=...

Dead-letter queue

GET /studio/dead-letter, GET /studio/dead-letter/{id}, GET /studio/dead-letter/by-work-unit/{workUnitId}, GET /studio/dead-letter/history/{workUnitId} (full failure history, oldest first)
POST /studio/dead-letter/{id}/retry, POST /studio/dead-letter/{id}/retry-with-context (folds a human correction into the goal, bypasses the normal attempt cap), POST /studio/dead-letter/{id}/replan (decompose the failed slice into fresh sub-slices, mark original Cancelled — never gated on attempt count since it never resumes the failed work unit), POST /studio/dead-letter/{id}/continue (MaxIterationsExceeded only — resume the SAME work unit with reconstructed prior context and a fresh iteration budget)

Everything else

Agent profiles: GET /studio/agent-profiles, GET /studio/agent-profiles/{id}, POST/PUT /studio/agent-profiles/{id}
Scheduler: GET /studio/scheduler/pending|awaiting-resume, POST /studio/scheduler/{workUnitId}/resume, POST /studio/scheduler/resume-all, POST /studio/scheduler/enqueue
Clarifications: GET /studio/clarifications/awaiting, POST /studio/clarifications/request, POST /studio/clarifications/{workUnitId}/respond
Sessions & events: GET/POST /studio/sessions, GET /studio/sessions/{id}, POST /studio/sessions/{id}/pause|resume|abandon, GET /studio/sessions/{id}/workunits|events|state, GET /studio/events/{id}
Artifacts: GET/POST /studio/artifacts, GET /studio/artifacts/{id} (+/children), POST /studio/artifacts/{id}/elevate (widen a repo-scoped constraint to all repositories)
Insights & findings (see Guides → Knowledge & constraints): GET /studio/findings (?status=), POST /studio/findings/{id}/review ({ decision, notes } — promote/dismiss/investigating), POST /studio/findings/import, POST /studio/insights/detect-findings (deterministic pattern rules), POST /studio/insights/llm-scan (body is a resolved LLM config; routes to an HTTP one-shot or a claude-cli/codex-cli one-shot by provider; returns { findings, rawCliOutput })
Constraints: GET /studio/constraints (?repositoryId=; each row labeled with reach + appliesToAllRepos + local enabled), POST /studio/constraints (manual add — { title, body, reach: "Workgroup"|"Private", repoSpecific } → a global constraint at the chosen 2×2 scope), POST /studio/constraints/{id}/toggle ({ disabled } — peer-private local suppression, not replicated), POST /studio/constraints/{id}/scope ({ reach, repoSpecific } — set the full 2×2 scope and re-route; generalizes /elevate), GET /studio/constraints/proposed (work-unit-owned observer/agent constraints eligible for promotion, each flagged promoted), POST /studio/constraints/{id}/promote ({ reach?, repoSpecific? } — mint a global copy of a lineage constraint stamped with promotedFromArtifactId; idempotent, returns the existing promotion if already promoted)
Options/policies/projections/snapshots: GET/POST /studio/options, GET /studio/policies, GET /studio/projections, GET /studio/projections/{type}, GET /studio/snapshots/{agentId} (+/compare/{otherAgentId})
Replay: GET /studio/replay/timeline (+/{branchId}), GET /studio/replay/range/{branchId}, POST /studio/replay/rollback/{branchId}, GET /studio/replay/inspect/{branchId}
Goals/decisions/evidence/trajectory/hypotheses/reasoning/models: GET/POST /studio/goals, GET/POST /studio/decisions, GET /studio/evidence + POST /studio/evidence/attach, GET /studio/trajectory/replay + POST /studio/trajectory, GET /studio/hypotheses + POST /studio/hypotheses/fork, POST /studio/reasoning, GET /studio/models/compare|replay/{workUnitId}
Phase 7: GET/POST /studio/experiments, GET /studio/experiments/{id}, POST /studio/steering/redirect|fork-from-node, POST /studio/counterfactuals

See Concepts → Trust & autonomy for the human-in-the-loop rationale behind these boundaries.

Introduction

How Studio works

Configuration and extension

Control Tower UI

API surface

API surface — MCP tools & REST

API surface — MCP tools, REST endpoints, and coverage

External caller surface (`nms_v1_*`)

Goal management

Clarifications

Results

Repository registration

Workspace / feedback

Typical external-caller flow

How the transports relate

MCP tool catalog (117 tools — categories below are not exhaustive)

Projection

Work unit

Task

Branch

Merge

Dead-letter

Replay

State / Known Good

Snapshot

Agent

Workspace — file I/O, execution, semantic navigation, and profile

Scheduler

Intent

Artifact

Goal, Decision, Evidence, Trajectory, Hypothesis (Phase 6.7+)

Phase 7 — REST-only, no MCP tool at all

REST endpoint catalog (214 routes)

Workspace files & execution

Work units, tasks, agents, merges, branches

Known-good states & cache management

Dead-letter queue

Everything else

​API surface — MCP tools, REST endpoints, and coverage

​External caller surface (nms_v1_*)

​Goal management

​Clarifications

​Results

​Repository registration

​Workspace / feedback

​Typical external-caller flow

​How the transports relate

​MCP tool catalog (117 tools — categories below are not exhaustive)

​Projection

​Work unit

​Task

​Branch

​Merge

​Dead-letter

​Replay

​State / Known Good

​Snapshot

​Agent

​Workspace — file I/O, execution, semantic navigation, and profile

​Scheduler

​Intent

​Artifact

​Goal, Decision, Evidence, Trajectory, Hypothesis (Phase 6.7+)

​Phase 7 — REST-only, no MCP tool at all

​REST endpoint catalog (214 routes)

​Workspace files & execution

​Work units, tasks, agents, merges, branches

​Known-good states & cache management

​Dead-letter queue

​Everything else

API surface — MCP tools, REST endpoints, and coverage

External caller surface (`nms_v1_*`)

Goal management

Clarifications

Results

Repository registration

Workspace / feedback

Typical external-caller flow

How the transports relate

MCP tool catalog (117 tools — categories below are not exhaustive)

Projection

Work unit

Task

Branch

Merge

Dead-letter

Replay

State / Known Good

Snapshot

Agent

Workspace — file I/O, execution, semantic navigation, and profile

Scheduler

Intent

Artifact

Goal, Decision, Evidence, Trajectory, Hypothesis (Phase 6.7+)

Phase 7 — REST-only, no MCP tool at all

REST endpoint catalog (214 routes)

Workspace files & execution

Work units, tasks, agents, merges, branches

Known-good states & cache management

Dead-letter queue

Everything else