MCP tool reference

The Arcweave MCP server provides 105 tools. Your AI assistant chooses and calls them for you, so you don't need to call them yourself. Use this reference to check what an assistant can do with your key, which permission a tool needs, and how file transfers work.

The tools work like the REST API and follow the same rules. Each family below links to its REST reference for field details and validation rules.

How the tools work

• Project ID: every tool except arcweave_list_projects, arcweave_create_project, and arcweave_import_project needs a projectId. It's the project's URL hash, returned by arcweave_list_projects.
• Discover IDs first: list tools return the IDs that other tools need. For example, call arcweave_list_boards, then arcweave_list_elements with a boardId, then arcweave_get_element with an elementId.
• Permissions: tools marked Read need a key with Read projects. Tools marked Write need Write projects, including tools that only prepare an upload URL. The key's creator also needs the same workspace and project permissions as for the matching REST request.
• Results: a tool returns its result as JSON. List tools wrap their results in a property named after the collection, such as {"boards": […]}. Create tools return the new item's id, the same value under a named key such as elementId, and project version data.
• Errors: a failed call returns an MCP tool error whose text is the same JSON error body as the REST API, with a title and, for invalid arguments, an errors object. Arguments that fail validation use the title Bad Request - MCP arguments.
• History and collaboration: changes appear in the project's History under the key's name and in the editor of anyone who has the project open. Custom CSS updates are the exception: they don't create History entries.
• Content: element titles and content, connection labels, and component names accept HTML, null, or an object that maps existing project language codes to text, such as {"en":"<p>Hello</p>"}. See Rich text and Localized content.
• Position arguments: index is zero-based. Create tools also accept "-" to append. An index past the end places the item last.

Projects, comments, and CSS

REST reference: Projects, Comments, and CSS.

Tool	Access	What it does
arcweave_list_projects	Read	Lists the projects in the key's workspace, with each project's projectId. Requires the creator's workspace-level View projects list permission.
arcweave_list_comments	Read	Reads all comment threads and replies, including resolved threads, with authors, timestamps, and positions. Doesn't mark comments as read.
arcweave_create_project	Write	Creates a project from a template: empty, sample, game-engine-sample, video-sample, tabletop-campaign-sample, visual-novel, or cyber-security-sample. Use empty for a blank project. Returns projectId.
arcweave_import_project	Write	Imports a project object, such as an Arcweave JSON export, as a new project named name. Pass the object itself, not a file path or a JSON string. Assets and media attachments aren't imported. Counts toward the import/export quota.
arcweave_rename_project	Write	Renames the project to name. The project ID and content stay the same.
arcweave_delete_project	Write	Deletes the whole project. It becomes inactive and inaccessible to everyone.
arcweave_get_project_css	Read	Reads the project's custom Play Mode CSS as {"css": "…"}.
arcweave_update_project_css	Write	Replaces the whole custom CSS with css. Send an empty string to clear it. See Style Play Mode.

An import of a JSON export of selected boards can fail when the file refers to items it doesn't contain, such as the project's starting element. See Import selected boards.

Exports

REST reference: Exports.

Tool	Access	What it does
arcweave_export_json	Read	Prepares a download of the project as Arcweave JSON.
arcweave_export_godot	Read	Prepares a download of the project in the format used by the Godot plugin.
arcweave_export_unity	Read	Prepares a download of the project in the format used by the Unity plugin.
arcweave_export_unreal	Read	Prepares a download of the project in the format used by the Unreal Engine plugin.

The export tools don't return the project data. Each returns a signed download URL that expires after 10 minutes, with expiresAt, method (GET), headers, a filename such as arcweave-PROJECT_HASH-json.json, and format. The assistant needs an HTTP or file-transfer tool to download the file; the request doesn't need an Authorization header.

These options are available:

Option	Formats	Description
locale	All	Language code to export. Omit it, or use __default__, for the project's main language. Use * for all languages.
allLocales	All	true exports all languages and overrides locale.
boardIds	JSON	Board IDs to include. Omit it, or pass null or an empty list, for all boards. Selecting a folder includes the boards inside it.
fallbackContents	Godot, Unity, Unreal	true fills missing translations from the language's Translates from chain. Defaults to false.
filterAssetNames	JSON, Godot	false includes stored asset filenames in each asset's file field. By default, that field is left out. Unity and Unreal always leave it out.

What you download:

• A JSON file, not a ZIP archive. Media files aren't included.
• The JSON export is the project object, as the REST JSON export returns it, and can be passed to arcweave_import_project. It doesn't include coordinates.
• The engine exports wrap the data in {"project": …}, as the REST engine endpoints do. See Engine export differences.
• The file is generated when the URL is fetched, so it contains the project as it is at download time, not when the URL was prepared. The URL keeps its options.
• When the URL is fetched, Arcweave checks again that the key exists, has Read projects, and that its creator can still access the project, and that the workspace has the export feature.
• Fetching the URL counts toward the import/export quota. Preparing it doesn't. See Limits.

