Cloudinary for AI Agents

Key Takeaways:

• Connect: Cloudinary publishes five MCP servers (Asset Management, Environment Config, Structured Metadata, Analysis, and MediaFlows) that expose its APIs as agent-callable tools. They run as remote OAuth endpoints or as local npx processes.
• Upload and transform: An agent uploads through the MCP Asset Management tool, the cld CLI, or a backend SDK. Transformations are URL parameters (f_auto, q_auto, c_auto, g_auto), so generating a variant means constructing a URL, not running a local binary.
• Run commands: The Cloudinary CLI (cld) gives an agent a deterministic, scriptable surface for Admin and Upload API operations from a shell.
• Sign URLs: Backend SDKs generate signed delivery URLs (sign_url: true) for authenticated or restricted assets, producing the /s--SIGNATURE--/ component server-side, never in the browser.

If you’re building an AI agent that has to upload, transform, or deliver media, you have two choices: hand the agent a pile of raw HTTP calls and hope it constructs them correctly, or give it a typed interface it can call like any other tool. Cloudinary is built for the second path.

It exposes its media platform to agents through Model Context Protocol (MCP) servers, a scriptable CLI, language SDKs, and signed-URL generation — so an agent can store an image, generate a responsive variant, and hand back a secure delivery URL without you writing glue code for each step.

This page is the map. It covers the four things an agent actually needs to do with media (connect, upload and transform, run commands, and sign URLs) and the exact, current way to do each one.

In this article:

• How AI Agents Connect to Cloudinary: The MCP Servers
• Agentic Upload and Transform Patterns
• Using the Cloudinary CLI Inside an Agent
• Generating Signed URLs in Agent Workflows

How AI Agents Connect to Cloudinary: The MCP Servers

Model Context Protocol is an open standard for exposing tools and data to LLM-based agents. Cloudinary’s AI Agent Tools and MCP Servers implement it, so an agent in Cursor, Claude Desktop, Claude Code, VS Code, or any MCP-capable client can call Cloudinary operations as native tools instead of reverse-engineering REST endpoints.

There are five servers, each scoped to a slice of the platform:

There are five servers, each scoped to a slice of the platform:

Each local server needs Node.js 18 or later. Remote servers default to OAuth; you can also use API-key authentication, except the Analysis server, which is OAuth-only.

Connect a Local Server (Cursor, Claude Desktop, VS Code)

The local pattern is identical across clients: run the server with npx and pass your credentials as environment variables. Add this to your MCP config:

{
  "cloudinary-asset-mgmt": {
    "command": "npx",
    "args": ["-y", "--package", "@cloudinary/asset-management", "--", "mcp", "start"],
    "env": {
      "CLOUDINARY_CLOUD_NAME": "your_cloud_name",
      "CLOUDINARY_API_KEY": "your_api_key",
      "CLOUDINARY_API_SECRET": "your_api_secret"
    }
  }
}

In VS Code, add "type": "stdio" to that object. Replace the three credential values with the cloud name, API key, and API secret from your Cloudinary Console.

Connect a Remote Server with OAuth (Claude Code)

To skip credential handling entirely and let the user authorize via OAuth, point the client at the remote endpoint. In Claude Code:

For Claude Desktop, the remote pattern goes through the mcp-remote bridge:

{
  "cloudinary-asset-mgmt": {
    "command": "npx",
    "args": ["mcp-remote", "https://asset-management.mcp.cloudinary.com/mcp"]
  }
}

Once a server is connected, the agent sees Cloudinary operations as callable tools — uploading a file or searching the media library becomes a tool call, with the request shape enforced for it.

Agentic Upload and Transform Patterns

Two ideas make Cloudinary fit agent workflows cleanly.

First, uploads return structured JSON the agent can reason over; including public_id, secure_url, dimensions, and format.

Second, transformations are declarative URL parameters, not imperative file operations. Producing a variant is a string the agent builds, and Cloudinary generates it on first request and CDN-caches it after.

There are three upload surfaces, and an agent can use whichever fits its environment.

1. MCP tool call: With the Asset Management server connected, the agent calls the upload tool directly. No code; the tool schema tells the model exactly what arguments to pass, which sharply reduces malformed requests.
2. Backend SDK: Inside agent code, a backend SDK handles the upload and returns the result object:

const result = await cloudinary.uploader.upload('product.jpg', {
  folder: 'catalog',
  tags: ['agent-upload'],
});
// result.public_id, result.secure_url, result.width, result.height …

1. CLI: For shell-based agents, one command uploads and prints the JSON response (covered in the next section).

Whichever surface uploaded the asset, transforming it is the same move: express the transformation in the delivery URL:

https://res.cloudinary.com/<cloud_name>/image/upload/f_auto,q_auto,c_auto,g_auto,w_800/product.jpg

