How to integrate Cloudinary MCP with Mastra AI

This guide walks you through connecting Cloudinary to Mastra AI using the Composio tool router. By the end, you'll have a working Cloudinary agent that can create a new folder for event photos, delete derived assets with ids [123,456], set up upload preset with watermarking through natural language commands. This guide will help you understand how to give your Mastra AI agent real control over a Cloudinary account through Composio's Cloudinary MCP server. Before we dive in, let's take a quick look at the key ideas and tools involved.

Get started for freeGet a demo
Cloudinary logoCloudinary
Api Key

Cloudinary is a cloud-based platform for managing, uploading, and transforming images and videos. It streamlines media workflows and delivers optimized assets globally.

108 Tools

Introduction

This guide walks you through connecting Cloudinary to Mastra AI using the Composio tool router. By the end, you'll have a working Cloudinary agent that can create a new folder for event photos, delete derived assets with ids [123,456], set up upload preset with watermarking through natural language commands.

This guide will help you understand how to give your Mastra AI agent real control over a Cloudinary account through Composio's Cloudinary MCP server.

Before we dive in, let's take a quick look at the key ideas and tools involved.

Also integrate Cloudinary with

OpenAI Agents SDKClaude Agent SDKClaude CodeClaude CoworkCodexOpenClawHermesCLIGoogle ADKLangChainVercel AI SDKLlamaIndexCrewAI

TL;DR

Here's what you'll learn:
  • Set up your environment so Mastra, OpenAI, and Composio work together
  • Create a Tool Router session in Composio that exposes Cloudinary tools
  • Connect Mastra's MCP client to the Composio generated MCP URL
  • Fetch Cloudinary tool definitions and attach them as a toolset
  • Build a Mastra agent that can reason, call tools, and return structured results
  • Run an interactive CLI where you can chat with your Cloudinary agent

What is Mastra AI?

Mastra AI is a TypeScript framework for building AI agents with tool support. It provides a clean API for creating agents that can use external services through MCP.

Key features include:

  • MCP Client: Built-in support for Model Context Protocol servers
  • Toolsets: Organize tools into logical groups
  • Step Callbacks: Monitor and debug agent execution
  • OpenAI Integration: Works with OpenAI models via @ai-sdk/openai

What is the Cloudinary MCP server, and what's possible with it?

The Cloudinary MCP server is an implementation of the Model Context Protocol that connects your AI agent and assistants like Claude, Cursor, etc directly to your Cloudinary account. It provides structured and secure access to your digital asset management system, so your agent can perform actions like organizing folders, creating metadata fields, managing upload presets, and handling asset deletion on your behalf.

  • Automated folder and asset organization: Easily instruct your agent to create new asset folders or remove empty ones, keeping your Cloudinary library tidy and structured.
  • Metadata management: Let your agent create custom metadata fields or delete obsolete ones, extending and refining your asset tagging and search capabilities.
  • Preset and upload mapping creation: Have your agent set up upload presets with specific options or define dynamic folder mappings, automating consistent upload processes across your assets.
  • Resource and derived asset cleanup: Direct your agent to permanently delete assets by ID or remove unnecessary derived resources, ensuring your storage stays efficient and clutter-free.
  • Datasource entry management: Ask your agent to inactivate or delete specific datasource entries from metadata fields, keeping your metadata schema accurate and up to date.

What is the Composio tool router, and how does it fit here?

What is Composio SDK?

Composio's Composio SDK helps agents find the right tools for a task at runtime. You can plug in multiple toolkits (like Gmail, HubSpot, and GitHub), and the agent will identify the relevant app and action to complete multi-step workflows. This can reduce token usage and improve the reliability of tool calls. Read more here: Getting started with Composio SDK

The tool router generates a secure MCP URL that your agents can access to perform actions.

How the Composio SDK works

The Composio SDK follows a three-phase workflow:

  1. Discovery: Searches for tools matching your task and returns relevant toolkits with their details.
  2. Authentication: Checks for active connections. If missing, creates an auth config and returns a connection URL via Auth Link.
  3. Execution: Executes the action using the authenticated connection.

Step-by-step Guide

Step by step09 STEPS
1

