Agents & Actions
MCP Tools
Spruce exposes a set of tools over the Model Context Protocol (MCP) so that agents like Claude Code can read and write artifacts without leaving their terminal session. The tools are namespaced under mcp__spruce__ and cover the same operations available through the Spruce UI.
Tool categories
Artifact tools
| Tool | What it does |
|---|---|
artifact_get | Fetch an artifact by ID; returns fields + body |
artifact_search | Search by text, type, or field filters |
artifact_create | Create a new artifact from a template |
artifact_update | Update fields or replace the body |
artifact_body_edit | Targeted string replacement in the body |
Comment tools
| Tool | What it does |
|---|---|
artifact_comment_list | List comments on an artifact |
artifact_comment_add | Add a top-level comment |
artifact_comment_claim | Claim a comment for the agent's session (stamps processingBy, fetches full thread) |
artifact_comment_reply | Reply to an existing comment |
artifact_comment_resolve | Mark a comment resolved |
Template tools
| Tool | What it does |
|---|---|
template_list | List all templates in the project |
template_get | Fetch a template by name or by artifact ID |
The claim-first-then-reply pattern
Agents working on comments follow a specific loop:
- Call
artifact_comment_claimwith asession_idand a shortnotedescribing the work. This stampsprocessingByon the comment, which the Spruce UI renders as a "being addressed" spinner with the note next to it. - Do the work (edit code, run tests, etc.).
- Call
artifact_comment_replywith the response. The claim auto-clears on reply.
This loop prevents duplicate responses when multiple agent sessions are listening, and gives the user a live indicator of what the agent is doing.
Comment origins
Every comment created via these tools is tagged with origin: 'agent'; comments created by users through the UI have origin: 'user'. The tag is set by the write path (agents can't spoof it). See Comments for the user-facing behaviour.
Related
- Actions — how the MCP connection gets wired up when launching an agent, plus comment forwarding via
forward: [comment-added]. - Comments — the user-facing comment system.
- MCP Tool Reference — full tool-by-tool reference with parameters.