MCP for AI agents - Convertly Docs

Convertly MCP is a Model Context Protocol server that lets AI agents work with files on your computer and call Convertly’s media APIs from the same conversation. Organize downloads, archive old files, convert images, compress video, remove backgrounds, generate thumbnails, and look up Convertly documentation before running a workflow.

The MCP server only exposes folders you explicitly approve. API keys stay on your machine — they are not sent to the AI model.

Your MCP client starts the Convertly MCP server locally. The AI model does not receive unrestricted filesystem access — only the folders you approve are exposed through MCP tools. For a product overview and visual walkthrough, see the MCP & AI agents page.

How it works

Convertly MCP runs in two modes. Choose the one that matches your client and security needs.

Mode	Transport	Filesystem access	Best for
Local	stdio	✅ Full access to approved folders	Claude Desktop, Cursor, Cline, Windsurf
Remote	HTTP/SSE	❌ None	Web-based clients, remote servers, Lovable

Local mode (stdio) — recommended

Your MCP client launches the Convertly server as a local process. The server can read and write any folder you list in CONVERTLY_MCP_ROOTS. All filesystem paths are resolved and sandboxed to those roots.

Remote mode (HTTP/SSE)

You start the server manually as an HTTP service. AI agents can use all API-based tools (conversion, compression, docs, cloud storage, jobs) but cannot access your local filesystem. Filesystem tools return an error in this mode.

export CONVERTLY_API_KEY="<paste-your-key-here>"
CONVERTLY_MCP_HTTP_PORT=3000 npx @convertly-sh/mcp

Connect to http://localhost:3000/mcp. HTTP configuration:

CONVERTLY_MCP_HTTP_PORT — port to listen on
CONVERTLY_MCP_MAX_SESSIONS — max concurrent SSE sessions (default: 100)
CONVERTLY_MCP_SESSION_TIMEOUT_MS — idle session timeout in ms (default: 600000 = 10 min)
GET /health — health check endpoint

Client setup

Claude Desktop

Claude Desktop was the first mainstream MCP client and has the largest ecosystem. macOS

Open Claude Desktop
Click your profile menu → Settings → Developer
Click Edit Config
Paste the configuration into ~/Library/Application Support/Claude/claude_desktop_config.json
Fully quit and restart Claude Desktop

Windows

Open Claude Desktop
Click your profile menu → Settings → Developer
Click Edit Config
Paste the JSON below into the file that opens
Fully quit and restart Claude Desktop

Config structure:

{
  "mcpServers": {
    "convertly": {
      "command": "npx",
      "args": ["-y", "@convertly-sh/mcp"],
      "env": {
        "CONVERTLY_API_KEY": "<paste-your-key-here>",
        "CONVERTLY_MCP_ROOTS": "/Users/you/Downloads:/Users/you/Pictures"
      }
    }
  }
}

Paste your dashboard API key into CONVERTLY_API_KEY locally. Do not commit MCP config files that contain real keys. On Windows, use ; to separate roots and forward slashes inside each path (recommended — avoids JSON escaping):

"CONVERTLY_MCP_ROOTS": "C:/Users/you/Downloads;C:/Users/you/Pictures"

If you use backslashes, each one must be escaped as \\ in JSON:

"CONVERTLY_MCP_ROOTS": "C:\\Users\\you\\Downloads;C:\\Users\\you\\Pictures"

Unescaped backslashes (C:\Users\...) produce invalid JSON and the MCP server may not start.

Paths and approved folders

Convertly MCP only reads and writes paths that fall under folders listed in CONVERTLY_MCP_ROOTS. Everything else — scan_folder, convert_media, forma_ai_transform with filePath, outputPath, and so on — must stay inside those roots.

Root list (`CONVERTLY_MCP_ROOTS`)

OS	Separator between roots	Example
Windows	`;` (semicolon)	`C:/Users/you/Downloads;C:/Users/you/Projects`
macOS / Linux	`:` (colon)	`/Users/you/Downloads:/Users/you/Pictures`

~ at the start of a path expands to your home directory (~/Downloads → /Users/you/Downloads or C:\Users\you\Downloads).
If CONVERTLY_MCP_ROOTS is omitted, only the MCP server’s current working directory is approved (usually wherever your client launched the process).

Windows paths in JSON config

JSON strings treat \ as an escape character. Prefer forward slashes — Node.js accepts them on Windows:

{
  "env": {
    "CONVERTLY_MCP_ROOTS": "C:/Users/you/Downloads;D:/Projects/site-assets"
  }
}

Backslashes are fine when doubled:

"CONVERTLY_MCP_ROOTS": "C:\\Users\\you\\Downloads;D:\\Projects\\site-assets"

Avoid single backslashes:

"CONVERTLY_MCP_ROOTS": "C:\Users\you\Downloads"

That is invalid JSON (\U, \D, etc. are not valid escapes) and clients may fail to parse the config. Paths with spaces do not need extra escaping — keep the whole value in quotes:

"CONVERTLY_MCP_ROOTS": "C:/Users/you/My Projects;C:/Users/you/Downloads"