Prerequisites

Before starting, make sure you have:
  • Node.js 18 or higher
  • A Composio account with an active API key
  • An OpenAI API key
  • Basic familiarity with TypeScript
2

Getting API Keys for OpenAI and Composio

OpenAI API Key
  • Go to the OpenAI dashboard and create an API key.
  • You need credits or a connected billing setup to use the models.
  • Store the key somewhere safe.
Composio API Key
  • Log in to the Composio dashboard.
  • Go to Settings and copy your API key.
  • This key lets your Mastra agent talk to Composio and reach Cloudinary through MCP.
3

Install dependencies

bash
npm install @composio/core @mastra/core @mastra/mcp @ai-sdk/openai dotenv

Install the required packages.

What's happening:

  • @composio/core is the Composio SDK for creating MCP sessions
  • @mastra/core provides the Agent class
  • @mastra/mcp is Mastra's MCP client
  • @ai-sdk/openai is the model wrapper for OpenAI
  • dotenv loads environment variables from .env
4

Set up environment variables

bash
COMPOSIO_API_KEY=your_composio_api_key_here
COMPOSIO_USER_ID=your_user_id_here
OPENAI_API_KEY=your_openai_api_key_here

Create a .env file in your project root.

What's happening:

  • COMPOSIO_API_KEY authenticates your requests to Composio
  • COMPOSIO_USER_ID tells Composio which user this session belongs to
  • OPENAI_API_KEY lets the Mastra agent call OpenAI models
5

Import libraries and validate environment

typescript
import "dotenv/config";
import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";
import { MCPClient } from "@mastra/mcp";
import { Composio } from "@composio/core";
import * as readline from "readline";

import type { AiMessageType } from "@mastra/core/agent";

const openaiAPIKey = process.env.OPENAI_API_KEY;
const composioAPIKey = process.env.COMPOSIO_API_KEY;
const composioUserID = process.env.COMPOSIO_USER_ID;

if (!openaiAPIKey) throw new Error("OPENAI_API_KEY is not set");
if (!composioAPIKey) throw new Error("COMPOSIO_API_KEY is not set");
if (!composioUserID) throw new Error("COMPOSIO_USER_ID is not set");

const composio = new Composio({
  apiKey: composioAPIKey as string,
});
What's happening:
  • dotenv/config auto loads your .env so process.env.* is available
  • openai gives you a Mastra compatible model wrapper
  • Agent is the Mastra agent that will call tools and produce answers
  • MCPClient connects Mastra to your Composio MCP server
  • Composio is used to create a Tool Router session
6

Create a Tool Router session for Cloudinary

typescript
async function main() {
  const session = await composio.create(
    composioUserID as string,
    {
      toolkits: ["cloudinary"],
    },
  );

  const composioMCPUrl = session.mcp.url;
  console.log("Cloudinary MCP URL:", composioMCPUrl);
What's happening:
  • create spins up a short-lived MCP HTTP endpoint for this user
  • The toolkits array contains "cloudinary" for Cloudinary access
  • session.mcp.url is the MCP URL that Mastra's MCPClient will connect to
7

Configure Mastra MCP client and fetch tools

typescript
const mcpClient = new MCPClient({
    id: composioUserID as string,
    servers: {
      nasdaq: {
        url: new URL(composioMCPUrl),
        requestInit: {
          headers: session.mcp.headers,
        },
      },
    },
    timeout: 30_000,
  });

console.log("Fetching MCP tools from Composio...");
const composioTools = await mcpClient.getTools();
console.log("Number of tools:", Object.keys(composioTools).length);
What's happening:
  • MCPClient takes an id for this client and a list of MCP servers
  • The headers property includes the x-api-key for authentication
  • getTools fetches the tool definitions exposed by the Cloudinary toolkit
8

Create the Mastra agent

typescript
const agent = new Agent({
    name: "cloudinary-mastra-agent",
    instructions: "You are an AI agent with Cloudinary tools via Composio.",
    model: "openai/gpt-5",
  });
What's happening:
  • Agent is the core Mastra agent
  • name is just an identifier for logging and debugging
  • instructions guide the agent to use tools instead of only answering in natural language
  • model uses openai("gpt-5") to configure the underlying LLM
9

Set up interactive chat interface

typescript
let messages: AiMessageType[] = [];

console.log("Chat started! Type 'exit' or 'quit' to end.\n");

const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout,
  prompt: "> ",
});