That URL says: deliver product.jpg at 800px wide, auto-cropped to the most relevant region (c_auto,g_auto), in the best format (f_auto) and quality (q_auto) for the requesting browser. The agent doesn’t process pixels; it composes a string. Every parameter is documented in the Transformation URL API Reference, and the image optimization guide covers the auto-* set in depth.

Using the Cloudinary CLI Inside an Agent

The Cloudinary CLI (cld) is often the best surface for an agent that already works in a shell: it’s deterministic, scriptable, and returns structured output you can pipe into the next step. It wraps the Admin and Upload APIs, so anything the APIs do, the agent can do from a terminal.

Install it with pip (Python 3.6 or later):

pip3 install cloudinary-cli

Point it at your product environment with one environment variable:

export CLOUDINARY_URL=cloudinary://<API_KEY>:<API_SECRET>@<CLOUD_NAME>

Now the agent can upload and generate URLs as plain commands:

# Upload an asset and get back JSON the agent can parse
cld uploader upload product.jpg public_id=hero folder=catalog
# Generate a delivery URL for an existing asset
cld url -rt video -o cli_video/setup

Run cld config to confirm the active cloud name, API key, and signature algorithm. Because every command is explicit and the output is structured, the CLI gives an agent a tight, auditable loop.

Generating Signed URLs in Agent Workflows

Some assets shouldn’t be delivered with an open, guessable URL. Cloudinary requires a signed delivery URL in cases including authenticated assets, assets delivered with strict transformations enabled, certain add-ons on first use, and restricted media types. A signed URL carries a signature component in the format /s--SIGNATURE--/, where the signature is a URL-safe base64 SHA digest of the transformation string plus public ID, hashed with your API secret. Full details are in Generating delivery URL signatures.

The rule that matters for agents: signing happens server-side. Your API secret is required to create the signature, so it must never be exposed to a browser, a frontend, or any untrusted context. An agent generating signed URLs has to do it from a backend SDK or a trusted CLI environment.

With a backend SDK, set sign_url: true and let it build the signature for you:

const url = cloudinary.url('sample-authenticated', {
  type: 'authenticated',
  sign_url: true,
  transformation: [{ width: 300, height: 300, crop: 'auto', gravity: 'auto' }],
});
// → https://res.cloudinary.com/<cloud_name>/image/authenticated/s--SIGNATURE--/c_auto,g_auto,h_300,w_300/sample-authenticated

The CLI does the same with the -s flag:

cld url -s sample-authenticated c_auto,g_auto,h_300,w_300

By default the SDKs use SHA-1; set the signature_algorithm configuration parameter to sha256 if you want SHA-256 digests instead. Either way, the agent gets a delivery URL that’s valid only for the exact transformation it signed: change the transformation and the signature no longer matches.

Putting It Together

A media-aware agent built on Cloudinary follows one clean arc:

• Connect through an MCP server
• Upload through that server’s tool (or the SDK or CLI)
• Transform by composing a delivery URL
• Sign that URL server-side when the asset is protected.

Each step has a typed, documented surface, so the agent spends its tokens on the task rather than on guessing API shapes, and you spend your time on the workflow rather than on glue.

That’s the whole point of designing for agent experience: the platform meets the agent where it already operates (with tools, shells, and URLs) instead of forcing it through brittle, hand-assembled HTTP.

Ready to build it? Sign up for a free Cloudinary account and connect your first MCP server.

Frequently Asked Questions

Does Cloudinary have an official MCP server?

Yes. Cloudinary publishes five MCP servers: Asset Management, Environment Config, Structured Metadata, Analysis, and MediaFlows documented on the AI Agent Tools and MCP Servers page. They run as remote OAuth endpoints or local npx processes requiring Node.js 18+.

How does an AI agent upload an image to Cloudinary?

1. Call the upload tool on the connected Asset Management MCP server
2. Use a backend SDK’s uploader.upload() method
3. Run cld uploader upload from the CLI.

All three return a structured response with the asset’s public_id and secure_url.

How does an agent transform an image without downloading it?

Transformations are expressed as URL parameters, so the agent builds a delivery URL like .../image/upload/f_auto,q_auto,w_800/photo.jpg. Cloudinary generates the derived asset on the first request and serves it from the CDN afterward; there’s no local file step.

Can an agent generate signed Cloudinary URLs?

Yes, from a trusted backend. Set sign_url: true in a backend SDK or use cld url -s in the CLI. Because signing requires your API secret, it must happen server-side and never in a browser or frontend.

Which MCP client can connect to Cloudinary?

Any MCP-capable client (like Cursor, Claude Desktop, Claude Code, and VS Code) are all documented. Local servers connect via an npx command with credentials as environment variables; remote servers connect over OAuth.

Do I need a paid plan to use the MCP servers or CLI?

No. Cloudinary’s free tier is self-serve with no credit card, and the MCP servers, CLI, and SDKs all work against it.