Named Transformations via an MCP Server: Create and Update

Before you start

You need three things in place, and the order matters.

A product environment with API credentials the MCP client can present. Remote Cloudinary MCP servers authenticate with OAuth; local ones need the environment’s credentials supplied by hand (Cloudinary’s MCP server documentation lists the five servers and their remote endpoints). If you are still deciding between the two, remote versus local MCP servers covers the trade. MCP server access is included on every plan, Free included, so this is not a paid-tier task.

The right server connected. Named transformations are configuration that belongs to the product environment, not to any single asset, so the tools you want live with the environment-level settings rather than with asset upload and search. Confirm which of the five servers your client has connected exposes transformation tools before the first step; the Environment Config MCP server is the one that owns environment settings, and if a project has connected only the Asset Management MCP server the agent will be able to see assets and not the transformation definitions behind their URLs.

An understanding of what you are about to touch. A named transformation gives a URL-shaped chain of operations — c_fill,w_800,h_600,g_auto,q_auto,f_auto, say — a single stable name, so a delivery URL references the name (t_hero) instead of restating the chain. Everything else on this page follows from that one property. Cloudinary’s named transformations reference describes the naming rules and how a name is referenced in a URL; the transformation reference lists the parameters a chain can contain.

Steps

1. Decide the intent, and name it after the intent.

   Create one named transformation per intent — hero, thumb, avatar, og-image — rather than one per page or per template. This is the step most people get wrong, and it is wrong in a way that only shows up months later. A named transformation per template converges on exactly the sprawl it was meant to prevent: forty names whose chains differ by a pixel, none of which anyone dares delete. One per intent keeps the list small enough that a human, or an agent, can read the whole thing and reason about what changing any entry will do.

   Write the intent down before asking the agent for anything, because the agent will happily create whatever it is told to. If two templates want the same visual treatment, they share a name. If a template genuinely needs a different treatment, that is a new intent, and the question to ask is whether the difference is real or whether the template should conform.

2. List what already exists.

   Before creating anything, have the agent list the environment’s current named transformations through the server. Two reasons. First, the name you want may already exist, and creating a near-duplicate is the first step down the sprawl path from step 1. Second, this listing is your baseline: you will compare against it after every change. If your client cannot show you the tool calls the agent made, sort that out first — seeing what an agent actually did through an MCP server is the prerequisite for trusting anything in steps 4 and 5.

3. Create the named transformation, then verify it in a URL.

   Ask the agent to create the transformation with the chain you decided on. Then, before referencing it anywhere in markup, request one asset through it — .../image/upload/t_hero/sample.jpg — and confirm the delivered image is what the chain describes. This is cheap and it catches the case where the agent transcribed the chain wrong, which is far easier to fix now than after fifty pages reference the name.

   Do not skip to using the name in markup because the tool call returned success. Success means the definition was stored; it says nothing about whether the definition is right.

4. Reference the name in delivery URLs, and only the name.

   Now put t_hero in the markup, and nothing else in that transformation segment. The moment a URL contains t_hero,w_900, you have two places that decide what the image looks like, and the point of the named transformation — one place to edit — is gone. If a page needs w_900 on top of hero, either that is a new intent (go back to step 1) or hero should be responsive and the width belongs inside the definition. If your project also drives transformation tools from a rules file, the same discipline applies: the rules should emit names, not chains.

5. Update the named transformation, knowing what an update does.

   Updating the named transformation changes every URL that references it. That is the mechanism that makes a sitewide image treatment editable in one place: change hero from q_auto to q_auto:eco through the server and every hero image on every page picks it up with no markup change and no deploy.

   That same property makes this the highest-leverage and highest-risk thing an agent can edit through an MCP server, because the change is invisible in the markup that uses it. A diff of your repository after an agent session will show nothing. Nothing in the templates changed; what changed is the meaning of a token those templates reference. An agent asked to “make the hero images a bit sharper” can, correctly and in one call, alter every page on the site, and the only evidence is in the server’s tool log and in the delivered images.

   So before an update: repeat the listing from step 2 and record the current chain for the name you are about to change, so you can restore it by hand if the update is wrong. Have the agent state the exact new chain before it makes the call, and compare it against the transformation reference yourself. Then make the change.

6. Invalidate, or re-request, before you judge the result.

   Cached derived assets do not regenerate on their own after an update. Every image already generated under the old hero definition is still sitting in the CDN cache, and until it is invalidated or the asset is re-requested after expiry, the old version keeps being served. So the update from step 5 is not visible yet, and the trap is to look at the site, see no change, assume the update failed, and apply it again — or apply something stronger.

   Cloudinary’s named transformations documentation covers invalidating derived assets after an update; do that, or accept that the change rolls out as caches expire rather than at once. Either way, check the result on an asset you know was cached before the update, not on a fresh upload, because a fresh upload will show the new chain and tell you nothing about the rest of the site.

What done looks like

The environment’s list of named transformations is short — one entry per intent — and you can say what each is for without opening the definition. Every delivery URL on the site carries a name and no additional transformation parameters in that segment. The listing you took in step 2 and the one you take after step 5 differ in exactly the entry you meant to change, and the tool log shows exactly the calls you expected. A previously cached asset requested after invalidation shows the new treatment.

And you have a written record of the intent behind each name, kept outside the environment, because the next agent session will not have your context and the markup will never reveal what a name means.