rl.prompt();

rl.on("line", async (userInput: string) => {
  const trimmedInput = userInput.trim();

  if (["exit", "quit", "bye"].includes(trimmedInput.toLowerCase())) {
    console.log("\nGoodbye!");
    rl.close();
    process.exit(0);
  }

  if (!trimmedInput) {
    rl.prompt();
    return;
  }

  messages.push({
    id: crypto.randomUUID(),
    role: "user",
    content: trimmedInput,
  });

  console.log("\nAgent is thinking...\n");

  try {
    const response = await agent.generate(messages, {
      toolsets: {
        cloudinary: composioTools,
      },
      maxSteps: 8,
    });

    const { text } = response;

    if (text && text.trim().length > 0) {
      console.log(`Agent: ${text}\n`);
        messages.push({
          id: crypto.randomUUID(),
          role: "assistant",
          content: text,
        });
      }
    } catch (error) {
      console.error("\nError:", error);
    }

    rl.prompt();
  });

  rl.on("close", async () => {
    console.log("\nSession ended.");
    await mcpClient.disconnect();
    process.exit(0);
  });
}

main().catch((err) => {
  console.error("Fatal error:", err);
  process.exit(1);
});
What's happening:
  • messages keeps the full conversation history in Mastra's expected format
  • agent.generate runs the agent with conversation history and Cloudinary toolsets
  • maxSteps limits how many tool calls the agent can take in a single run
  • onStepFinish is a hook that prints intermediate steps for debugging

Complete Code

Here's the complete code to get you started with Cloudinary and Mastra AI:

typescript
import "dotenv/config";
import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";
import { MCPClient } from "@mastra/mcp";
import { Composio } from "@composio/core";
import * as readline from "readline";

import type { AiMessageType } from "@mastra/core/agent";

const openaiAPIKey = process.env.OPENAI_API_KEY;
const composioAPIKey = process.env.COMPOSIO_API_KEY;
const composioUserID = process.env.COMPOSIO_USER_ID;

if (!openaiAPIKey) throw new Error("OPENAI_API_KEY is not set");
if (!composioAPIKey) throw new Error("COMPOSIO_API_KEY is not set");
if (!composioUserID) throw new Error("COMPOSIO_USER_ID is not set");

const composio = new Composio({ apiKey: composioAPIKey as string });

async function main() {
  const session = await composio.create(composioUserID as string, {
    toolkits: ["cloudinary"],
  });

  const composioMCPUrl = session.mcp.url;

  const mcpClient = new MCPClient({
    id: composioUserID as string,
    servers: {
      cloudinary: {
        url: new URL(composioMCPUrl),
        requestInit: {
          headers: session.mcp.headers,
        },
      },
    },
    timeout: 30_000,
  });

  const composioTools = await mcpClient.getTools();

  const agent = new Agent({
    name: "cloudinary-mastra-agent",
    instructions: "You are an AI agent with Cloudinary tools via Composio.",
    model: "openai/gpt-5",
  });

  let messages: AiMessageType[] = [];

  const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout,
    prompt: "> ",
  });

  rl.prompt();

  rl.on("line", async (input: string) => {
    const trimmed = input.trim();
    if (["exit", "quit"].includes(trimmed.toLowerCase())) {
      rl.close();
      return;
    }

    messages.push({ id: crypto.randomUUID(), role: "user", content: trimmed });

    const { text } = await agent.generate(messages, {
      toolsets: { cloudinary: composioTools },
      maxSteps: 8,
    });

    if (text) {
      console.log(`Agent: ${text}\n`);
      messages.push({ id: crypto.randomUUID(), role: "assistant", content: text });
    }

    rl.prompt();
  });

  rl.on("close", async () => {
    await mcpClient.disconnect();
    process.exit(0);
  });
}

main();

Conclusion

