# Load and save projects

> Load and save the MCP working graph, update or copy an attached Studio project with the right versions, and recover partial or unavailable editor actions.

Source: https://kaitoi.io/docs/core/mcp-projects/
Section: Kaitoi Core / MCP
Written for: People managing persistent projects through Kaitoi MCP tools.
Last reviewed: 2026-10-24

---

Loading a project, changing the working graph, saving its bundle, and
reloading a copy are different actions. Keep project IDs and versions from
actual receipts rather than treating a project name as identity.

## Read both parts of a save receipt


A save can persist a project while the attached Studio tab still needs reconciliation. Inspect the returned persistence and adoption fields, including any adoption guard. Keep the saved project identity and verify which project the tab now owns. Replacing or closing the tab without inspecting these outcomes can lose unsaved local work. The controls only compare example outcomes.

Updating A keeps the project identity. Saving a separate copy produces B while the editor can still show A; confirming adoption changes the editor binding to B without changing B’s saved content. Persistence and adoption remain independently inspected receipts.

*Figure: Persistence and adoption by the open tab are separate outcomes.*

## Work in the headless graph

Use `list_projects`, then `load_project(project_id)` to replace the server's
headless working graph with the intended project. Inspect and edit that graph,
then `save_project(name, project_id, expected_version)` to update it using
the observed saved-project version. For a new named project, use the new-save
contract instead of passing an unrelated existing ID.

Scratch single-node execution is not this working graph and cannot be saved
through this workflow. Add and connect persistent nodes when you need work
that can be extended and reopened.

## Save an attached Studio graph

Attach explicitly and read the current session's `saveContext`, including
project ID and `bundleVersion`, plus the live `graphRevision`. An update uses
the same project ID, its bundle version as `expected_version`, and current
`expected_revision`. Changing the name on that update renames the same project.

For a separate copy, omit `project_id` and use `expected_version:0` with the
current editor revision. This can save live unsaved work into a new bundle.
Inspect `bundleSaved`, `versionConfirmed`, returned bundle version, and any
`reloadCopyState` separately. A saved bundle and editor adoption/reloading
are not the same fact.

## Treat attached loading as conditional

Attached `load_project` is not enabled in every deployment. When available,
it requires current revision and a supported different personal project;
reserved/temporary or unsupported team contexts can be refused. Respect
`STUDIO_ACTION_NOT_ALLOWED` or other availability responses. Do not silently
retry the refused action against a headless graph.

## Check identity and receipt before retrying

**Headless:** load the intended saved project into the headless working
graph and update it with its saved version. **Attached update:** use the same
project ID, bundle version and current live revision. **Copy:** omit project ID,
use new-save version zero, and inspect save versus reload/adoption receipts.
Attached loading is deployment-dependent and must not silently fall back.

## Recover without overwriting another context

Retain a pending `actionId` and inspect the original action after uncertainty.
If a bundle save succeeded but editor adoption was incomplete, do not assume
the entire operation failed and create another copy. Read the receipt and
current tab before deciding the next action.

For stale saved versions, reread and reconcile the project. For stale editor
revisions or lost attachment, refresh the live context. These failures need
different repairs. See [Live Studio sessions](/docs/core/mcp-studio/) and
[Permissions and troubleshooting](/docs/core/mcp-troubleshooting/).