MCP

Concat ships an MCP server inside the app. An agent starts it as concat --mcp and edits with the same commands the window uses.

Status: shipped in 0.2.8. The desktop app is its own MCP server: an agent (Claude Code, Claude Desktop or any other MCP client) starts it as concat --mcp and can then create projects, import media, cut, add titles and captions, keyframe, apply effects, look at frames and export. Nothing extra to install. Live mode, where an agent edits the project open in the window while you watch, is not in it yet; it is planned in #337.

Set it up

Point the client at the Concat program with the one argument --mcp.

SystemProgram
macOS/Applications/Concat.app/Contents/MacOS/concat
Windows, installed for you (the setup program)%LOCALAPPDATA%\Programs\Concat\concat.exe
Windows, installed for everyone, or the MSIC:\Program Files\Concat\concat.exe
Linux (.deb, .rpm, Arch)/usr/bin/concat
Linux (AppImage)The .AppImage file itself

Claude Code:

claude mcp add concat -- /Applications/Concat.app/Contents/MacOS/concat --mcp

Claude Desktop (Settings › Developer › Edit Config, claude_desktop_config.json), and most other clients, which take the same shape:

{
  "mcpServers": {
    "concat": {
      "command": "/Applications/Concat.app/Contents/MacOS/concat",
      "args": ["--mcp"]
    }
  }
}

On Windows, write the path with doubled backslashes in JSON: "C:\\Program Files\\Concat\\concat.exe". The phone apps have no MCP server.


How it reaches Concat

concat --mcp works one of two ways. The concat_version tool says which, as mcp.mode:

  • Through the window (window). When Concat is open with Settings › Automation › Scripts and apps on, the window writes where its server is, and its token, to automation.json in Concat's config folder (readable only by you). The MCP server finds it and goes through the window's JSON-RPC server. This is the safer way while you are editing: the agent cannot open the project you have on screen and save over it, and its exports take turns with yours.
  • On its own (headless). Otherwise the MCP server runs Concat's engine itself, with no window. Nothing has to be open.

Choose explicitly with --mcp window (fail rather than run on its own) or --mcp headless; the default is --mcp auto, and CONCAT_MCP_MODE says the same from the environment. To reach a server elsewhere, set CONCAT_API_ADDRESS (for example 127.0.0.1:7420) and CONCAT_API_TOKEN together in the client's env for the server.

Every Concat process locks the project folders it has open (a concat.lock file in the folder, let go on close or when the process dies). A project open in the window is refused in headless mode, with a note to turn on Automation and use --mcp window; the window refuses a project an agent has open.

Either way the agent writes files (projects, exports, frames) only under your home folder. Set CONCAT_MCP_ROOTS (a path list, :-separated, ; on Windows) to allow other folders in headless mode.


Tools

Tools are named for what they do. Their argument schemas are generated from the Concat API's own types, so they carry the same limits and descriptions the engine does.

AreaTools
Projectsproject_list, project_create, project_open, project_save, project_close, project_set_video
Readingtimeline_read (compact: lanes, clips in time order, media, ids), project_get (everything), concat_version
Mediamedia_probe, media_import
Editingclip_add, clips_add_sequence, clip_trim, clips_split, clips_move, clips_remove, clip_update, clip_transform, clip_speed, clip_frame, track_add
Pictureclip_mask, clip_stabilize, timeline_background
Titles and captionstitle_add, captions_add
Keyframes and effectskeyframe_set, keyframe_clear, effects_list, effect_layer_add, effect_key_set
Anything elseedit_apply (any edit command, or a batch of them as one undo step), edit_undo, edit_redo
Templatestemplate_list, template_instantiate
Exportexport_start, export_status, export_wait (with progress), export_cancel
Lookingpreview_frame (the composited frame as an image)

Edits stay in memory until project_save, as in the window. Times are seconds; a keyframe's position is a fraction of its clip (0 to 1); sizes and offsets are fractions of the frame.


Protocol

MCP over stdio, newline-delimited JSON-RPC 2.0. Both protocol eras are served: the initialize handshake (2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05) and the per-request _meta of 2026-07-28 with server/discover. ping, tools/list, tools/call, progress notifications for export_wait, and notifications/cancelled are supported. Standard output carries only the protocol; the server logs to standard error.

Note

CI tests the MCP server end to end over its standard input and output, headless and through a running server, with the server built from source. No release check starts concat --mcp from a packaged build yet. If your client cannot start it, say so with the client and the system.

For scripts that do not speak MCP, the same API is served as JSON-RPC lines from Settings › Automation; see JSON-RPC.


Guidance for agents

If you are an agent reading this because you have been pointed at Concat:

  1. Call concat_version. Check that the API version starts with 0.2, and read mcp.mode to know whether you are going through a window or on your own.
  2. Open or create a project. Keep its folder path; every project tool needs it. A project open in the window is refused while you are on your own; ask the person to turn on Automation.
  3. Import media with media_import. The new item's id is the reply's createdId.
  4. Place clips with clip_add or clips_add_sequence. Read timeline_read for clip ids; do not guess them.
  5. Prefer one edit_apply batch for a sequence of edits that belong together.
  6. Export with export_start, then export_wait (or poll export_status) for that job. Do not start a second export meanwhile; it is refused with busy.
  7. Treat a refused message as the reason, in plain words. Nothing changed.
  8. Save with project_save before project_close, or close with save: true.

Recipes has complete scripts for the same steps over JSON-RPC.