Boards

REST reference: Boards.

Tool	Access	What it does
arcweave_list_boards	Read	Lists board and folder summaries with IDs, hierarchy, item counts, and each board's startingElementId.
arcweave_get_board	Read	Reads a board or folder by boardId, including its item ID lists.
arcweave_create_board	Write	Creates a board, or a folder with type: "folder". Optional: name, parentId (a folder; null for the project root), index, and customId for a board. Returns boardId.
arcweave_update_board	Write	Renames a board or folder with name, or sets a board's missing customId. Existing custom IDs can't change.
arcweave_move_board	Write	Moves a board or folder to index within parentId. Omit parentId to keep the current folder; null moves it to the project root.
arcweave_delete_board	Write	Deletes a board and its contents, or a folder and everything in it. At least one regular board must remain.

Starting elements

REST reference: Starting element and Board starting element.

The project's starting element is where Play Mode starts when you play the whole project. A board can also have its own board start, used when you play only that board.

Tool	Access	What it does
arcweave_get_starting_element	Read	Reads the project's starting element. Returns elementId and the full element, or null for both when none is set.
arcweave_set_starting_element	Write	Sets the project's starting element to elementId, on any board, or clears it with null. elementId is required.
arcweave_get_board_starting_element	Read	Reads a board's own starting element. Returns boardId, elementId, and element. elementId and element are null when the board has none, even if the project's starting element is on the board.
arcweave_set_board_starting_element	Write	Sets a board's starting element to elementId, which must be an element on that board, or clears it with null. Doesn't change the project's starting element. Folders can't have a starting element.

Elements

REST reference: Elements.

Tool	Access	What it does
arcweave_list_elements	Read	Lists element summaries for a boardId, in board order.
arcweave_get_element	Read	Reads a full element by elementId, including all translations, outputs, attributes, component attachments, cover, and audio.
arcweave_create_element	Write	Creates an element on boardId at x and y. Optional: title, content, width, height, theme, autoHeight, and index. Returns elementId.
arcweave_update_element	Write	Updates the supplied fields of an element. Fields you leave out don't change.
arcweave_move_element	Write	Moves an element to index in its board's element list. Its position on the canvas doesn't change.
arcweave_move_element_output	Write	Reorders an element's outgoing choices. outputId is a connection ID from the element's outputs.
arcweave_delete_element	Write	Deletes an element with its incoming and outgoing connections. Jumpers that pointed to it become unassigned, and it stops being the project's or its board's starting element.

Notes

REST reference: Notes.

Tool	Access	What it does
arcweave_list_notes	Read	Lists note summaries for a boardId.
arcweave_get_note	Read	Reads a note by noteId, with its content, position, size, and appearance.
arcweave_create_note	Write	Creates a note on boardId at x and y. Optional: content (HTML, not a language map), width, height, theme, and autoHeight. Returns noteId.
arcweave_update_note	Write	Updates the supplied fields of a note.
arcweave_delete_note	Write	Deletes a note.

Connections

REST reference: Connections.

Tool	Access	What it does
arcweave_list_connections	Read	Lists connection summaries for a boardId, with source and target IDs.
arcweave_get_connection	Read	Reads a connection by connectionId, with its endpoints and all label translations.
arcweave_create_connection	Write	Connects two items on boardId. Set sourceid and sourceType (elements or conditions) and targetid and targetType (elements, branches, or jumpers). Optional: label, type, theme, sourceFace, targetFace, labelLocation, labelWidth, waypoints, and controlPoints. A condition source attaches only on right, and a branch target only on left, top, or bottom; leave a face out for automatic placement. Returns connectionId.
arcweave_update_connection	Write	Updates a connection's label, appearance, endpoints, or path. Change an endpoint's ID and type together. Pass null for waypoints or controlPoints to restore automatic routing.
arcweave_delete_connection	Write	Deletes a connection. The items it connected remain.

Branches and conditions

REST reference: Branches.

Condition scripts are Arcscript expressions, such as score > 3, without if.

