MCP reference
MCP is a standard way for an AI agent to use another program's tools. Astro has an MCP address. An agent that connects to it can edit your Astro projects.
The address
http://127.0.0.1:41417/api/cut/mcp
127.0.0.1 means this computer. Nothing outside your computer can reach it. The Astro app has to be running.
The token
Every request carries a token:
Authorization: Bearer astro_YOUR_TOKEN
Create a token in Settings, Connect agents. It is shown once. Astro keeps only a fingerprint of it, so nobody can read it back, including Astro.
| What happens | What the agent is told |
|---|---|
| No token | "No agent token was sent. Create one at Settings ▸ Connect agents in Astro and give it to your agent." |
| Wrong token | "Token not recognised. Create a new one at Settings ▸ Connect agents in Astro." |
| Revoked token | "This token was revoked." |
Each call is counted under your account, and the token's last used time updates.
What an agent can do
An agent connected with a token edits projects and their media. That is all it can do.
| It can | It cannot |
|---|---|
| List, create and open your projects | Run a program or a command on your computer |
| Cut, trim, move and delete clips | Run code it wrote itself |
| Add titles, captions, shapes, effects and transitions | Read or write a file outside your projects and their media |
| Grade colour, fix audio, add music and voiceovers | Read your agent tokens |
| Search stock footage and add it to the project | Change your saved preferences, your style or your edit settings |
| Make designed graphics from Astro's recipes | Open an address on your computer or your private network |
| Export the video and check the export | See the report about your computer |
Tools that are closed to a token
| Tool | Why | What to use |
|---|---|---|
render_code_video, add_motion_graphic, edit_motion_graphic | They run code the caller writes | motion_recipe, build_motion_video, add_title, edit_graphic |
run_ffmpeg_tool | It passes free-form arguments to scripts on this computer | convert_media, set_speed, the audio and colour tools |
system_doctor, run_system_setup | They report on the computer and install programs on it | Settings, Help & support, Troubleshooting |
update_my_preferences, record_lesson, save_my_style, set_edit_settings | They change rules for every project on the account | set_this_edit_mode for one edit |
send_feedback | It sends a message to Astro in your name | Settings, Help & support |
An agent that asks for one of these gets a sentence saying why and what to use.
The assistant inside Astro can use all of them, because you are at the app watching the edit happen.
Web addresses
Three tools take a web address: capture_brand, import_url and watch_link. For an agent connected with a token, the address must be http or https and must be on the public internet. An address on this computer or on a private network is refused.
Tool groups
Astro has about 240 tools. An agent starts with 19 core tools and loads more when it needs them, which keeps each request small and cheap.
The core tools
get_state, search_tools, load_tools, run_tool, read_skill, check_edit, select, seek, capture_frame, split_at, trim_clip, delete_item, set_clip_muted, add_title, update_overlay, undo, redo, set_aspect, export_video
Plus three for projects: astro_list_projects, astro_create_project, astro_open_project.
The groups
| Group | What it covers |
|---|---|
timeline | Clips: add, move, trim, split, speed, tracks, titles, keyframes |
cuts | Cutting a recording to its words: silences, retakes, filler |
transcript | The words of the cut by number: read them with who speaks, remove words and fillers by number |
watch | Looking at footage: frames, scene changes, a linked video |
captions | Captions: transcribe, caption language, timing, the caption look |
text | Videos made only of words: kinetic type, lyric videos |
audio | Volume, sound quality, music, sound effects, the beat |
voice | Voiceovers, reading captions aloud, voice clean-up, telling the speakers apart |
layout | Where the speaker sits: reframing, split layouts, the safe box, reading on-screen text |
graphics | Shapes, stickers, emoji, your own logo or screenshot |
motion | Animated titles and graphics from recipes |
effects | Effects, transitions, element animations, fades |
color | Grading: presets, curves, wheels, matching a reference |
cutout | Background removal, masks, green-screen keying |
stock | Stock footage and photographs, web pictures, importing a link |
generation | AI-generated images, video and talking characters |
scenes | Generated scene productions and faceless videos |
films | Launch films, product demos, explainers, learning a style |
edit | A whole finished edit: edit style, stills before the render, versions |
brand | The brand kit: a site's logo, colours and type |
export | Export, cutdowns, fades, the post caption, checking an export |
project | Media files and folders, the library, templates, version history |
Finding and loading tools
| Tool | What it does |
|---|---|
search_tools | Finds tools by what they do. With no query, lists the groups. |
load_tools | Loads one or more groups and returns each tool's parameters. |
run_tool | Runs a loaded tool by name. |
When the tool list changes
After load_tools, the session lists more tools than the agent first read. Astro says so in two ways, and an agent can use either.
- The answer to
load_toolscarries each loaded tool's parameters, andrun_toolruns it. - An agent that holds a stream open (a
GETon the address with its session id andAccept: text/event-stream) receivesnotifications/tools/list_changed: once when the stream first attaches, and again each time a group loads. It then asks fortools/listagain.
The Claude Code plugin and the Claude Desktop extension handle this for you.
One project per session
A session works on one project: the one it opened with astro_open_project or made with astro_create_project. astro_list_projects marks it with open: true.
A call that names a different project in project_id is refused, and nothing runs. This stops an id left over from earlier in a conversation from landing an edit on the wrong video. To change project, call astro_open_project with the other one.
Reading less
Results that name what changed
Every edit's result carries changed. It holds the counts that moved, written before→after, and the items themselves:
| Field | What it holds |
|---|---|
added | The items the call made, each with its id, where it is (in), its start and its len |
edited | The items the call changed, the same way, with set naming the settings that changed |
removed | The ids that are gone |
moved | Rows that slid together: every item of a row from from on moved by seconds, count of them |
captions | A caption pass in one line: how many cues were added, removed and edited, and the stretch they cover |
An agent keeps its picture of the timeline current from these and has no need to read the project again between its own edits.
The compact read
get_state with compact: true returns the timeline alone, as short rows, at a fraction of the size of the full read. Its rows field names the columns. from and to return one stretch of a long timeline, and cues: true adds the caption cues.
Ids in the compact read are cut to the fewest characters that still name one item. Every tool takes a short id back. A short id that fits two items is refused with both of them named.
Examples
Open a project and add a title
{ "name": "astro_list_projects", "arguments": {} }
{ "name": "astro_open_project", "arguments": { "project_id": "PROJECT_ID" } }
{ "name": "add_title", "arguments": { "text": "Hello", "start": 0, "end": 3 } }
Load the caption tools and make captions
{ "name": "load_tools", "arguments": { "groups": ["captions"] } }
{ "name": "run_tool", "arguments": { "name": "subtitles_generate", "arguments": {} } }
Check the edit before exporting
{ "name": "check_edit", "arguments": {} }
{ "name": "export_video", "arguments": {} }
Skills
Astro's skills are guides the agent reads before it edits. read_skill returns one, and each skill is also an MCP resource at astro://skills/NAME. Start with creative-director.
Seeing the edit
When the project is open in Astro, every change an agent makes shows there as it lands. When it is closed, the change is saved and shows the next time you open the project.
Troubleshooting
| What you see | What it means | What to do |
|---|---|---|
ECONNREFUSED | The Astro app is closed or still starting | Open Astro and try again |
| "/plugin isn't available" | Your Claude Code has no plugin command | Use the direct claude mcp add command in Connect Claude Code |
| "Token not recognised" | The token is mistyped or from another account | Create a new token in Settings, Connect agents |
| "This token was revoked" | The token was turned off | Create a new token |
| "… is not open to an agent connected with a token" | The tool is closed to outside agents | Use the tool the message names, or run it from Astro's own chat |
| "That address is on this computer or a private network" | The agent handed over a local address | Use a public web address |
| "No project is open" | The agent has not opened a project | Call astro_open_project first |
| "This session has project … open, and the call names …" | The call named a project other than the session's | Call astro_open_project to switch, or leave project_id out |
| "… fits 2 ids" | A short id names more than one item | Pass more of the id |
More help is on the Troubleshooting page.