On Windows, the drive letter (C:) is part of the path, not the root separator. Only ; splits multiple roots.

macOS and Linux paths

Use normal absolute paths. Separate multiple roots with ::

"CONVERTLY_MCP_ROOTS": "/Users/you/Downloads:/Users/you/Pictures"

Spaces are fine inside quoted JSON strings:

"CONVERTLY_MCP_ROOTS": "/Users/you/My Projects:/Users/you/Downloads"

Avoid : inside a single path when you list multiple roots (uncommon on macOS/Linux). If you need a unusual path that contains :, approve a parent folder instead. Tilde works the same as on Windows:

"CONVERTLY_MCP_ROOTS": "~/Downloads:~/Pictures"

Paths in tool calls

When the agent passes folder, filePath, outputFolder, or outputPath to a tool:

Use an absolute path under an approved root, or a relative path resolved from the server working directory.
On Windows, forward slashes (C:/Users/you/file.png) are safest in prompts and tool args; backslashes usually work but agents sometimes emit invalid escapes.
If a tool returns outside approved roots, add the parent directory to CONVERTLY_MCP_ROOTS and restart the MCP server (or reload the client) so the new env var is picked up.

Call list_roots to see the resolved allow-list the server is actually using.

Cursor

Cursor supports the same mcpServers format as Claude Desktop and hot-reloads config changes. Global (all projects):

Open Cursor
Settings → Cursor Settings → MCP
Click Add new MCP server
Paste the same JSON config into ~/.cursor/mcp.json

Project-scoped: Create .cursor/mcp.json inside your project root:

{
  "mcpServers": {
    "convertly": {
      "command": "npx",
      "args": ["-y", "@convertly-sh/mcp"],
      "env": {
        "CONVERTLY_API_KEY": "<paste-your-key-here>",
        "CONVERTLY_MCP_ROOTS": "/Users/you/Downloads:/Users/you/Pictures"
      }
    }
  }
}

Cline (VS Code extension)

Open VS Code with Cline installed
Click the MCP Servers icon (plug) in the Cline sidebar
Click Install MCP Server
Paste the config or use the path:
- macOS/Linux: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
- Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

Lovable and other web clients

Web-based clients cannot run stdio servers. Use HTTP/SSE mode instead:

export CONVERTLY_API_KEY="<paste-your-key-here>"
CONVERTLY_MCP_HTTP_PORT=3000 npx @convertly-sh/mcp

Paste http://localhost:3000/mcp into the client’s remote MCP server field.

Environment variables

Variable	Required	Description
`CONVERTLY_API_KEY`	For API tools	Your Convertly API key. Required for conversion, compression, media tools, cloud storage, and jobs.
`CONVERTLY_MCP_ROOTS`	Recommended	Approved folders. `;` between roots on Windows, `:` on macOS/Linux. See Paths and approved folders. If omitted, only the current working directory is approved.
`CONVERTLY_BASE_URL`	No	Override the Convertly API origin. Defaults to `https://convertly.sh`.

Tools

Convertly docs

Research before you act. These tools let an agent read Convertly documentation before calling APIs or touching files.

Tool	Description
`list_convertly_docs`	Lists available Convertly documentation pages.
`search_convertly_docs`	Searches Convertly docs by topic, API name, or workflow.
`get_convertly_doc`	Fetches a docs page by slug or URL and returns readable text.

Local filesystem

These tools only work in Local (stdio) mode. They require paths inside CONVERTLY_MCP_ROOTS.

Tool	Description
`list_roots`	Shows the approved folders the server can access.
`scan_folder`	Lists files with size, modified date, and media category.
`plan_organize_folder`	Creates a dry-run organization plan by file type (Images, Videos, Audio, Archives, Documents, Other).
`move_files`	Moves approved files to approved destinations. Requires `confirm: true`.
`rename_files`	Renames approved files. Requires `confirm: true`.
`copy_files`	Copies approved files to approved destinations. Requires `confirm: true`.
`create_folder`	Creates folders inside approved roots.
`read_file`	Reads text contents of approved files (UTF-8).
`create_archive`	Creates ZIP archives from approved files or folders.
`delete_files`	Deletes approved files. Requires `confirm: true`.

Media conversion

Tool	Description
`convert_media`	Converts images, video, audio, documents, and archives between formats.
`compress_media`	Compresses image, video, or audio files.

CDN URL builder

Tool	Description
`build_cdn_url`	Builds Convertly CDN URLs for image transforms, video transcode/clip, poster frames, GIFs, and origin-backed assets. Use `trim: true` to crop transparent borders from logos.

Forma AI (all plans)

Generative and analysis tools that bill your Forma AI unit quota (included on Free, Starter, Pro, and Business). Use these when the agent or model cannot generate images natively.

Tool	Description
`forma_ai_transform`	Generate from text (`image.generate`), edit, upscale, replace background, style transfer, outpaint, object removal. Saves to cloud storage; optional local `outputPath`.
`forma_ai_analyze`	Describe, alt-text, tags, or moderate an image (JSON).

