Agents and MCP

An external MCP client, such as an AI agent, can edit a Current project. It does not get a separate copy or a separate format. It sends the same operations the workspace sends, through the same validation, revision checks and history. Current itself has no built-in chat. Prompting happens in the external client.

The MCP transport is local only: a named pipe for the current Windows user, reached through Current’s MCP client program. There is no remote relay.

Connect a client

1. In Current, select the objects or the track the client may change. You can skip this if you enable the structure grant or the camera grant.
2. Open Settings > External clients. View > External clients… and the rail’s Connections button open the same page.
3. Choose an Edit mode:
   • Review edits: the client prepares proposals. Nothing changes until you preview and accept them in Activity.
   • Plan: the client can read the scoped project. It cannot propose or apply edits.
   • Edit directly: permitted edits to scoped objects apply at once. The client can also prepare proposals.
4. Turn on any grants the client needs:
   • Composition frame evidence: render frames and filmstrips, and use transcript and audio analysis tools.
   • Composition structure: create objects, change tracks and export. It does not grant edits to existing objects outside the scope.
   • Camera and composition controls: edit the active composition’s camera and shared controls. This can affect every spatial layer that uses them.
5. Choose Grant new scope. The page shows the client command: the MCP client with a --session "<path>" argument. Configure the client to run it.

The session path is a short-lived local credential. Do not share it, and never put it in a project. Mode and grants are not stored between sessions. Rebind scope or Disconnect revokes the previous session. Opening a project, starting a new project or recovering an autosave also ends the session. Reconnect restores only the saved project, mode, object IDs and permissions.

Scope

• Direct property edits need the object’s ID in the session’s direct edit scope.
• The structure grant allows creation and structural edits. It does not grant every existing object’s properties.
• When the client creates an object, only that new object’s ID is added to its scope.
• Locked clips and tracks, protected properties (for example Protect wording from agents) and indirect effects on protected content reject the edit.
• Only a person in Current can accept proposals or change locks.

project_inspect reports the scope, including which IDs are directly editable and which objects are out of scope.

Tools

The client discovers exact schemas with tools/list. The tools are:

Group	Tools
Inspect	project_inspect, parameters_inspect, parameter_evaluate, scene_inspect, assets_list, asset_inspect, shaders_catalogue, verify_project, history_list, jobs_list
Create and import	asset_import, font_import, text_create, shape_create, grid_create, asset_place, asset_place_range, composition_set_format
Edit	edit_apply, align_apply
Review	proposal_prepare, proposal_inspect
Evidence	render_frame, render_filmstrip, render_cancel, transcript_review
Transcripts and audio	transcript_model_status, transcript_start, transcript_cancel, transcript_status, transcript_search, transcript_range, speech_ranges, audio_inspect
Save and export	project_save, project_save_as, export_settings, export_start, export_job, export_cancel

Saving and exporting need Edit directly mode and the structure grant. The create and import tools also need both.

edit_apply and proposal_prepare take a list of operations, such as move, trim, split, property, keyframe, add_effect, set_parameter_source, rename_clip or set_motion_blur. Operations that only the workspace performs, such as locking, relinking and importing components, are not in the MCP operation list. Spatial, camera and control addresses, and the transcript tools, are not covered in detail in these docs yet.

The base revision rule

The project has a revision number that rises by one with every accepted change, undo and redo. Every MCP edit states the revision it was based on:

• edit_apply needs base_revision and an idempotency_key.
• proposal_prepare needs base_revision.
• align_apply, export_start, project_save and the import and create tools also check a base revision.

The edit is accepted only if base_revision equals the current revision. A batch is atomic: either every operation applies, or none does.

{
  "name": "edit_apply",
  "arguments": {
    "base_revision": 5,
    "idempotency_key": "rename-title-1",
    "operations": [
      {
        "op": "rename_clip",
        "id": "<clip-id>",
        "name": "Film title"
      }
    ]
  }
}

What happens on a stale revision

If anything changed the project after the client read it, for example a manual edit, an undo, or another accepted proposal, the revision has moved on. Then:

• The request fails with stale_revision. MCP adds the hint: “Inspect the current project revision and retry with that base revision.”
• Nothing in the batch is applied. No history entry is added. The newer manual edit stays as it is.
• The client should call project_inspect again, rebuild its edit against the current project, and send it with the new revision.

An agent edit can never silently overwrite a newer manual edit this way.

Retries

• Sending the same request again with the same idempotency_key returns the earlier result. It does not apply the edit twice.
• Reusing a key with a different request fails with idempotency_mismatch.
• A session keeps at most 10,000 retry keys.

Proposals

In Review edits mode (and optionally in Edit directly mode), the client uses proposal_prepare. Current validates the operations against the stated revision and builds a candidate project without changing the real one. At most 32 proposals can wait at once.

• The proposal appears in Activity > Needs review.
• You must preview the candidate before you can accept it. Accept applies it as one agent change. Discard removes it.
• If the project changed after the proposal’s base revision, the proposal is stale. Activity shows “Stale. The project changed after revision …”, and accepting it fails with stale_revision. The client can check this with proposal_inspect, which returns stale.
• Evidence tools accept a proposal_id to render the candidate. A stale candidate is rejected.

Shared history and undo

Accepted agent edits join the same history and undo list as manual edits. Ctrl+Z in Current undoes an agent edit. History records the actor (human or agent). Because undo also raises the revision, the client’s next edit after an undo must use the new revision.

Evidence

With the frame evidence grant:

• render_frame renders one frame to a PNG. source_quality is original or preview.
• render_filmstrip renders 1 to 12 frames, given as frame numbers or seconds, into one labelled PNG contact sheet.
• Both can take base_revision; a mismatch fails with stale_revision.