wp_upload_media_from_url: upload media from a URL

Downloads a public image and adds it to the media library. Your server makes the request, which is why this tool is fenced more tightly than any other in the server.

Arguments

Permissions

Allow content writes open, and upload_files.

The four fences

Because this tool makes your server fetch a URL an assistant chose, it is constrained at four points.

1. URL. Only http and https, ports 80 or 443, and at most 2,048 characters. Embedded credentials and fragments are refused. Invalid URLs return pom_ai_mcp_invalid_url.

2. Host resolution. The hostname's IPv4 addresses are resolved before the request, and every returned address is checked. If any is private or reserved, the request is refused with pom_ai_mcp_private_host.

That is the important one. It means the tool cannot be pointed at localhost, at an internal service, at a cloud metadata endpoint, or at a public hostname that resolves to a private address. A host that cannot be resolved at all is pom_ai_mcp_invalid_host.

The validated address is pinned for the request using WordPress's cURL transport. Servers without that transport must use wp_upload_media with a supported raster image payload.

3. No redirects. The URL must return the image directly. Any redirect makes the response non-2xx from the tool's point of view, and it fails with pom_ai_mcp_media_download_failed.

4. Size and type. The download is capped at 10 MB, and the result goes through the same double validation as a base64 upload — filename extension, then actual contents.

The redirect rule catches everyone

A URL that works perfectly in a browser can fail here, because the browser followed a redirect that this tool will not.

Common cases:

• link shorteners;
• a CDN or image service that redirects to a signed URL;
• http redirecting to https;
• a hosting platform redirecting to a regional domain;
• a trailing-slash or canonical-host redirect.

When a URL fails and looks fine, this is almost always why. The fix is to resolve the redirect yourself and pass the final URL, or to fetch the bytes and use wp_upload_media instead.

The filename comes from the URL path

The stored filename is derived from the last path segment of the URL, falling back to remote-image.jpg when there is none.

That has a consequence: a URL ending in something without a recognised image extension fails the extension check, even when the response is a perfectly good JPEG. Image delivery URLs with query-string parameters and no file extension are the usual example.

Again, the base64 tool is the answer — it lets you name the file yourself.

Use the dry run

dry_run returns the URL it would fetch, without fetching it:

Use a dry run and show me the URL you would download.

Its value is confirming the assistant resolved the URL you meant, before your server makes an outbound request on its behalf.

What it returns

The created attachment in the standard shape, including the new id.

When to use this rather than base64

Only when you genuinely have a public, direct, non-redirecting URL and not the bytes. In practice that is narrower than it sounds, and wp_upload_media is the more reliable default.

Using it well

Use a dry run for this URL, then upload it and show me the attachment ID.

Then set the alt text as a separate step — uploading never sets it.

Common problems

Related

• wp_upload_media — the more flexible route
• wp_update_media
• What POM AI MCP does not expose