Tool Surface & Budgets
What an MCP session can actually call in Daintree: the 38 external tools, the Core and Full in-app tool sets, handback markers, reply waits and notices, mcp.surface, payload budgets, forge over MCP, resources, prompts and idempotency.
This page is the reference companion to MCP Server and Authorization & Approval. It covers what a session can call, how an orchestrator prompts agents and gets their replies back, what shape the results come back in, and the ceilings that keep those results transportable. The connect config and the audit log live on the hub page, and the authorization model on its own page.
Why the surface was cut
The external tool surface used to carry 100 tools and roughly 128 KB of schema. That is past what real MCP clients tolerate, and the failure mode was the problem: Cursor caps the tool count across every connected server and silently truncates the overflow, while GitHub Copilot's 128-tool cap is a hard blocking error. Either way the client was choosing which of Daintree's tools survived, and neither told anyone which ones it dropped.
v0.30 cut the external surface to a curated allowlist. The count is not the interesting part: the interesting part is that the choice moved back inside Daintree, where it can be reasoned about and tested, instead of being made silently by whichever client happened to connect. Each tool added since has had to argue for its slot against a fixed ceiling.
The surface is budgeted in both dimensions, because the failure is measured in bytes as much as in tools. A test asserts a ceiling of 38 external tools and a floor of 15: the floor guards the opposite failure, where a bad merge empties the list and makes every other assertion vacuous. A separate test bounds the summed descriptions across the external roster at 9,000 UTF-8 bytes, and every description at a readable floor of 120 bytes, because a few dozen tools carrying novel-length descriptions would reproduce the same truncation with a count that still looks fine.
The November 2026 source snapshot (091308f2af, 0.51 plus unreleased work) declares 38 external tools, at the ceiling. The tables below reflect that snapshot; use tools/list and mcp.surface for your running version. Workspace binding can narrow the list further. The implementation lives in the external allowlist, the Core and Full tool sets and their authorization tests.
The external tool surface
These are the tools an API-key client sees in tools/list and may dispatch through tools/call. The two sets are identical by design: nothing is withheld from the listing while staying callable. Tools ending in Owned act only on a terminal or worktree this MCP session created; see Cleaning up a session's work.
| Tool | What it does |
|---|---|
actions.list | Enumerate the calling session's authorized action surface. |
actions.search | A compact ranked shortlist of authorized actions, the answer when the tools/list schemas are too large to reason over. |
actions.getSchema | One action's manifest entry plus whatever schemas it publishes. |
actions.getContext | The live habitat context: active project, worktree, focused terminal and panel state. |
mcp.surface | This session's tool surface as versioned data with a stable hash. |
workspace.list | Every project and scratch workspace Daintree knows, open or not, with the id the Daintree-Workspace-Id header binds to and whether a view is open. Identity only. |
agent.launch | Launch an agent (built-in, user-defined or plugin-contributed) in a worktree, optionally with a first prompt, a system prompt, a handback request or a wait for its reply. |
agent.listAvailable | The authoritative effective agent registry and live launchability. Nothing the caller's own shell can answer. |
agent.listPresets | Discover effective preset ids for an agent, including project presets. Returns identity and labels without environment variables, arguments, or flags. |
agent.listAccounts | An agent's saved accounts: the ids agent.launch takes as accountId, and with a worktree, which account a launch there would use by default. Identity only, never the folder a login lives in. |
fleet.getRunStatus | A read-only supervision snapshot of the fleet broadcast run the user is running. |
recipe.list | List the workspace recipes available to this project. |
recipe.run | Run a recipe. Confirm-gated. |
skills.search | Search plugin-contributed skills. |
skills.load | Load a skill's markdown into the agent's context. |
terminal.list | Enumerate the terminal panels in the view. owned: true keeps only the ones this session created, and includeClientMetadata adds each one's client record. |
terminal.new | Create a terminal panel. |
terminal.getOutput | Read one terminal's trailing output. |
terminal.getStatus | Batched agent and process state across many terminals, optionally with output tails and a send's delivery record. |
terminal.sendCommandOwned | Submit text to a terminal this session created. Returns once queued, not when the work finishes, unless it was asked to wait for the reply. |
terminal.injectOwned | Write the active worktree's prepared context into a terminal this session created, to hand its agent a large codebase context. |
terminal.interruptOwned | Stop the turn an agent is running, keeping the panel and the conversation. |
terminal.readLastMessageOwned | Read the last reply a Claude Code agent wrote in its own transcript, including an unanswered question and its options. |
terminal.revealOwned | Bring the user to a panel this session created, switching workspace and raising the window if needed. |
terminal.placeOwned | Move a panel this session created or was handed to the background, the dock or the grid. Its process keeps running, and the user's focus never moves. |
terminal.restartOnPresetOwned | Move a panel this session launched to another preset of its agent, for a worker that hit a plan limit. Confirm-gated; scrollback is lost, and a handed-over panel is refused. |
terminal.restartOnAccountOwned | The same move to another of the agent's saved accounts. Confirm-gated, with the same refusals. |
terminal.closeOwned | Close only a terminal this session created, using the usual trash and recovery behavior. |
terminal.waitUntilIdle | A bounded long-poll until an agent's state machine leaves working. |
terminal.waitUntilIdleBatch | The same wait, fanned across several terminals. |
terminal.setClientMetadata | Attach the client's own JSON record (up to 2 KB) to a terminal, so a reconnecting client can tell panels apart. Shared by every external client, invisible in the UI, deleted with the panel, and it confers no ownership. |
worktree.list | List the project's worktrees. |
worktree.getCurrent | The active worktree. |
worktree.createWithRecipe | Create a worktree with Daintree's own creator (config copy, submodules, setup), optionally applying a recipe. |
worktree.waitForPullRequest | Wait until a worktree has a detected pull request. Detection is a cached background poll: a PR seen, not proof its agent finished. |
worktree.deleteOwned | Delete only a worktree this session created, with host confirmation and the normal deletion safeguards. |
worktree.setActive | Switch the active worktree, which moves what the user sees. |
copyTree.generateAndCopyFile | Apply the project's CopyTree policy and put the bundle on the clipboard as a file. |
Some arguments the in-app sessions use are left out of this listing, because only a caller with a pane of its own, or an assistant, can use them. agent.launch drops notify and replyLines, which ask for a notice typed into the caller's own prompt and shape it; an API-key client has no prompt. terminal.sendCommandOwned drops those two plus generation, whenBusy and queueTtlSeconds, and terminal.getStatus drops queuedSendToken: they address another assistant, or a worker the global Assistant steers, and hold a message for it, which only an assistant can do. terminal.interruptOwned and terminal.revealOwned drop generation for the same reason.
What is deliberately excluded
- Every
forge.*,git.*,file.*,project.*and browser id. An external agent driving Daintree sits in a terminal with its own shell and its owngh. The few of these that stay on MCP at all are in-app only, where no third-party client cap applies: the forge reads in Core, git activity and project checks in Full, and the assistant's ownproject.runCommandandproject.links.*in Core. - Unscoped terminal input,
terminal.closeandworktree.delete. The external session can type into, interrupt, close and delete only what it created, through the*Ownedtools.terminal.listreturns the user's own shells and other agents' terminals too, and listing a resource does not grant authority over it. - The batch tools, composites and notices.
agent.launchMany,agent.launchInNewWorktree,terminal.sendCommandMany,terminal.closeMany,terminal.notifyWhenIdleandworktree.retireOwnedare in-app only. An external client loops over the single calls and waits withwaitForReplyor the idle waits. - Fleet broadcast.
fleet.getRunStatusis read-only. To fan out, send oneterminal.sendCommandOwnedper terminal the session created and watch with a batchedterminal.getStatusor a boundedterminal.waitUntilIdleBatch. - The
github.*aliases, which were removed in v0.18 and do not exist at any tier.
Cleaning up a session's work
Daintree records ownership from successful creation results for terminal.new, agent.launch, recipe.run and worktree.createWithRecipe, and in-app for workflow.startWorkOnIssue (its agent terminal only, not the worktree it creates) and a panel agent.resumeOwned started. agent.launchInNewWorktree owns both halves through the create and launch it runs. Launching an agent into an existing worktree owns the new terminal only. A partially successful worktree creation can still record the worktree it left behind. Only those trusted results write the record: a caller cannot name a resource into it by passing its id.
For an API-key client, ownership is session-scoped. Keep the returned ids and clean up within the same MCP session. Disconnecting, or 30 minutes without MCP calls, ends the session and clears the ownership record but leaves the terminals and worktrees in place; a reconnected session cannot claim them by supplying their ids. Daintree says so in the result of a launch and of an owned listing, and when it refuses an *Owned call. An orchestrator that needs ownership to survive reconnects should run as an agent pane with Agent integrations on: a pane's credential owns what it creates until the pane exits or is relaunched.
A terminal the user hands to an orchestrating pane (right-click > Hand to orchestrator) counts as owned for sending, injecting, answering dialogs, interrupting, revealing and reading its last message, but not for closing: handing over a conversation is not handing over the right to destroy it.
Delete worktrees only after reviewing the result, and approve the host's contents preview when prompted. worktree.deleteOwned never forces past uncommitted or untracked changes, never deletes the branch, and closes no terminals at all: close your own panels with terminal.closeOwned first, because it refuses while any terminal process still runs in the worktree, a closed panel's included. See the ownership ledger and deletion and recovery guide.
The in-app tool sets
Daintree's own assistant and the agent panes a project connects to the server run at Core or Full. Core is 74 tools and the default; Full adds 45. Every tool in a set is re-sent to the model on each turn, which is why Core holds the orchestration loop (choosing work, launching and steering agents, confirming their pull requests landed green, cleaning up) and the rest waits in Full.
| Area | Core | Full adds |
|---|---|---|
| Discovery and context | actions.getContext, actions.search, actions.getSchema, mcp.surface, workspace.list, slashCommands.list | actions.list |
| Worktrees | worktree.list, worktree.createWithRecipe, worktree.waitUntilReady, worktree.waitForPullRequest, worktree.delete¹, worktree.deleteOwned, worktree.retireOwned | worktree.getCurrent, worktree.setActive, worktree.reviewReadiness, worktree.resource.status, worktree.resource.provision, worktree.resource.pause, worktree.resource.resume, worktree.resource.teardown, worktree.setLabelColor, worktree.setCustomTitle |
| Issues and pull requests | forge.listIssues, forge.getIssue, forge.listIssueComments, forge.listPRs, forge.getPR, forge.getPRs, forge.getCIStatus, forge.getChecks | |
| Agents | agent.launch, agent.launchMany, agent.launchInNewWorktree, agent.listAvailable, agent.listPresets, agent.createPreset, agent.updatePreset, agent.deletePreset, agent.listAccounts, agent.listModels, agentSessionHistory.list, agent.resumeOwned | agentSessionHistory.resume, agent.addAccount, canopy.openWindow |
| Terminals | terminal.list, terminal.getStatus, terminal.getOutput, terminal.readLastMessageOwned, terminal.sendCommand¹, terminal.sendCommandMany, terminal.waitUntilIdle, terminal.waitUntilIdleBatch, terminal.notifyWhenIdle, terminal.cancelQueuedSend, terminal.interruptOwned, terminal.sendKeys¹, terminal.close¹, terminal.closeMany, terminal.waitForExit, terminal.restartOnPresetOwned, terminal.restartOnAccountOwned, terminal.applyClaudeUpdateOwned, terminal.moveToWorktree, terminal.revealOwned, terminal.placeOwned, terminal.rename | terminal.new, terminal.inject¹, terminal.kill², terminal.restart², terminal.startHeld², terminal.closeAll², terminal.setClientMetadata |
| Recipes and workflows | recipe.list | recipe.run, workflow.startWorkOnIssue, workflow.prepBranchForReview |
| Commands, checks and git | project.runCommand² | project.detectRunners, project.runCheck, git.getProjectPulse |
| Context, skills and fleet | copyTree.generate, copyTree.injectToTerminal², copyTree.generateAndCopyFile, skills.search, skills.load, fleet.getRunStatus | |
| Links | project.links.list², project.links.add², project.links.update², project.links.remove² | |
| Assistant sessions | assistant.list², assistant.start², assistant.resume², agent.readQuota² | |
| Remote Hosts (registered only where Remote Hosts is available) | host.list², host.call², host.status², host.ensureProject², host.settings², host.watch², host.bringBack² | host.switch, project.openOnHost |
| Diagnostics and preview | help.displayImage, diagnostics.openReview² | browser.getConsoleMessages, devPreview.reloadPreview, devPreview.restart, errors.recent, notifications.recent |
| Plugin authoring | plugin.validate, plugin.diagnostics, plugin.reloadProject, plugin.reloadPanel, plugin.capturePanel |
¹ The Daintree Assistant's form. Every other session, an agent pane included, gets the *Owned form in its place (terminal.sendCommandOwned, terminal.injectOwned, terminal.sendKeysOwned, terminal.closeOwned, worktree.deleteOwned), which acts only on what that session created or was handed. The batch tools follow the same rule item by item.
² Reserved to the Daintree Assistant and withheld from agent panes at any tier.
So a project's assistant sees 74 tools at Core and 119 at Full, and an agent pane 56 and 96. Where Remote Hosts is not available, the seven Core host.* tools, host.switch and project.openOnHost are not registered, which leaves the assistant 67 and 110 and a pane 56 and 94. These are the static sets; what a session lists can be narrower, for example when it is bound to a workspace. A pane at Core lists everything a pane at Full holds, because a call above its tier asks you for approval rather than failing; see Agent panes. Git and forge writes, file reads, UI navigation and layout, theme and settings reads and writes, session bookmarks, the recipe editor, screenshot capture, fleet arming and bulk kills are in neither set.
What the less obvious groups do
- Remote Hosts.
host.listandhost.calllet the assistant see this machine's remote hosts and run a host's own Daintree tools there, under that host's own gates.host.statusreads agents across projects and hosts in one call,host.ensureProjectputs this project on a host without opening a window there,host.settingschanges a host's named settings once you approve the preview,host.watcharms one notice for when a link or capacity condition is met or an agent starts waiting, andhost.bringBackwakes a host whose link is down, where a wake is set up, and starts Daintree there if its Host mode is on.host.listincludes this machine aslocal. They are offered from the start of every assistant session, whether or not you have hosts. - Links.
project.links.*keep the project's entries in the links launcher. Adding one opens nothing, and the assistant can change only the links it added and you have not since edited. - Assistant sessions.
assistant.list,assistant.startandassistant.resumelet one assistant find another in the same project, open one in a vacant slot or reopen the conversation a stopped slot keeps, and then message it with the ordinary send tools.agent.readQuotareads this machine's Codex quota and, for each Claude Code limit, the last usage-limit message its terminals showed. - Running a command.
project.runCommandruns one non-interactive shell command in the project root or a worktree, with no prompt or terminal attached, and returns its exit code and output. It does not ask first and runs as your user, not in a sandbox, so it is pinned with the deletes in the settings preview, and Daintree strips its ownDAINTREE_variables from it. - Presets, accounts and models.
agent.createPreset,agent.updatePresetandagent.deletePresetedit your own presets, each confirm-gated with the exact change previewed; project, CCR and built-in presets stay read-only.agent.listAccountsandagent.listModelsresolve the ids a launch takes, andagent.addAccount, in Full, asks every time, with a row per account naming its folder. - Bringing agents back.
agentSessionHistory.listandagent.resumeOwnedreopen a closed session into a panel the caller owns, which is why they sit in Core.agentSessionHistory.resumeopens one the caller does not own, so it stays in Full. See Resume agents and history. - Steering panels.
terminal.placeOwnedparks or brings back a panel without moving you,terminal.waitForExitwaits for the processes of panels this session closed before their worktree is deleted,terminal.cancelQueuedSendwithdraws a message held for a busy worker, the tworestartOn…Ownedtools move a worker to another preset or account after you confirm (the process restarts, and the conversation carries over only if asked for and the CLI accepts it), andterminal.applyClaudeUpdateOwnedtypes/restartonce into a Claude Code panel waiting at an empty prompt, after you approve, to apply an update it installed.worktree.retireOwnedis the owned delete with its checks run first: clean, every commit pushed, nobody else's process there, and the session's own panels closed. - Full's smaller additions.
worktree.setLabelColorandworktree.setCustomTitlemark and name a worktree on its card, and are cosmetic only.canopy.openWindowopens Canopy in its own window.terminal.startHeldstarts a held panel in place rather than launching a replacement beside it.plugin.capturePanelreturns an image of one plugin panel as it renders, with its recent console warnings and errors, to close the plugin-authoring loop.
Prompting agents and getting replies back
An orchestrator's loop is launch, prompt, wait, read, and either prompt again or clean up. The tools above carry it, and a few arguments on the send and launch tools save most of the polling.
- First prompt and system prompt.
agent.launchtakes aprompt, submitted once the agent starts, and an agent-neutralsystemPromptthat Daintree maps to each CLI's own flag and replays across restart, restore and resume. - Handback marker.
handback: trueon a launch or send asks the agent to end its reply with aDAINTREE-DONEmarker line carrying a one-line summary. Once the agent prints it,terminal.getStatusand both idle waits carrylastHandback(message,observedAt,submissionToken,truncated). It records that the agent printed the marker, not that the work is done: the message is the agent's own lossy summary, and its absence never means the agent is still working, because agents forget the instruction or lose it when their context compacts. - Waiting for the reply.
waitForReply: trueholds the call open until the agent finishes (its marker, a settle, an exit or a close) orwaitSecondsruns out (default 300, at most 1800), and returns the reply inreplywith anoutcomeofhandback,settled,exited,closedortimeout. Atimeoutmeans still going. The reply is the agent's screen: output, not instructions. Your client's own request timeout still applies. - Being told instead of waiting. From an agent pane or the assistant,
notify: truereturns at once. When the agent next stops working, Daintree types one notice into the caller's own prompt: the agent's handback summary and a pointer toterminal.getOutputwhen the summary is complete, otherwise its last screen lines (replyLines, default 40, at most 200, 0 for none; setting it quotes the screen even when there is a summary).terminal.notifyWhenIdlearms the same notice for a terminal that is already working, with an optional note of up to 160 characters echoed back. A notice fires once, after the target has stayed out ofworkingfor two seconds, and waits until the asking pane is settled at its prompt; a pane sitting at an approval, a question or an error is not typed into. - Reading the last message.
terminal.readLastMessageOwnedreads the last reply a Claude Code agent wrote to its own transcript, with any unanswered tool calls such as a question and its options. It pages back through a long reply with a cursor and reaches up to 20 replies back. It is not proof the agent is waiting: permission prompts appear only on screen. - Delivery confirmation. Every send returns a
submissionToken. Pass it withterminalIdstoterminal.getStatusto read that send'ssubmissionrecord: itsphase(queued,writing,pty_written,failed,cancelledorunknown) and, once written, when the screen next changed.pty_writtenmeans the text and its Enter reached the terminal, not that the agent acted on them. Daintree keeps the last 32 per terminal, and loses them on restart. - Answering an agent's own dialogs.
terminal.sendKeys(orterminal.sendKeysOwned) answers a CLI's trust, permission or selection dialog by option label withchoose, or by named keys. A plain send types text and Enter, which picks whatever is highlighted. - Stopping a turn.
terminal.interruptOwnedsends the agent's own cancel keystrokes and keeps the conversation. It refuses an idle agent, or one whose CLI binds a different cancel key, rather than sending a stray key, and it reports that the keystrokes were handed over, not that the agent stopped. - Batches. In-app sessions can launch several agents with one prompt (
agent.launchMany), send a different message to each of several terminals (terminal.sendCommandMany), and close several at once (terminal.closeMany). Each item runs as the single call would, with its own notice, and results come back in order.
Reading your own surface with mcp.surface
A client written against an older surface has no way to notice it is talking to a newer one, until a call fails for a reason it cannot interpret. mcp.surface answers that at startup: it returns the session's tool surface as versioned data with a stable content hash, so a client can compare one string instead of diffing a tool list, and fail loudly rather than silently.
| Field | Meaning |
|---|---|
manifestVersion | The shape version of the payload, currently 4. Bumped by hand when a field is added, removed or given new meaning, never for a change in which tools the surface contains. Version 3 renamed the in-app tier values to core and full, and version 4 added role. A client reads this to know whether it can still parse the response at all. |
appVersion | The running Daintree build, so a captured response is diagnosable on its own. |
tier | The tier this call was admitted at, and the tier the rest of the response describes. |
role | Which kind of session the server took the connection for, settled from its credential at the handshake: global-assistant, project-assistant, agent-pane, external-client or relay. Part of the hash. |
hash | Hex SHA-256 over the canonical form of the surface. |
tools | Sorted by id. Each entry carries id, tier (the smallest tool set that permits it, or external), kind, readOnlyHint, idempotentHint, and an optional deprecated object with a reason and a replacement. |
Two decisions are worth knowing. Descriptions and schemas are deliberately omitted: they are already on tools/list, and re-sending them would make the cheap startup check as expensive as the thing it replaces. And prose is stripped before hashing: descriptions, titles and examples are removed from the schema preimage, so rewording a description never reads as a compatibility break, while an argument-schema edit always does. The hash covers the full argument schema, including value ranges the advertised schema leaves out for the model's benefit.
The manifest describes the static tier allowlist plus the session's own binding, exactly as tools/list does, not the transient per-tool approvals that can widen dispatch for a few minutes. Folding those in would make the hash flap as approvals come and go, and would describe a surface tools/list never showed. When a tier changes, the server fires notifications/tools/list_changed; a client that re-reads on that notification converges.
Workflow instructions at initialize
The MCP initialize result carries a static instructions string that clients fold into the model's system prompt at session start. It is the only place to establish cross-cutting rules before the model has picked a tool, so it deliberately does not restate any tool's own description. External clients and agent panes get four points:
- Daintree drives IDE-owned worktrees, recipes and agent terminals. Use your own shell for repository, file, git and forge work; that is not license for an in-app session to route around its own tier.
- Call only listed tools.
actions.searchfinds one by intent andactions.getSchemagives its arguments; neither widens access. - Resolve worktree and terminal ids before scoped actions. A send returns once queued, not when the work is done. From an agent pane or the assistant, pass
notify: trueand end the turn; otherwise wait withterminal.waitUntilIdle, never a polling loop, and readidleReasonbefore an irreversible step. - In-app sessions run Core or Full, and
externalis its own allowlist. A call outside the session's set returnsTIER_NOT_PERMITTED, or from an agent pane asks the user;USER_REJECTEDmeans they declined. Retry aretriable: falseerror only after something changes.
The string is budgeted by test rather than truncated at runtime: Claude Code hard-cuts instructions at 2 KiB and the authorization paragraph is the tail, so silently losing it would leave a model guessing at why a call was denied. The suite fails an author's edit instead, with 512 bytes held in reserve. Daintree's own assistant sessions get a one-line string instead, because their own instruction files carry these rules in fuller form, and Codex repeats a server's instructions inside every tool description it looks up.
Payload budgets
Before v0.30 a single tool call could return 31 MB. Every result path is now bounded, and the bounds are byte-based rather than token-based on purpose: tokenization is a client concern, and pinning the server to one vendor's tokenizer would be worse than a conservative fixed cap.
| Surface | Cap | Behavior at the cap |
|---|---|---|
| Tool result text | 50 KiB | Truncated at a UTF-8 character boundary, with the notice prefixed rather than appended: a model reading top-down learns the body is incomplete before it starts parsing it. |
structuredContent | Measured separately | Re-derived by parsing the already-bounded text, so the two halves can never disagree. Dropped when the text was truncated, when nesting exceeds 100 levels, or when it re-serializes over the cap. Any dropped structured half flags the envelope isError: true. |
| Terminal tails | 50 KiB, shared across a call | Output tails in terminal.getOutput, terminal.getStatus and the scrollback resource are fitted to the cap before serialization and keep the newest lines, so a tail is never cut into unparseable JSON. recentOutputTruncated says older output was cut. |
| Resource text | 50 KiB | A threshold rather than a hard ceiling; appends a [truncated] marker. |
| Project check output | Tail-preserving | Keeps the end of the run, where the failure is. Secret-scrubbed across an 8 KiB overlap so a credential straddling the cut is still redacted. |
| Commit subjects | 512 bytes per field | Commit subjects and author names in git.getProjectPulse are truncated per field, so one pathological commit message cannot crowd out a whole result. |
| CopyTree content preview | 32 KiB read, 48 KiB serialized | The serialized budget is the one that decides: JSON escaping doubles newlines and quotes and expands control characters sixfold, so a 32 KiB head of the wrong file serializes to far more. |
| Waited and notified replies | 6,000 characters per terminal | The newest output is kept. A notice carries at most 20,000 characters across all its terminals, and a batch's waited replies at most 32,000. |
Session history reads, the last-message read and the action manifest carry their own budgets on the same model. Two paths bypass the helper entirely: non-text content, and JSON-RPC protocol errors.
Alongside the budgets, every action result is parsed through its declared schema before it is returned, so the published shape is the delivered one. That parse is also a security boundary in its own right. See Security posture over MCP.
Forge over MCP
Forge tools are not on the external surface: an external caller has its own gh. In-app sessions reach eight forge reads at core, and so at full too, because choosing what to work on, triaging it and confirming that an agent's pull request landed green are part of the orchestration loop: forge.listIssues, forge.getIssue, forge.listIssueComments, forge.listPRs, forge.getPR, forge.getPRs, forge.getCIStatus and forge.getChecks. No forge write is on any tier, so nothing creates, merges or edits a pull request or issue over MCP. The assistant and agents do that with their own forge CLI in their own shell: the assistant's Claude Code session runs gh, glab and tea without a permission prompt, and its instructions have it file an issue only once you approve the repository, title and body. Daintree's own confirmation dialogs still cover everything that goes through MCP.
Writes
Forge write actions (pull requests: create, merge, comment, edit; issues: create, close, label; PR reviews: approve and request changes) still exist in Daintree for its own UI, and each returns the state it changed rather than void. None of them is reachable over MCP.
Reads
forge.getCIStatusreturns the roll-up CI verdict for one pull request. Read the overall state for the answer: the accompanying counts cover required checks only, and a zero total also appears when the required-check list could not be read in full, so it is never evidence that nothing gates the merge. Values are provider-cached and can lag by around a minute.forge.getChecksnames the checks behind that verdict, the follow-up once the roll-up shows trouble.forge.getPRreads one pull request, andforge.getPRsseveral in one call, keeping a failed lookup apart from a missing pull request;forge.listPRs,forge.listIssuesandforge.getIssuelist and read pull requests and issues, with the listing options below.forge.listIssueCommentsreads an issue's comment thread, sinceforge.getIssuereports only how many comments there are.
forge.getPR, forge.getPRs, forge.getCIStatus and forge.getChecks advertise an MCP outputSchema, so a model can be held to the result shape rather than parsing prose.
Listing
Issue and PR lists take perPage (1–100, with a default that varies by provider; 100 is the tightest page ceiling across the provider roster), sort (created or updated), direction, an opaque cursor from the previous response's nextCursor, and a view that selects a summary or full projection. There is also a bypassCache escape hatch, because without it an out-of-band change (you running a forge CLI in a terminal, another agent closing an issue) stays invisible until the cached page ages out.
The schemas are strict: an unknown filter key is rejected rather than dropped. A silently ignored filter returned a plausible-looking but wrong set, and an agent then acted on it. A validation error naming the bad key is strictly more useful than a wrong answer.
Running a project's checks
project.runCheck (v0.30) runs one of a project's detected runners (a test command, a lint command) as a real child process and returns its real exit code, instead of the best-effort scrollback parse that preceded it. It executes in the main process rather than round-tripping to a renderer, because renderer dispatch is capped at 30 seconds, well under a real test suite, and an MCP abort signal does not cross IPC so a renderer-hosted run could never be cancelled. Because it never needs a project view, it also works for a workspace-bound session whose project has no window open.
It sits in the full tool set, beside project.detectRunners, which lists a project's runners without executing them. Neither is in core. It is not on the external surface: an external caller runs its own test command in its own shell. Don't confuse it with project.runCommand, the assistant's Core tool, which runs any command the assistant names rather than one the project declares, and is withheld from agent panes.
CopyTree returns a file handle
copyTree.generateAndCopyFile is the one deliberate exception to "drop what the caller can do itself", and it is worth stating why. A caller holding a terminal could pipe files through pbcopy itself. What it cannot reproduce is the deliverable: one call that applies the project's own CopyTree policy (ignore rules, budgets, format) and puts the bundle on the clipboard the same way on every platform (the file itself on macOS and Linux, its path on Windows). The alternative is a brittle shell-and-pipe reconstruction per platform.
It returns a file handle rather than the whole bundle, so a multi-megabyte context bundle never has to cross the transport. Its blast radius is a clipboard overwrite, which the risk banding already classifies as destructive-local and the tool advertises through destructiveHint. See CopyTree.
Terminal and agent metadata
terminal.getStatus is the batched polling path. Prefer it over listing terminals and then reading each one's output in turn. Name up to 256 terminals with terminalIds, or filter by worktree or location. Per entry it returns the terminal id, the detected or launched agent id, the agent state, the reason it is waiting, the timestamp of the last transition, and:
- Process lifecycle.
exitCodeis set once the process exits and is absent while it runs (null for a signal with no numeric code);spawnedAtis the spawn time;hasPtyturns false once the process exited or a kill was requested;agentIncarnationcounts how many times a new agent took over the same terminal. - Screen and typing activity. With
includeOutput,lastOutputChangeAtis when the visible screen last changed, ignoring spinner and timer redraws, so a frozen turn can be told from a long one, andlastTypedInputAtis when input was last typed, so a CLI's pre-filled suggestion can be told from input actually sent.recentOutputcarries the tail. Neither timestamp is a hang verdict. - Parsed check results.
lastCheckResultcarries a parsed pass/fail verdict from a test, lint or build summary detected in the terminal. It is best-effort rather than authoritative:project.runCheckis the path that returns a real exit code. - Handback and delivery.
lastHandbackwhen the agent printed a requested marker, and a send'ssubmissionrecord when asubmissionTokenwas passed; see Prompting agents and getting replies back. - Armed state. Whether fleet broadcast input reaches the terminal.
It never blocks and never fails as a whole: an unknown id returns a per-entry error instead of aborting the call. The result says which surface answered (renderer, or pty when the workspace has no open window) and lists the fields that surface cannot observe in unavailableFields, which means unknown rather than false. The idle waits add a trackingState (tracked, closed or unknown), so a finished agent can be told from a terminal Daintree no longer tracks; an untracked terminal returns idleReason: "unknown" at once, which is not proof a shell command finished.
terminal.restart and terminal.kill are in the full tool set for the Daintree Assistant only. Fleet arming and disarming, and browser.captureScreenshot, are on no tier: they are yours to drive from the UI.
Resources
Five resource kinds are exposed, under the URI scheme daintree://<host>/<id>/<verb>. Three support live subscriptions, which emit notifications/resources/updated with no payload: the client re-reads on each notification. A notification can be dropped without error, so the read is the authoritative half.
| URI | Backing action | Subscribable |
|---|---|---|
daintree://workspace/current/binding | workspace.list | Yes |
daintree://worktree/{id}/pulse | git.getProjectPulse | Yes |
daintree://terminal/{id}/scrollback | terminal.getOutput (last 200 lines) | No |
daintree://agent/{id}/state | terminal.list | Yes |
daintree://project/current/issues | forge.listIssues | No |
The binding resource is a session's view of its own workspace binding: whether the bound workspace has a live view, when eviction last took one, and whether the user asked to keep it resident. It needs no renderer, so it is listed first and still answers when nothing else can; an unbound session reads unbound. In the agent state URI, {id} is an agent id such as claude, not a terminal id: the resource reports the terminal of that agent Daintree heard from most recently, and names it.
Resources authorize through their backing action, which has a consequence worth stating: because no forge.* or git.* id is on the external allowlist, an external session cannot read the pulse or issues resources. Binding, scrollback and agent state are available to it.
Prompts
The server registers three MCP prompts. Most clients surface them as slash commands in the input autocomplete.
| Prompt | Arguments | What it renders |
|---|---|---|
start_issue | issue_number (required) | A structured prompt to start work on an issue, with the active worktree and branch filled in, asking the model to summarize the goal, confirm the worktree is the right place, and outline the first two or three steps for sign-off before editing. |
triage_failed_agent | terminal_id (optional) | A diagnosis prompt for a stuck or failed agent. Pass a terminal id and recent output is embedded; omit it to triage the current worktree without specific output. |
triage_terminals | None | A static watching recipe: how to batch terminal.getStatus, when to set includeOutput, how to read lastCheckResult and lastHandback, and how to pace the next round instead of holding a blocking wait open. |
Idempotency dedup
Models replay tool calls during multi-step planning, especially across reconnects. A per-session dedup cache absorbs that for creation tools: within a 120-second TTL a duplicate call returns the original result instead of redispatching, with a 256-entry FIFO cap per session.
A caller can pass an explicit requestKey alongside _meta in the arguments; without one, the server hashes the action id and the argument object. An in-flight duplicate joins the original promise; a completed one returns the cached result and audits as dedup. A repeat with the same requestKey but different arguments is rejected as a collision rather than silently answered.
A tool earns a place on that allowlist only when all three hold: a retry after a transient error is realistic, the repeat would leave a durable or immediately visible artifact, and an intentional same-argument repeat inside the window is not a normal use case. That last condition is what bounds the list:
| Group | Members |
|---|---|
| Panel and agent spawns | terminal.new, agent.launch, recipe.run |
| Worktree and workflow creation | worktree.createWithRecipe, workflow.startWorkOnIssue, agent.launchInNewWorktree, worktree.resource.provision |
Both worktree deletes are deliberately absent. Worktree ids are paths, and create, delete, recreate with the same path is a supported workflow, so caching a delete could report success for a second deletion of a genuinely different worktree. The forge writes that used to sit on this list left MCP with the Core and Full split, so no replay of them can arrive.
git.commit and git.push were deliberately removed from this list, before git writes left MCP entirely. Neither takes an argument a legitimate repeat varies: git.commit commits whatever the index holds, and git.push gets only a working directory and an upstream flag. So a second push after a new commit (or a repeated wip message) is a same-argument call that would be swallowed as a cached success for work that never happened.
Navigation actions, repeatable commands and idempotent state-sets are excluded for the mirror-image reason: they create no duplicate to suppress, so caching buys nothing and costs correctness. In a set → unset → set sequence, the third call matches the first, the cached success returns, and the state stays unset.
Argument and error conventions
- Selectors. Scoped actions take
worktreeIdorworktreePath, andprojectIdorprojectPath.cwd,rootPathandpathsurvive as legacy aliases. Where a default would be silently wrong, the selector is required rather than inferred. - Pagination.
limitpluscursororoffset, returning items withhasMore,nextCursorand sometimes atotal. An empty cursor string is rejected rather than treated as page one. - Errors throw. A returned
{ ok: false }serializes as a successful tool result, so failures must throw to reach the caller as failures. Errors carry aretriableflag; retry afalseonly once the arguments, context or authorization have changed. - Short agent ids. An MCP launch that names no panel id gets a short readable one (such as
claude-7f3a), because a model repeats the id in every send, notice and close.
Related pages
- MCP Server: enabling the server, connecting a client, the tier model, agent panes and the audit log.
- Authorization & Approval: how sessions get a tier, agent panes, widening and host confirmation.
- Daintree Assistant: the in-app client that reaches the Core and Full tool sets.
- Code Forge: provider setup behind the
forge.*tools. - CopyTree: what
copyTree.generateAndCopyFilebundles. - Fleet: the broadcast runs
fleet.getRunStatusreports on.