Tool	Access	What it does
arcweave_list_branches	Read	Lists branch summaries for a boardId.
arcweave_get_branch	Read	Reads a branch by branchId, with its if, else if, and else conditions, their IDs, scripts, and output connection IDs.
arcweave_create_branch	Write	Creates a branch on boardId at x and y. Optional: theme and conditions with ifCondition, elseIfConditions, and elseCondition. Returns branchId.
arcweave_update_branch	Write	Updates a branch's position, theme, or conditions. Supplying elseIfConditions replaces the whole list; conditions you leave out are deleted with their connections.
arcweave_delete_branch	Write	Deletes a branch with its conditions and connections.
arcweave_update_branch_if_condition	Write	Sets the if condition's script, or clears it with null. The if condition can't be removed.
arcweave_create_branch_else_condition	Write	Adds an else condition to a branch that has none. Returns conditionId.
arcweave_update_branch_else_condition	Write	Sets the else condition's script.
arcweave_delete_branch_else_condition	Write	Removes the else condition and its output connection.
arcweave_create_branch_else_if_condition	Write	Adds an else if condition at the end of the list, with an optional script. Returns conditionId.
arcweave_update_branch_else_if_condition	Write	Sets the script of the else if condition conditionId.
arcweave_delete_branch_else_if_condition	Write	Deletes an else if condition and its output connection.
arcweave_move_branch_else_if_condition	Write	Moves an else if condition to index, changing the order in which conditions are checked.

To connect a condition's output, call arcweave_create_connection with the condition ID as sourceid and sourceType: "conditions". Each condition has one output: to point it somewhere else, update or delete its current connection instead of creating a second one.

Variables

REST reference: Variables.

Tool	Access	What it does
arcweave_list_variables	Read	Lists global variables with their IDs, names, types, and values. Board and component attribute variables aren't included.
arcweave_get_variable	Read	Reads a variable by variableId.
arcweave_create_variable	Write	Creates a global variable with a unique name. Optional: type (string, integer, float, or boolean; defaults to string), value, and index. Returns variableId.
arcweave_update_variable	Write	Changes a variable's type or value. Variables can't be renamed.
arcweave_delete_variable	Write	Deletes a variable. Check the Arcscript that uses it first.
arcweave_move_variable	Write	Moves a variable to index in the list.

Jumpers

REST reference: Jumpers.

Tool	Access	What it does
arcweave_list_jumpers	Read	Lists jumper summaries for a boardId, with their target element IDs.
arcweave_get_jumper	Read	Reads a jumper by jumperId, with its position, size, and target element.
arcweave_create_jumper	Write	Creates a jumper on boardId at x and y. Optional: elementId, the target element on any board, width, and height. Returns jumperId.
arcweave_update_jumper	Write	Updates a jumper's position, size, or target. elementId: null leaves it unassigned.
arcweave_delete_jumper	Write	Deletes a jumper and its incoming connections. The target element remains.

To lead into a jumper, connect an item to it with targetType: "jumpers". Jumpers have no outgoing connections.

Components and element attachments

REST reference: Components and Elements.

Tool	Access	What it does
arcweave_list_components	Read	Lists components and folders with their IDs, names, and tree relationships.
arcweave_get_component	Read	Reads a component or folder by componentId.
arcweave_create_component	Write	Creates a component, or a folder with type: "folder". Optional: name, parentId, and index. A custom ID is generated automatically. Returns componentId.
arcweave_update_component	Write	Renames a component or folder. name is required. The custom ID doesn't change.
arcweave_move_component	Write	Moves a component or folder to index within parentId. Omit parentId to keep the current folder; null moves it to the top level.
arcweave_delete_component	Write	Deletes a component, or a folder and everything in it, and removes it from elements and component-list attributes.
arcweave_create_element_component	Write	Attaches the component componentId to the element elementId. Returns itemId, the attachment's ID, which differs from the component ID.
arcweave_delete_element_component	Write	Removes the attachment itemId from an element. The component remains.
arcweave_move_element_component	Write	Moves the attachment itemId to index. Add targetElementId to move it to another element.

Attributes

REST reference: Attributes.

Board and component attributes can be string, rich-text, component-list, asset-list, boolean, integer, or float. String, boolean, integer, and float attributes with a customId work as Arcscript variables. Element attributes can be string, rich-text, component-list, or asset-list. Create attributes with a value object containing type and optional data.