You've built a Mastra AI agent that can interact with Cloudinary through Composio's Tool Router. You can extend this further by:
  • Adding other toolkits like Gmail, Slack, or GitHub
  • Building a web-based chat interface around this agent
  • Using multiple MCP endpoints to enable cross-app workflows
TOOLS

Supported Tools

Every Cloudinary action and event your agent gets out of the box.

Activate Live Stream

Tool to manually activate a Cloudinary live stream.

Create Asset Relations by Asset ID

Tool to add related assets by asset ID.

Create Asset Relations by Public ID

Tool to create relations between assets by public ID.

Create Folder

Tool to create a new asset folder.

Create Image from Text

Tool to create an image from text using Cloudinary's text generation API.

Create Live Stream

Tool to create a new live stream in Cloudinary.

Create Live Stream Output

Tool to create a new live stream output configuration.

Create Metadata Field

Tool to create a new metadata field definition.

Create Metadata Rule

Tool to create a new conditional metadata rule.

Create Multi-Resource Animation

Tool to create an animated image, video, or PDF from a set of images.

Create Slideshow

Tool to create an auto-generated video slideshow from existing Cloudinary assets.

Create Streaming Profile

Tool to create a new adaptive streaming profile in your Cloudinary account.

Create Transformation

Tool to create a new named transformation by assigning a custom name to a set of transformation parameters.

Create Trigger

Tool to create a new webhook trigger for a specified event type.

Create Upload Mapping

Tool to create a new upload mapping folder and URL template.

Create Upload Preset

Tool to create a new upload preset.

Delete Asset Relations by Asset ID

Tool to delete asset relations by asset ID.

Delete Asset Relations by Public ID

Tool to delete asset relations by public ID.

Delete Derived Resources

Tool to delete derived assets.

Delete Metadata Field Datasource Entries

Tool to delete datasource entries for a specified metadata field.

Delete Folder

Tool to delete an empty asset folder.

Delete Live Stream

Tool to delete a live stream from Cloudinary.

Delete Live Stream Output

Tool to delete a live stream output from Cloudinary.

Delete Metadata Field

Tool to delete a metadata field by external ID.

Delete Metadata Rule

Tool to delete a conditional metadata rule by its ID.

Delete Resources by Asset ID

Tool to delete resources by asset IDs.

Delete Resources by Public ID

Tool to delete Cloudinary resources by public ID, prefix, or all resources.

Delete Resources by Tags

Tool to delete Cloudinary assets by tag.

Delete Streaming Profile

Tool to delete a custom streaming profile or revert a built-in profile to original settings.

Delete Transformation (v2)

Tool to delete a named transformation from your Cloudinary account.

Delete Trigger

Tool to delete a trigger (webhook notification).

Delete Upload Mapping

Tool to delete a folder upload mapping.

Delete Upload Preset

Tool to delete an upload preset from the account.

Destroy Asset

Tool to permanently destroy a Cloudinary asset/resource by public ID.

Destroy Asset by ID

Tool to delete an asset by its immutable asset ID.

Explicit Resource Update

Tool to update an existing asset and/or eagerly generate derived transformations using Cloudinary's Explicit API.

Explode Multi-Page Resource

Tool to create derived images from multi-page files (PDF, PSD, TIFF, animated GIF) by exploding them into separate images.

Generate Archive

Tool to create an archive (ZIP or TGZ file) containing a set of assets from your Cloudinary environment.

Get Adaptive Streaming Profiles

Tool to list adaptive streaming profiles.

Get Analysis Task Status

Tool to get the status of an analysis task.

Get product environment config details

Tool to get product environment config details.

Get Live Stream

Tool to get details of a single live stream by ID.

Get Live Stream Output

Tool to get details of a single live stream output.

Get Live Stream Outputs

Tool to get a list of live stream outputs.

Get Live Streams

Tool to get a list of live streams from Cloudinary.

Get Metadata Field By ID

Tool to get a single metadata field definition by external ID.

Get Resource by Asset ID

Get Resource by Asset ID

Get Resource by Public ID

Tool to get details of a single resource by public ID.

Get Resources by Asset Folder

Tool to list assets stored directly in a specified folder.

Get Resources by Context

Tool to retrieve assets with a specified contextual metadata key/value.

