MCP Server

Drive Ordinary Animator from an AI tool (Claude Code, etc.) via the MCP server and the entity path scheme. For developers.

Beta. MCP support is an early feature and is still being shaken out, so expect rough edges. The entity model below is stable and worth understanding now. For developers -- if you use the app through its screens, you do not need anything on this page: you navigate by menus, not paths.

Ordinary Animator exposes an MCP server (Model Context Protocol) so an external AI tool such as Claude Code can read and change your production data programmatically. The in-app AI Assistant uses the same addressing scheme under the hood.

The entity path scheme

Every entity is addressed by a hierarchical path. project on its own (no leading slash) lists all your projects; every other path starts with /:

Entity Path
All projects project
Project /project/{projectId}
Episode /project/{projectId}/episode/{episodeId}
Scene /project/{projectId}/episode/{episodeId}/scene/{sceneId}
Shot /project/{projectId}/episode/{episodeId}/scene/{sceneId}/shot/{shotId}
Character /project/{projectId}/character/{characterId}
Location /project/{projectId}/location/{locationId}
Prop /project/{projectId}/prop/{propId}
Agent /project/{projectId}/agent/{agentId}
Recipe /project/{projectId}/recipe/{recipeId}
Step /project/{projectId}/recipe/{recipeId}/step/{stepId}
Idea /project/{projectId}/idea/{ideaId}
Experiment /project/{projectId}/experiment/{experimentId}
Track /project/{projectId}/swimlane/{swimlaneId}
Arc /project/{projectId}/swimlane/{swimlaneId}/arc/{arcId}

A Timeline track is addressed as swimlane -- the API keeps the old name for the rows so that existing tools and stored data keep working.

Dropping the final id lists that type: /project/{projectId}/character is every character, /project/{projectId}/experiment is every experiment (newest first, with each one's question, status, subjects and verdict). An experiment is a full entity here, as it is in the app (the Experiment group in the left-hand rail) -- you read it, list it, navigate to it and write its verdict exactly as you would a character's description.

A shot's storyboardMediaId and shotMediaId are writable: they are what Set as storyboard and Set as rough clip set in the app. Each takes the id of an item in the shot's own gallery -- an image for the storyboard, a video for the clip -- and an empty value clears it. Choosing a different rough clip clears the finished clip, as in the app. finishedMediaId is readable but not writable: Set as finished clip is an action (below).

What you can do through MCP

Everything on a media item's menu and in the plan rows is either reachable here or listed below with the reason.

An item's menu entries are actions, pressed with run_action on the gallery's owner and named like the menu entry. The app performs each one -- the same code the click runs -- so what you get is exactly what the menu gives. Each takes mediaIds (one id or a list) and its own arguments.

In the app Through MCP
Edit metadata run_action edit with one item id and a new name, tags or aiDescription.
Star / unstar run_action star with item ids; starred: false removes the star.
Archive / unarchive run_action archive with item ids; archived: false restores them.
Set / remove as finished clip run_action finished-clip with one item id on a shot; finished: false removes it. Setting it meets the Finish step exactly as running it does.
Set an identity LoRA in use run_action identity-lora-in-use with one item id (inUse: false to stop using it).
Delete run_action delete with item ids. It does what the menu's Delete does, including clearing a project, episode or experiment card picture that showed the deleted file.
Make local copy run_action local-copy with the ids of linked items: each becomes an owned item under the same id.
Move to another gallery run_action move with item ids and a destination (an entity id in the same project) or a newExperiment title. Items that only feed the chosen ones come along (includeSuggested: false stops that; include / exclude adjust it); links and pointers that named the old gallery are updated in the same write.
Set as storyboard, rough clip or reference Set the shot's storyboardMediaId / shotMediaId, or the asset's referenceMediaId.
Run again run_current_recipe with repeat_media_id set to the item. It runs the item's workflow again with a new seed.
Run exactly The same, with repeat set to exactly: the saved graph, the same seed, where the item ran.
Link or copy to another gallery Set linkMedia / copyMedia.
Add to another visual style Set the workflow on that visual style's entry for the operation.
Use this recipe Set recipeChoices on the project, scene or shot. On the project it puts the recipe at the top of the visual style's ordered list for that media purpose (Sound: the project's list); on a scene or shot it is that level's own choice.
Use the rough clip as is run_action finished-clip with the shot's rough clip id.
Finish the clips run_current_recipe on the scene, for every shot, with the upscale operation.
Skip or reopen a criterion Set its state to approved or not-done. Skipping no longer exists as a state.

