MCP Media Upload

Agents can upload binary images into the media library and attach them to posts without using the admin UI or OpenAI image generation.

Tools#

Tool	Ability	Permission
list-media	mcp:media.read	media.view
upload-media	mcp:media.write	media.create
attach-featured-image	mcp:posts.update	post.edit

Generate a fresh MCP token after granting media.create so the token includes mcp:media.write.

Recommended workflow#

1. create-post (include_images: false) → post_id
2. upload-media(filename, mime_type, content_base64) → media.id
3. attach-featured-image(post_id, media_id)
4. assign-post-terms / generate-seo-meta
5. update-post (status: published) when ready

upload-media input#

{
  "filename": "wordpress-laravel-migration-checklist-hero.png",
  "mime_type": "image/png",
  "content_base64": "<base64 bytes>",
  "title": "Optional media title",
  "alt_text": "Optional alt text"
}

Constraints#

• Max decoded size: 5 MB
• Allowed types: image MIME types supported by the admin media library (png, jpeg, webp, gif, svg, …)
• filename extension must match mime_type
• Uses the same validation and storage pipeline as Settings → Media uploads

upload-media output#

{
  "message": "Media uploaded successfully.",
  "media": {
    "id": 123,
    "name": "wordpress-laravel-migration-checklist-hero",
    "file_name": "wordpress-laravel-migration-checklist-hero.png",
    "mime_type": "image/png",
    "size": 38794,
    "human_readable_size": "37.89 KB",
    "url": "https://your-site.com/storage/media/....png",
    "created_at": "2026-09-10T12:00:00+00:00"
  }
}

Chain directly into attach-featured-image with media_id.

Errors#

Case	Result
Missing mcp:media.write	MCP error mentioning mcp:media.write
Invalid base64 / MIME / size	Validation error message
Missing media.create permission	Permission error

Notes#

• create-post include_images: true is optional and requires OpenAI. Agents with local brand heroes should use upload-media instead.
• Uploaded files appear in the admin Media library and in list-media.