Get Resources in Moderation

Tool to retrieve assets in a moderation queue by status.

Get Root Folders

Tool to list all root folders in the product environment.

Get Streaming Profile Details

Tool to get details of a single streaming profile by name.

Get Resource Tags

Tool to list all tags used for a specified resource type.

Get Transformation

Tool to retrieve details of a specific transformation.

Get Transformations

Tool to list all transformations (named and unnamed).

List Webhook Triggers

Tool to list all webhook triggers for event types in your environment.

Get Upload Mapping Details

Tool to retrieve details of a single upload mapping by folder.

Get Upload Mappings

Tool to list all upload mappings.

Get Upload Preset

Tool to retrieve details of a single upload preset by name.

Get Usage

Tool to get product environment usage details.

Get Video Views

Tool to get video analytics views from Cloudinary.

Idle Live Stream

Tool to manually idle a Cloudinary live stream.

List Images

Tool to list image assets from Cloudinary.

List Metadata Fields

Tool to list all structured metadata fields defined in your Cloudinary product environment.

List Metadata Rules

Tool to retrieve all conditional metadata rules defined in your Cloudinary account.

List Raw Files

Tool to list raw assets from Cloudinary.

List Resources by Asset IDs

Tool to retrieve multiple resources by their asset IDs.

List Resources by External IDs

Tool to retrieve resources by their external IDs.

List Resources by Tag

Tool to list resources (assets) with a specified tag.

List Resources by Type

Tool to retrieve resources (assets) by resource type and storage type.

List Resource Types

Tool to list all available resource types in your Cloudinary product environment.

List Upload Presets

Tool to list all upload presets configured in the account.

List Video Assets

Tool to list video assets from Cloudinary.

Manage Context Metadata

Tool to add or remove contextual metadata on Cloudinary assets.

Order Metadata Field Datasource

Tool to update ordering of a metadata field datasource.

Ping Cloudinary Servers

Tool to ping Cloudinary servers.

Publish Resources

Tool to publish Cloudinary assets by public IDs, prefix, or tag.

Rename or Move Resource Public ID

Tool to rename an asset's public ID using Cloudinary's rename endpoint.

Reorder Metadata Field

Tool to change the position of a specific metadata field.

Reorder Metadata Fields

Tool to reorder all metadata fields in the product environment.

Restore Metadata Field Datasource Entries

Tool to restore previously deleted datasource entries for a metadata field.

Restore Deleted Resources

Tool to restore deleted Cloudinary resources by public IDs.

Restore Resources by Asset IDs

Tool to restore backed up assets by asset IDs.

Search Assets

Tool to search and filter assets using powerful query expressions.

Search Datasource in Metadata Field

Tool to search datasource values in a metadata field.

Search Folders

Tool to search asset folders with filtering, sorting, and pagination.

Search All Metadata Field Datasources

Tool to search across all metadata field datasources.

Visual Search Assets

Tool to find images in your asset library based on visual similarity or content.

Show Folder

Tool to list sub-folders within a specified folder.

Update Asset Metadata

Tool to populate or update metadata field values on one or more Cloudinary assets.

Update Folder

Tool to rename or move an existing asset folder.

Update Live Stream

Tool to update a live stream's configuration in Cloudinary.

Update Live Stream Output

Tool to modify an existing live stream output configuration.

Update Metadata Field

Tool to update a metadata field definition by external ID.

Update Metadata Field Datasource

Tool to update the datasource (allowed values) for a metadata field.

Update Metadata Rule

Tool to update an existing conditional metadata rule.

Update Resource by Asset ID

Tool to update asset properties by asset ID in Cloudinary.

Update Resource by Public ID

Tool to update asset properties by public ID in Cloudinary.

Update Resource Tags

Tool to add, remove, replace, or remove all tags for one or more Cloudinary assets.

Update Streaming Profile

Tool to modify an existing adaptive streaming profile's configuration.

Update Transformation (v2)

Tool to update the definition of an existing named transformation.

Update Trigger

Tool to update the callback URL of an existing webhook trigger.

Update Upload Mapping

Tool to update an existing upload mapping by changing its remote URL template.