An action runs in your open browser tab, on the page that shows that gallery. With no such page open the answer is unclaimed and nothing ran. Every id is checked before any is touched, so a call either does all of it or none, and deleting asks for no confirmation: naming the ids is the confirmation.

You do not need to be told these exist. Reading a character, location, prop, shot, scene, episode or project shows each chosen-media field with its value (null when empty), names the actions that gallery has in one line, and gives every media item's starred and archived state, false included -- so the entity itself says what can be changed.

Not available through MCP, and why: opening fullscreen, adding an item to the selection or to the chat box and the sketch editor are things your browser or your machine does; loading what made an item into the generation controls is screen state (read the item's provenance and build the step instead). Downloading and an item's details are available: see Reading a media item.

When a call is refused, the error names the property or action that was rejected, the rule it broke, and what would have been accepted -- for example the ids a gallery does hold -- and says that nothing was changed or run.

These paths mirror the entity hierarchy. A tool uses them to fetch data, create entities, and navigate ("go to character kira"). Start from project to discover your project IDs, then drill down.

Reading a media item

A media item has one path: its gallery owner's path, then /media/, then the item's id.

/project/oatest/character/posing-bench/media/av74
/project/oatest/character/posing-bench/look/noir/media/av2     (a named look)

It works under every entity that has a gallery: a project, episode, scene, shot, character, location, prop, experiment, or a named look. The MCP Path row of an item's Media Information dialog shows this path. A media id the gallery does not hold is refused, with the ids it does hold.

fetch_entity on the path returns the item: its name, kind, tags, starred and archived state, description, storage path, file size, dimensions or duration where stored, and, for generated media, where it came from (the workflow, the run and its inputs). A linked item answers with the original's facts and says it is a link.

It also returns a download URL: a signed link to the stored file. Open it in a browser or fetch it with a plain GET; it stops working after 15 minutes, so ask again for a new one. If a link cannot be signed where the service runs, the answer says so and gives the storage path instead; the rest of the read is unaffected.

fetch_entity on <gallery owner>/media lists the whole gallery, oldest first, one line per item led by its media path. It lists up to 200 items; pass limit (up to 1000) for more and tag to list only items carrying a tag. A list that was cut says how many items it left out.

run_action accepts a media path wherever it takes a media id: in mediaIds, or as the entity_id itself, which runs the action on that gallery for that item. Bare ids keep working.

upload_media adds a file from your own machine to an entity's media gallery -- the one way to get media into a project without dragging it into a browser. A batch of reference images onto a character, a set of takes to compare on a shot, clips assembled elsewhere onto a scene.

upload_media(entity_id, file_path, tags, display_name)
Argument What it takes
entity_id The entity whose gallery to add to. Galleries live on projects, episodes, scenes, shots, characters, locations, props and experiments -- nothing else has one. An experiment's gallery is scratch space, meant to be thrown away.
file_path One path, or a list of paths to add several files in one call.
tags Optional comma-separated tags. The file's kind (image / video / audio) is tagged for you.
display_name Optional name for the row. Defaults to the file's own name without its extension.

It returns the new media id and the path the file was stored at.

file_path is a path on the machine running the agent service. In the usual local setup that is your own machine, so ordinary paths work. Pointed at the hosted service it means nothing, and the call is refused saying so -- upload through the app's gallery instead. Web addresses are not accepted; download the file first.

The same file twice gives you one item. Files are stored by their content, so re-uploading one you already added returns the media id you already have and adds no second row. That makes "upload all of these" safe to repeat after a failure partway through.

What it refuses, and why. A file it cannot classify by extension (images, video, audio, .glb and text files are all accepted) -- storing it would give you a row that neither previews nor plays. A file over 512 MB. A path that does not exist. An entity with no gallery. If one path in a batch is bad, nothing is uploaded at all, so you never have to work out which half arrived.

.webm and .ogg hold either audio or video. Pass tags of audio for an audio one, or it will be shown as a video.

Duration is filled in for audio and video where it can be read, and left out where it cannot -- a wrong duration would be taken seriously by the sequencer, a missing one is simply read off the file when it plays.

Running one of the app's actions

Some of what the app does is not a field you set -- it is a button you press. Generating a scene's shots from its screenplay is the clearest example. run_action presses those buttons for you.

run_action(entity_id, action, params, wait)
Argument What it takes
entity_id The entity to act on -- the scene whose shots to generate, say.
action The action's name, e.g. generate-shots.
params Options, for the actions that take any. Most take none.
wait Wait for it to finish and report what it did. On by default.

There is one tool for every action, not one per button. To find out what an entity can be asked to do, call describe_entity with its type -- the reply lists the actions along with the fields. For an action's full rules before you run it, call describe_entity with the action name as well.

Your browser does the work. The action runs in the Ordinary Animator tab you already have open, using exactly the code the button uses -- so what you get is what you would have got by clicking. The app is opened on the right page for you. If no tab is open, nothing runs, and the call says so in those words rather than pretending it worked. Open the app and ask again.

This also means an action works on a project shared with you: the browser writes to the owner's data the same way it does when you click the button yourself.

Actions available today

Action On What it does
generate-shots Scene Plans the scene's shots -- which shots, what each one frames, how long each runs -- from its screenplay plus its mood, beats, pacing and energy curve. On a scene with no shots it builds the list and fills it in. On a scene that already has shots it fills only empty fields and turns everything else into a proposal with a reason, including shot lengths, for you to accept or reject on the shot. It never overwrites, never deletes, never reorders, and never adds a shot: a beat it thinks is uncovered is offered for the user to add.

Checking and importing a workflow

validate_workflow checks a workflow file with the app's own validator and spends nothing. Give it an import_to_project and it goes one step further: if the file has no error, it is imported into that project's Workflow Library, exactly as the Import dialog would.

validate_workflow(workflow, target, workflow_name, import_to_project, filename, wait)
Argument What it takes
workflow The workflow as a JSON object, in the graph (UI) format -- not a string.
target cloud (the default) or local -- which backend the workflow is meant for.
workflow_name Optional name, used only to make messages easier to read.
import_to_project The project id to import into. You need to be able to edit that project; a reviewer on a shared project is refused.
filename The name it is saved under, e.g. my-upscale.json (defaults to workflow_name). Importing a name the library already has saves a new version of that workflow, as the dialog does.
wait Wait (up to about 45 seconds) for the verdict. On by default.

The answer says what happened, in the dialog's words:

  • accepted -- "Imported ", with the operation and model the workflow says it is for. It is now in the Project Library.
  • refused -- nothing was saved. findings are the same problems the dialog would show, for example that the workflow has no OA Workflow Metadata note.
  • pending -- the import is finished by an Ordinary Animator tab that has that project open (on any page), and none picked it up in time. Call again with the same import_to_project and filename and no workflow to keep waiting; there is nothing to re-send.

Sending yourself a notification

send_notification sends a notification to the devices you registered under My Account, for example when a long task you started from Claude Code is done.

send_notification(title, body, url)
  • title is required (up to 120 characters); body is optional (up to 1000).
  • url is optional and must be a path inside the app, such as /comfy-queue or /shot?projectId=p1; a full web address is refused. Opening the notification keeps the project the user is already in.
  • It always goes to the signed-in user -- there is no way to name anyone else.
  • At most 30 an hour. With no registered device the answer says devices: 0 and nothing reaches a phone; the user can turn notifications on from My Account (see Notifications).

Talking to the assistant

chat sends a message to Ordinary Animator's own assistant, exactly as if you had typed it into the chat panel, and returns its reply.

chat(message, conversation_id, entity_id, view)
Argument What it takes
message What you would type. Leave it out to read a conversation instead.
conversation_id Continue this conversation (its id comes back with every reply). Leave it out to start a new one.
entity_id The page you are "standing on" -- the assistant's "this" and "here" mean that entity.
view Which of that entity's pages, as for navigate_to (media, properties, ...).

With conversation_id alone it returns that conversation's messages; with neither it lists the project's recent conversations. The reply lists what the assistant actually did (the tools it called) as well as what it said.

It is the same assistant and the same conversations. A conversation started here appears in the chat panel's recent list, and one started in the panel can be continued here. The app is moved to the page you name, as it would be if you were typing there.

A turn can take minutes and can spend credits -- the assistant may run and wait on generations.

Connecting

You connect as yourself, with a browser sign-in -- there is no key to copy and paste, and no configuration file holding a secret.

Point your MCP client (Claude Code, Claude Desktop) at the Ordinary Animator MCP server. The client registers itself, then opens your browser on an Ordinary Animator consent page. Sign in with the same Google account you use for the app, read which application is asking and where your browser will be sent afterwards, and approve only if you started the connection yourself. The client is handed a token of its own, and every call it makes from then on acts as you and reaches only your own data.

Tokens refresh themselves, so you sign in once rather than every session.

See Entities & the Data Model for the concepts behind the hierarchy and the property model.