Let an agent edit your content, safely

Available in Pro. Writing to a site from an agent needs either the admin persona, authenticated with an API key, or an OAuth token carrying write access — and both API keys and the OAuth server are Pro features. If update_object is missing from an agent's tool list, it is connected read-only. Everything an agent writes goes through the same save path as the admin form: schema validation, slug generation, and the same events the CMS fires for a human edit.

The safe default is patch_object. It merges only the fields you send over the stored object, so omitted fields keep their current values and there is nothing to round-trip and nothing to lose by accident. Three rules govern the merge: containers — cards, decks and lists — replace whole, so send the complete container to change any part of it; clearing is explicit, meaning an empty string or an empty array, because omitting a field never clears it; and a content write never puts a file in a field.

That last rule is what makes agent editing safe on content-rich collections. A patch never touches the file in an image, file, gallery or depot field, so a blog post with a hero image is fully writable by an agent and the hero keeps the image it has. The write can still describe a file that is already there: its alt text, a credit, tags, a focal point or a download label.

Putting a file in a field is a separate, deliberate call. attach_file_from_url downloads a file from a public URL and saves it the way the admin's upload button does: an image or file is replaced, a gallery gains it at the end, and a depot gains it in a folder, with the alt text and credit set in the same call. remove_file deletes one. Both need the same access as patch_object, and attaches are limited to 60 an hour per caller.

When you genuinely mean to rewrite a whole record, update_object replaces it, and whatever you omit reverts to its default. Fetch the object with format: "html" first — the default markdown converts styled-text fields for reading, and writing that conversion back would permanently replace the original HTML. Edit what needs changing, strip the url key that read tools decorate results with, and send the whole body. After any write, do not clear the cache: object writes fire the update event, which invalidates the affected page caches for you.

Reach is capped independently of intent. Every authenticated call clears three gates — the scope the person consented to, what their access groups grant on that collection, and whether the collection is exposed to MCP at all. A blogger's token can save into the blog and is refused on products, however broad its scopes. And what an agent produces depends on what you tell it: schema descriptions and property help text are its only documentation of your content model. tcms schema:lint --strict fails on the ones you left empty.