Update Upload Preset

Tool to update an existing upload preset's configuration settings.

Upload Asset

Tool to upload media assets (images, videos, raw files) to Cloudinary.

Upload File Chunk

Tool to upload a single chunk of a large file to Cloudinary.

Upload File (Auto Detect)

Tool to upload files with automatic resource type detection.

FRAMEWORKS

How to build Cloudinary MCP Agent with another framework

OpenAI Agents SDK logo

OpenAI Agents SDK

Use Cloudinary MCP with OpenAI Agents SDK

Claude Agent SDK logo

Claude Agent SDK

Use Cloudinary MCP with Claude Agent SDK

Claude Code logo

Claude Code

Use Cloudinary MCP with Claude Code

Claude Cowork logo

Claude Cowork

Use Cloudinary MCP with Claude Cowork

Codex logo

Codex

Use Cloudinary MCP with Codex

OpenClaw logo

OpenClaw

Use Cloudinary MCP with OpenClaw

Hermes logo

Hermes

Use Cloudinary MCP with Hermes

CLI logo

CLI

Use Cloudinary MCP with CLI

Google ADK logo

Google ADK

Use Cloudinary MCP with Google ADK

LangChain logo

LangChain

Use Cloudinary MCP with LangChain

Vercel AI SDK logo

Vercel AI SDK

Use Cloudinary MCP with Vercel AI SDK

LlamaIndex logo

LlamaIndex

Use Cloudinary MCP with LlamaIndex

CrewAI logo

CrewAI

Use Cloudinary MCP with CrewAI

FAQ

Frequently asked questions

With a standalone Cloudinary MCP server, the agents and LLMs can only access a fixed set of Cloudinary tools tied to that server. However, with the Composio Tool Router, agents can dynamically load tools from Cloudinary and many other apps based on the task at hand, all through a single MCP endpoint.

Yes, you can. Mastra AI fully supports MCP integration. You get structured tool calling, message history handling, and model orchestration while Tool Router takes care of discovering and serving the right Cloudinary tools.

Yes, absolutely. You can configure which Cloudinary scopes and actions are allowed when connecting your account to Composio. You can also bring your own OAuth credentials or API configuration so you keep full control over what the agent can do.

All sensitive data such as tokens, keys, and configuration is fully encrypted at rest and in transit. Composio is SOC 2 Type 2 compliant and follows strict security practices so your Cloudinary data and credentials are handled as safely as possible.

Start with Cloudinary.It takes 30 seconds.

Managed auth, hosted MCP servers, and every Cloudinary tool your agent needs.Free to start.

Start building
Customer stories

Teams ship real agents on Composio

GET STARTED FOR FREEBOOK A DEMO
agent.aiZoomLettaGleanHubSpotAWSWabi

Karan skipped his own birthday party to fix our critical issue. It was 10pm and he diverted his Waymo to help us instead. This really sets the bar — it shows the commitment you need when users rely on your software.

Harsha Gaddipati
Harsha Gaddipati
Co-founder, Slashy

A lot of students tell us that the moment their connected tools start talking to each other inside Opennote feels almost magical. The agent just knows them, and it's immensely helped keep new users on the platform.

Abhi Arya
Abhi Arya
Co-founder, Opennote

We chose Composio over Pipedream because it delivered depth where it mattered — niche tools and tricky edge cases other platforms simply ignored. That gave us confidence to scale without compromising.

Nirman Dave
Nirman Dave
CEO, Zams

As a solo builder, shipping fast is life or death. The only way I can outcompete incumbents is by outmanoeuvring them. Getting bogged down managing agent auth would have been a death sentence.

Ryan Yu
Ryan Yu
Founder, Extra Thursday

Before Composio, adding tool integrations was slow and resource-intensive. Each one could take weeks of engineering time, and maintaining them meant constantly keeping up with API changes.

Tomisin Jenrola
Tomisin Jenrola
Founder & CEO, SwarmZero

With hands-on help from their founder, we integrated Gmail and Google Drive in just 30 minutes. This level of personal support and commitment is exactly what startups should strive for.

Jerome Leclanche
Jerome Leclanche
Co-Founder, Ingram Technologies