Requires CONVERTLY_API_KEY. Free and Starter hard-cap at the included Forma AI quota; Pro+ supports overage when enabled. See Forma AI and Limits.

AI media tools

Tool	Description
`remove_background`	Background removal for images; use the configured ML backend for complex subject segmentation.
`transform_image`	Resize, crop, rotate, flip, and format-shift images.
`generate_thumbnail`	Creates thumbnails from images or videos.
`watermark_media`	Adds text or logo watermarks to images and videos.
`create_storyboard`	Generates storyboard grid images from videos.
`trim_media`	Trims video and audio to a start time and duration.
`video_to_gif`	Converts videos to animated GIFs.
`pdf_preview`	Converts PDF pages to image previews.
`poster_frame`	Extracts poster frames from videos.
`extract_audio`	Extracts audio tracks from videos.
`strip_metadata`	Removes metadata from media files.
`images_to_pdf`	Combines images into a single PDF.
`inspect_media`	Reads metadata and properties for media files.
`adjust_media`	Applies brightness, contrast, saturation, hue, grayscale, and other adjustments.

Cloud storage

Tool	Description
`list_cloud_files`	Lists files stored in Convertly cloud storage.
`download_cloud_file`	Gets a temporary signed download URL for a cloud file.
`save_cloud_file`	Downloads a cloud file directly to an approved local folder.
`delete_cloud_file`	Deletes a file from cloud storage.
`rename_cloud_file`	Renames a file in cloud storage.
`list_folders`	Lists folders in cloud storage.
`create_cloud_folder`	Creates a folder in cloud storage.
`rename_folder`	Renames a folder in cloud storage.

Async jobs

Tool	Description
`list_jobs`	Lists recent async conversion and media-tool jobs.
`get_job`	Gets status and results for a specific job.

Utilities

Tool	Description
`transfer_url`	Downloads a public remote URL to an approved local folder (local mode only).

Example prompts

These are prompts you can paste directly into an MCP-enabled client. Research then compress:

Search the Convertly docs for compression options, then compress the images in my Downloads folder into an optimized folder. Show me the plan first.

Organize and convert:

Scan my Downloads folder, group loose files by type, archive media older than 90 days, and convert JPG/PNG images to WebP. Do not delete anything unless I confirm.

Batch rename with context:

Scan my vacation photos folder, then rename all files to vacation-001.jpg, vacation-002.jpg, etc. in chronological order. Show me the rename plan first, then execute.

Cloud + local workflow:

List my Convertly cloud files, find the largest video, download it to my Downloads folder, trim the first 30 seconds, and compress it.

Website images via Forma AI:

Generate three 16:9 hero images for a SaaS landing page — minimal, high-converting, no text in frame. Save them to my Projects/site-assets folder and list the cloud file ids.

Edit and upscale:

Upscale my hero.png with Forma AI, then save the result locally to Downloads/hero-4k.png.

Docs-aware conversion:

Read the Convertly docs about vectorization options, then convert my logo.png to SVG with color preserved.

Safety model

The AI model does not receive raw filesystem access.

Path sandboxing: All paths are resolved against CONVERTLY_MCP_ROOTS. Requests outside approved folders are rejected.
Dry-run by default: plan_organize_folder and scan_folder never modify files.
Explicit confirmation: move_files, rename_files, copy_files, delete_files, delete_cloud_file, rename_cloud_file, and rename_folder require confirm: true before executing.
Non-destructive first: Agents can show a plan, get your approval, and then execute.

Troubleshooting

Filesystem tools return “not in approved roots”

Add the parent folder to CONVERTLY_MCP_ROOTS (not just the file).
Use the correct separator: ; on Windows, : on macOS/Linux.
On Windows, use forward slashes or escaped backslashes in JSON — see Paths and approved folders.
Restart the MCP client after editing config so env vars reload.
Call list_roots to confirm what the server resolved.

Invalid MCP config / server won’t start (Windows)

Check JSON escaping. C:\Users\... with single backslashes is invalid JSON. Use C:/Users/... or C:\\Users\\....

HTTP mode: “Filesystem tools are unavailable”

This is expected. HTTP/SSE mode cannot access your local computer. Use stdio (local) mode if you need filesystem tools.

​How it works

​Local mode (stdio) — recommended

​Remote mode (HTTP/SSE)

​Client setup

​Claude Desktop

​Paths and approved folders

​Root list (CONVERTLY_MCP_ROOTS)

​Windows paths in JSON config

​macOS and Linux paths

​Paths in tool calls

​Cursor

​Cline (VS Code extension)

​Lovable and other web clients

​Environment variables

​Tools

​Convertly docs

​Local filesystem

​Media conversion

​CDN URL builder

​Forma AI (all plans)

​AI media tools

​Cloud storage

​Async jobs

​Utilities

​Example prompts

​Safety model

​Troubleshooting

​Filesystem tools return “not in approved roots”

​Invalid MCP config / server won’t start (Windows)

​HTTP mode: “Filesystem tools are unavailable”