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.
| System | Program |
|---|---|
| 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 MSI | C:\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 --mcpClaude 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, toautomation.jsonin 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.
| Area | Tools |
|---|---|
| Projects | project_list, project_create, project_open, project_save, project_close, project_set_video |
| Reading | timeline_read (compact: lanes, clips in time order, media, ids), project_get (everything), concat_version |
| Media | media_probe, media_import |
| Editing | clip_add, clips_add_sequence, clip_trim, clips_split, clips_move, clips_remove, clip_update, clip_transform, clip_speed, clip_frame, track_add |
| Picture | clip_mask, clip_stabilize, timeline_background |
| Titles and captions | title_add, captions_add |
| Keyframes and effects | keyframe_set, keyframe_clear, effects_list, effect_layer_add, effect_key_set |
| Anything else | edit_apply (any edit command, or a batch of them as one undo step), edit_undo, edit_redo |
| Templates | template_list, template_instantiate |
| Export | export_start, export_status, export_wait (with progress), export_cancel |
| Looking | preview_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 --mcpfrom 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:
- Call
concat_version. Check that the API version starts with0.2, and readmcp.modeto know whether you are going through a window or on your own. - 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.
- Import media with
media_import. The new item's id is the reply'screatedId. - Place clips with
clip_addorclips_add_sequence. Readtimeline_readfor clip ids; do not guess them. - Prefer one
edit_applybatch for a sequence of edits that belong together. - Export with
export_start, thenexport_wait(or pollexport_status) for that job. Do not start a second export meanwhile; it is refused withbusy. - Treat a
refusedmessage as the reason, in plain words. Nothing changed. - Save with
project_savebeforeproject_close, or close withsave: true.
Recipes has complete scripts for the same steps over JSON-RPC.