Media Upload
The Media Upload tool (internal name builtin_system_mediaupload) puts a file into your store's media storage (pub/media) and returns its path and public URL. It can also list the files in a media directory and delete one.
The tool moves files and nothing else. Attaching a stored file to a record — a product, a category, a CMS page — is a separate REST call the AI client makes afterwards, so the permission on that record still decides whether it may.
Access control
Access to this tool is controlled by the MCP Tools -> Built in -> System -> Media Upload ACL resource. Enable or disable it in System -> Permissions -> User Roles -> [Role] -> Role Resources. This resource controls whether the tool is visible to the role.
Every action additionally requires the role's core Content -> Media Gallery (Magento_Cms::media_gallery) permission — the same permission that opens the media browser in the admin. A role without it cannot list media through this tool either, matching what that role can already see in the admin.
Uploading and deleting also require the store-config switch Allow writing to media storage (default enabled) — see Settings. With it disabled, the tool is read-only: the AI client can still list existing media to reference it, but cannot upload or delete.
When to use
The AI client uses this tool whenever a task needs a file that isn't in the store yet — a product photo, a banner for a CMS block, a category image. Before this tool, the only way to get an image in was FTP or admin access, because Magento's product media endpoint expects the image encoded inside the request, which an AI client cannot produce for a real photograph.
See How to add images to products and pages for the complete workflow.
Where files go
Naming the entity puts the file where that entity keeps its media, with that folder's file-type rules:
entity | Destination | Accepted types |
|---|---|---|
product | tmp/catalog/product | jpg, jpeg, png, gif |
category | catalog/category | jpg, jpeg, gif, png |
| (omitted) | wysiwyg — the media library CMS content references | jpg, jpeg, png, gif, plus any type added in Settings |
Use directory instead to write anywhere else under pub/media — a third-party module's own media folder, for example. Other extensions can register their own entity here, so this list grows with what you have installed.
A product image is uploaded to a staging folder and moved into the catalog when it is assigned to the product, which is why entity: product reports tmp/catalog/product. Delete the staged file afterwards if the assignment does not go ahead.
Parameters
| Parameter | Description | Type | Required |
|---|---|---|---|
action | The operation to perform. One of upload, check, list, delete. | string | Yes |
entity | upload, list. The entity whose media folder the file belongs in. One of product, category. Omit to use the media library. | string | No |
directory | upload, list. A directory relative to pub/media, for destinations no entity covers. Ignored when entity is given. | string | No |
filename | upload with source_url. The name to store the file under. The extension always follows the file's real content, and the effective name is returned. | string | No |
source_url | upload. A public, direct URL the store downloads the file from. Omit to receive an upload link instead. | string | No |
overwrite | upload. Replace an existing file at the same path. Defaults to false, in which case the existing file is reported rather than replaced. | boolean | No |
upload_id | check. The identifier returned when an upload link was issued. | integer | Conditional |
path | delete. The media-relative path of the file to remove. | string | Conditional |
Two ways a file gets in
From a URL. Give the tool a public, direct link and the store downloads the file itself. The URL must point at the file rather than at a page showing it, because redirects are not followed, and addresses inside your own network are refused.
From your own device. With no source_url, the tool returns a short-lived upload link. Open it and choose the file — the page works in a phone browser, so a photo can go straight from your camera roll into the store. The link is the only credential involved:
- single use, and valid for 15 minutes
- locked to one folder, with the size and file-type limits fixed when it was issued
- no admin session needed, and no store token ever appears in the conversation
Once you have uploaded, tell the assistant and it will confirm where the file landed. The stored name comes from the file you chose.
The maximum upload size is your server's own PHP limit (upload_max_filesize). Photos straight from a phone are often larger than the common 2 MB default — if the page reports the file did not reach the server, that limit is usually why.
Settings
The Media Upload settings are located at Stores -> Configuration -> Mirasvit Extensions -> MCP Tools -> Tools -> Media Upload.
To apply changes, clear the Magento cache after modifying these settings.
- Allow writing to media storage (Yes/No, default Yes): set to No to make the tool read-only. The AI client can still list existing media so it can reference it, but cannot upload or delete, whatever permissions the connected role holds.
- Additional allowed file types: extensions to accept beyond the images Magento itself accepts (
jpg,jpeg,png,gif) — for examplepdf, csv, xmlfor documents your store serves frompub/media. Entities with their own file-type list are unaffected, so a product gallery keeps accepting images only.