Tool	Access	What it does
arcweave_get_attribute	Read	Reads any attribute by attributeId. Use it for element attributes, whose IDs are listed by arcweave_get_element.
arcweave_list_board_attributes	Read	Lists a board's attributes in order.
arcweave_get_board_attribute	Read	Reads an attribute of a board.
arcweave_create_board_attribute	Write	Creates an attribute on a board. Optional: name, size, and customId, which variable attributes require. Returns attributeId.
arcweave_update_board_attribute	Write	Updates the supplied fields of a board attribute. Changing type without data resets the value.
arcweave_delete_board_attribute	Write	Deletes a board attribute.
arcweave_move_board_attribute	Write	Moves a board attribute to index.
arcweave_list_component_attributes	Read	Lists a component's attributes in order.
arcweave_get_component_attribute	Read	Reads an attribute of a component.
arcweave_create_component_attribute	Write	Creates an attribute on a component. Optional: name, size, and customId, which variable attributes require. Returns attributeId.
arcweave_update_component_attribute	Write	Updates the supplied fields of a component attribute.
arcweave_delete_component_attribute	Write	Deletes a component attribute.
arcweave_move_component_attribute	Write	Moves a component attribute to index.
arcweave_create_element_attribute	Write	Creates an attribute on an element. Optional: name and size. Returns attributeId.
arcweave_update_element_attribute	Write	Updates the supplied fields of an element attribute.
arcweave_delete_element_attribute	Write	Deletes an element attribute.
arcweave_move_element_attribute	Write	Moves an element attribute to index.

Folders can't have attributes. Deleting an attribute doesn't delete the components or assets it refers to.

Assets and covers

REST reference: Assets.

Tool	Access	What it does
arcweave_list_assets	Read	Lists the asset and folder tree with IDs, names, types, and parents.
arcweave_get_asset	Read	Reads an asset's or folder's metadata, such as its stored filename and size. Doesn't return the file.
arcweave_get_asset_file	Read	Returns a download URL for an asset's file. See Download an asset file.
arcweave_prepare_asset_upload	Write	Returns an upload URL for a new image, audio, or video asset. See Upload a media file.
arcweave_create_asset	Write	Creates an asset folder with name. Optional: parentId and index. It doesn't create media assets.
arcweave_update_asset	Write	Updates an asset's metadata, such as its name, volume, or fades, or renames a folder. A replacement file must already be stored in the project. Template assets can't be changed.
arcweave_delete_asset	Write	Deletes an asset, or a folder and everything in it, and removes it from covers, audio, and asset-list attributes.
arcweave_move_asset	Write	Moves an asset or folder to index within parentId. Omit parentId to keep the current folder; null moves it to the top level.
arcweave_set_component_cover	Write	Sets a component's cover to an image asset (id) or an icon (type: "icon" and file). Replaces the previous cover.
arcweave_delete_component_cover	Write	Removes a component's cover. The asset remains.
arcweave_set_element_cover	Write	Sets an element's cover to an image or video asset (id), an icon (type: "icon" and file), or a YouTube video (type: "youtube" and url). Videos also accept mode (once, loop, or stop), autoplay, showControls, and showOptions.
arcweave_delete_element_cover	Write	Removes an element's cover. The asset remains.

Upload a media file

Uploading takes two steps, and the second happens outside MCP:

1. Call arcweave_prepare_asset_upload with projectId and type (image, audio, or video). It returns a url, expiresAt, method (POST), headers, fileField (file), and nameField (name).
2. Send a multipart/form-data POST request to url with the file in the file field and its name in the asset library in the name field. Optional fields: parentId, index, volume (0 to 1), and, for audio, fadeIn and fadeOut in milliseconds. Don't add type; the URL sets the project and media type.

The upload request stores the file and creates the asset at the same time. It returns 201 Created with the asset's id and assetId, which you can use right away for covers, audio, or asset-list attributes. Don't call arcweave_create_asset afterward: that tool only creates folders.

• The upload URL expires after 10 minutes and works once. Request a new URL for each file.
• The request doesn't need an Authorization header; the URL identifies the key. It works only while the key exists and still has Write projects.
• The assistant needs an HTTP or file-transfer tool to send the file. Don't pass local file paths or base64 file contents as MCP arguments.
• The same file types and plan limits apply as for REST uploads.
• If the response is lost or a server error occurs, check arcweave_list_assets before uploading again, because the asset might already exist.

Download an asset file

Call arcweave_get_asset_file with projectId and assetId. It returns a url, expiresAt, method (GET), and headers. Download the file with a GET request to that URL within 10 minutes, without an Authorization header. Folders and assets without a file can't be downloaded.

Don't save transfer URLs, for example in custom CSS: they expire.

Element audio

REST reference: Elements.

Tool	Access	What it does
arcweave_create_element_audio	Write	Attaches the audio asset assetId to an element. Optional: mode (once, loop, or stop), volume, autoStopOnExit, delay, fadeIn, and fadeOut. Returns itemId, the reference's ID.
arcweave_update_element_audio	Write	Updates the audio reference itemId. Pass null for volume, fadeIn, or fadeOut to use the asset's own value.
arcweave_delete_element_audio	Write	Removes the audio reference itemId. The asset remains.
arcweave_move_element_audio	Write	Moves the audio reference itemId to index. Add targetElementId to move it to another element.