MCP tools

The tools of the agent endpoint POST /mcp. How to declare an agent and connect a client is under AI agents ; this page lists what a connected agent can call.

Arguments marked optional may be left out; every other argument is required, and no tool accepts an argument not listed. version is the value a read tool returned for the object being changed (see versions and conflicts ). Each tool needs the permissions of the operation it performs, checked by the same services as the screens.

Components

publication is { publicationId, publishedAt }, or null for a component never published.

attributes

update_component takes the component's attributes as an ordered list; the list's order is the attributes' order. Each item is:

get_component returns the attributes in this same shape, so a read can be edited and saved back. The component's type cannot change.

Pages

• component is a component uid. A component without a publication cannot be used: pages/unpublished-component:.
• parent, node and slot are a node's uid and the uid of one of its attributes of type components. position is 0-based; without it the node goes at the end.
• values maps attribute uids to values. Each must match its attribute's type and meta-schema, or the call fails with pages/invalid-value: and writes nothing. Attributes of type components change through add_node, move_node and remove_node, not set_values (pages/slot-not-a-value:).
• A page name has 1 to 200 characters, none of them /, \ or a control character, and is not . or .. (pages/invalid-name:). A name already taken fails with pages/exists:.

What get_page returns

{
  name: string
  previewURL: string
  root: string                       // the root node's uid
  nodes: Array<{                     // only nodes reachable from the root
    uid: string
    component: { uid: string, name: string }
    values: Array<{                  // in the component's attribute order
      uid: string, name: string, type: string,
      value: unknown                 // for a slot: the child node uids, in order
    }>
  }>
  version: string
}

Collections

• list_documents returns limit documents (1 to 200, 50 by default) and a next token while more remain; pass it back as pageToken. where is a list of conditions { field, operator, value }, all of which must hold: operator is one of ==, !=, <, <=, >, >=, and value a string, number, boolean or null. A condition on a field you may not read fails with documents/unreadable-field:.
• Documents carry only the fields you may read. The key field is part of data and cannot be set.
• A document that does not match the schema is refused with documents/invalid: <path> <keyword>, one pair per error, and nothing is written. Errors under a field you may not read are replaced by one hidden fields. An update is checked as it will be stored, together with the fields it keeps.
• update_document leaves fields not in data as they are and cannot remove one. The later save wins: nothing is checked against a version. A missing document fails with documents/not-found:. delete_document of a missing document is not an error.

Storage

bucket is a bucket name. An object name is levels separated by /, none of them empty, . or .., and does not end with /. A directory path is '' for the root, or such a name followed by /; anything else fails with storage/invalid-name:. A change under .genoacms/ of the default bucket fails with storage/internal-read-only:.

• lastModified and expiresAt are ISO 8601 strings, and next is absent on the last page. list_directory signs no URLs; get_object returns one, valid for an hour. The agent fetches the contents from it, and the URL is signed even for an object that does not exist.
• upload_object stores content as its UTF-8 bytes, or, with encoding: "base64", as the bytes it decodes to (storage/invalid-content: when it is not base64). At most 4,194,304 bytes (storage/too-large:). It refuses to replace an object (storage/exists:) unless overwrite is true, and the stored object has no content type.
• move_object refuses an existing destination, and move_directory one that holds anything (storage/exists:), unless overwrite is true. move_directory refuses a destination under path (storage/invalid-name:).
• create_directory, move_directory and delete_directory refuse the root. move_object and delete_object of a missing object fail with storage/not-found:.
• Moving without overwrite looks the destination up in a listing, so it needs storage:bucket:read as well.

Page edit errors