MCP tools

A connected app talks to Sequence through eight tools on the Model Context Protocol (MCP) server. Finding a workspace, project, asset, or screening reads Sequence directly and does not ask Snippy. ask_snippy, snippy_wait, and snippy_stop are how the app asks Snippy to work, checks on that work, and stops it.

The app should call list_workspaces first and have you choose a workspace, even when you belong to only one. It keeps that choice until you switch. A new chat needs that workspace and a project in it. A follow-up needs only the chat's session_id and the message. To find an asset or screening, or to give you a link, the app uses search_project_items and get_entity rather than asking Snippy. To see or share what Snippy made, ask it to export the cut and create a public screening. The result lists the screening's link.

Refused or failed calls return status: refused or status: failed. The reason field explains the problem and what to do next. Unknown tool names are rejected.

session_id values are lowercase hyphenated UUIDs, as ask_snippy and list_sessions print them.

List workspaces#

list_workspaces lists the workspaces you can open. It does not change anything. Have the app ask you to choose one before it finds projects or starts work, and reuse that choice until you switch.

Inputs. None.

Returns.

  • items — the workspaces, sorted by name (ignoring case) and then by id. Each one has id, name, and slug.
  • total — how many workspaces are in items.

List projects#

list_projects finds projects in the workspace you selected, most recently updated first. It does not change anything.

InputRequiredDescription
workspace_idYesThe workspace you selected, from list_workspaces.
queryNoCase-insensitive text to find in project names.
offsetNoWhere to start in the list. A whole number from 0 to 2147483646. Default 0.
limitNoHow many projects to return. A whole number from 1 to 100. Default 20.

Returns.

  • workspace_id — the workspace you asked about.
  • items — each project has id, name, updated_at, and url. url opens the project in Sequence, or is null when Sequence has no link for it.
  • next_offset — pass this as offset to read the next page with the same workspace and query. null when this page is the last.

Search project items#

search_project_items finds assets and screenings by name in a project of the selected workspace, without asking Snippy. Items that share a name are listed separately. Tell them apart by folder_path, duration_ms, or status. Each item's url opens it. The list is sorted by name (ignoring case), then by kind, then by id.

Timelines are not searchable. Leave types out, or include timeline along with other kinds, and notes includes: Timelines are not included: they can't be searched with these tools yet. Open the project's url to see its timelines. A call whose types is only timeline is refused: Timelines can't be found or looked up with these tools yet; open the project's url to see its timelines.

InputRequiredDescription
workspace_idYesThe workspace you selected, from list_workspaces.
project_idYesA project in that workspace, from list_projects.
queryNoCase-insensitive text to find in item names.
typesNoOnly these kinds: asset, screening, or timeline. Default is all three, and timelines are then left out with a note.
offsetNoWhere to start. A whole number from 0 to 2147483646. Default 0.
limitNoHow many items to return. A whole number from 1 to 100. Default 20.

Returns. workspace_id, project_id, items (each item is shaped as in What an item contains), next_offset (or null on the last page), and notes (a list of strings, empty when timelines were not requested).

You must have access to the project, and it must belong to the selected workspace.

Get entity#

get_entity looks up a project, asset, or screening in the selected workspace without asking Snippy. Supply either type and id, or url. Use entity IDs from list_projects, search_project_items, or an ask_snippy result; internal references in Snippy's reply are not entity IDs. A pasted Sequence URL must refer to the selected workspace. It does not switch workspaces.

A timeline ID or URL is refused: Timelines can't be found or looked up with these tools yet; open the project's url to see its timelines. Missing, deleted, and inaccessible items return the same refusal without distinguishing the cause.

InputRequiredDescription
workspace_idYesThe workspace you selected, from list_workspaces.
typeWith idproject, asset, screening, or timeline.
idWith typeThe entity's id.
urlInstead of type and idA Sequence link. It must be in the selected workspace.
project_idNoWhen set, the entity must belong to this project.

Returns. One item, shaped as in What an item contains.

Ask Snippy#

ask_snippy sends a request to Snippy. Without session_id, it starts a chat in the specified project. With session_id, it continues that chat in its existing project. Each chat accepts one request at a time, and up to five chats can run concurrently.

The call waits up to wait_seconds for the turn to end. If the turn is still running, the status is running and the app polls snippy_wait with the returned session_id. Work continues after the wait ends. Sending the same request again starts the work again.

InputRequiredDescription
messageYesWhat Snippy should do.
workspace_idFor a new chatThe workspace you selected, from list_workspaces.
project_idFor a new chatA project in that workspace, from list_projects.
session_idFor a follow-upA chat to continue, from an earlier ask_snippy or from list_sessions.
wait_secondsNoHow long to wait before answering with status running. A whole number of seconds from 0 to 60. 0 answers at once. If you leave it out, the server waits 30 seconds. A higher number waits 60.

A new chat requires message, workspace_id, and project_id. A follow-up requires message and session_id. If a follow-up also sends workspace_id or project_id, those ids must match the chat.

Returns. A turn, shaped as in What a turn returns.

Wait for Snippy#

snippy_wait returns the status of a chat's turn and any background work it started. It does not change the project. Set wait_seconds to 0 to read the status immediately.

