# Attach to a live Studio session

> Opt in on a Studio tab, discover and attach its exact session, use revision-guarded actions, and recover uncertain changes without silently switching graphs.

Source: https://kaitoi.io/docs/core/mcp-studio/
Section: Kaitoi Core / MCP
Written for: People connecting an external AI client to the live Studio editor.
Last reviewed: 2026-10-24

---

Live attachment lets an external AI client inspect and change the intended
Studio tab. It is separate from the MCP connection itself and from the
server's headless working graph.

## Attach to the intended tab and graph


Enable Agent access for the intended Studio tab, discover available sessions, attach and inspect the returned graph state. Use the resulting session and revision identity in later operations. Reattach or inspect again if the tab or graph changed. Attaching does not grant unrestricted authority, execute nodes or guarantee that unsaved changes were persisted.

Handle h1 initially identifies the opted-in tab and project A at editor revision 7. Changing its context to project B at revision 8 invalidates the old binding; the other visible tab is not implicitly selected.

*Figure: Verify the connection, session and current revision before editing.*

## Opt in on the intended tab

Enable **Agent access** in the Studio tab you intend to use. Ask the client
to call `list_studio_sessions` and identify that tab/project/workspace from
the returned metadata. Follow `nextSessionId` when the list is paginated.
Do not choose a tab by approximate name when several could match.

Call `attach_studio_session(session_id, set_default=true)` when that is the
desired default. Keep the returned handle as `studio_session`; passing it
explicitly avoids accidentally using another default attachment. Write scope,
account capabilities, current consent and workspace role still apply.

## Read before an attached mutation

Use `get_studio_attachment` to check the binding, then read the current graph
with `get_graph_state`. Preserve the live graph revision and pass the current
`expected_revision` to attached mutations. Editor revisions and saved project
bundle versions are different values.

Attachments are short-lived and bound to the client credential, tab and its
context. Reconnect, project/workspace changes, consent or primary-connection
changes can invalidate them. Refresh the attachment and reread state; do not
copy a new revision onto an old assumed graph or silently continue headlessly.

## Recover an uncertain editor action

**Attach:** enable Agent access on the intended tab, discover its exact
session, and retain the attachment handle. **Edit:** read current graph state
and use its expected_revision; saved bundle versions are different.
**Recover:** inspect the original actionId instead of repeating an uncertain
write. Context changes fail closed and do not grant headless fallback.

## Inspect action receipts and retained values

Keep an `actionId` and inspect it with `get_studio_action` if a change is
pending or its response is uncertain. `cancel_studio_action` targets that relay
action, not an unrelated durable execution. Pending or unknown is not
permission to repeat the write.

Use `get_studio_action_value` with the returned expected version/path for
omitted retained values. Large captures use `get_studio_capture_value`;
retrieve every needed path and page before `release_studio_capture`.
`hasMore:false` completes the selected value, not necessarily the entire
capture. A bounded screenshot, when offered, captures the Studio graph with
declared omissions; it is not general desktop or settings access.

## Detach deliberately

`detach_studio_session` ends the selected handle/default for this client. It
does not disable all clients on the tab, undo edits, or reverse execution
charges. See [Projects](/docs/core/mcp-projects/) and
[MCP troubleshooting](/docs/core/mcp-troubleshooting/) for context-specific
recovery and availability refusals.