InputRequiredDescription
session_idYesThe chat to check.
wait_secondsNoSame bounds as on ask_snippy. If you leave it out, the server waits 30 seconds, and never more than 60.

Returns. A turn, shaped as in What a turn returns.

Stop Snippy#

snippy_stop stops a chat's running turn and the background work it left running. The chat is saved. A later ask_snippy on the same session_id continues it. Stopping does not delete the chat or the project work already done. If the chat is not busy, the call returns the current turn and does not send a stop. The call waits up to 10 seconds for the stopped turn to end.

InputRequiredDescription
session_idYesThe chat to stop.

Returns. A turn, shaped as in What a turn returns.

List chats#

list_sessions returns chats started through this connector and still tracked by this server, newest first. Use it to recover a session_id. It does not list every conversation in the Snippy panel or change the project.

A chat is removed from the server's list when it is not running and has not been used for 24 hours. A later call can resume it.

InputRequiredDescription
project_idNoOnly this project's chats.

Returns.

  • items — each chat has session_id, project_id, status (the same status values as a turn), started_at (the time the chat started), and last_message.
  • total — how many chats are in items.

What an item contains#

search_project_items and get_entity return the fields below. type, id, name, project_id, and url are always present. Other fields depend on type.

FieldOnDescription
typeAllproject, asset, or screening.
idAllThe entity's id.
nameAllIts name.
project_idAllThe project it belongs to. For a project, this is the project's own id.
urlAllOpens it in Sequence. A screening's url is its public page. null when Sequence has no link.
updated_atProjectsWhen the project was last updated.
duration_msAssetsDuration in milliseconds, or null.
folder_pathAssetsLocation in the library. / is the top level.
privacyScreeningspublic or private.
statusScreeningsuploading, processing, or complete.
readyScreeningstrue when processing is complete.
review_urlScreeningsThe project's Review page for that screening. Opening it needs a project login. null when Sequence has no link.

What a turn returns#

ask_snippy, snippy_wait, and snippy_stop return the fields below. Only status is always present. A call refused before a chat exists returns status and reason.

FieldDescription
statusThe turn's current state. See the list below.
session_idThe chat.
project_idThe chat's project.
responseThe turn's text, or the text so far while running.
tasksEach task has id, description, and status.
jobsBackground jobs. Each one has id, label, and status.
notesStrings Sequence attached to the turn.
executioncloud, detached, or interactive.
screeningsScreenings from the turn. Each one has id, name, privacy, ready, and url (url may be null).
reasonPresent with refused or failed: why, and what to do.

status is one of:

  • completed — the turn ended.
  • awaiting_question — the turn ended because Snippy asked something. Answer with ask_snippy on the same session_id.
  • awaiting_idle — the turn ended.
  • awaiting_jobs — the turn ended, and background work continues. Poll snippy_wait.
  • running — still working. Poll snippy_wait. response is the text so far.
  • stopped — the turn was stopped.
  • refused — Sequence did not run the request. Read reason.
  • failed — the turn did not finish. Read reason.

When a call is refused#

The reason field contains one of these messages. Placeholders represent the ID, type, or detail supplied by Sequence. The concurrent chat limit is five unless the server is configured otherwise.

  • This chat is already running — wait for it with snippy_wait.
  • No project {id} you can open — list yours with list_projects.
  • No workspace {id} you can open — ask the user to choose from list_workspaces.
  • This project is outside the selected workspace. Ask the user to choose the workspace before starting a new chat there.
  • No {kind} {id} you can open — find it by name with search_project_items (projects with list_projects).
  • This {kind} is in another workspace than the selected one. Ask the user to choose that workspace from list_workspaces before using it.
  • Timelines can't be found or looked up with these tools yet; open the project's url to see its timelines.
  • Too many chats running (5 at most) — list them with list_sessions and stop one with snippy_stop.
  • This chat belongs to another account.
  • This chat is open in a browser tab of yours, which runs it now; follow it there.
  • Lost the connection to Snippy ({why}); the work may still be running — check with snippy_wait.
  • Your message did not reach Snippy ({why}); send it again with ask_snippy on the same session_id.
  • No chat {id} — start one with ask_snippy without a session_id.
  • {id} is not a chat id: session ids are lowercase hyphenated UUIDs, as ask_snippy and list_sessions print them.
  • This chat is on project {project}; name that project.
  • Give type and id, or a Sequence url.
  • Give either type and id, or url, not both.
  • {url} is not a link to a Sequence project, asset, timeline or screening on this server.
  • types must be a list of asset, screening and timeline.
  • wait_seconds must be a whole number of seconds, 0 to 60.
  • Couldn't reach Sequence ({why}); try again in a moment.
  • Headless execution is off in this environment.
  • Headless execution is unavailable right now (cloud runtime did not come up); try again in a minute.
  • Snippy's cloud run ended before the turn finished ({why}); send a follow-up with ask_snippy on the same session_id to continue.
  • The handoff was refused: draining (Snippy is restarting); try again in a moment.
  • Snippy reported an error.

A missing argument comes back as {name} is required. A value of the wrong type comes back as {name} must be a string. offset or limit outside its range comes back as {name} must be a whole number from {min} to {max}.