How the Mochify MCP Server Works: Hosted vs Local, with Worked Examples

30-Second Cheat Sheet

If your goal is the lowest possible token cost, use either local mode or hosted-MCP URL input. The hosted MCP now returns compressed results as a short-lived download URL rather than inline binary - which fixes the old return-side problem but means the compressed result is briefly held in Mochify-controlled storage.

The Two Surfaces of the Mochify MCP Server

Mochify exposes its compression engine to AI agents through two separate surfaces. Both ultimately call the same hosted API at api.mochify.app/v1/squish, where the encoding work happens in RAM and the original is discarded immediately. They differ in where the agent's request originates, whether image bytes ever pass through the agent's context window, and whether the compressed result is briefly held server-side for pickup.

The hosted MCP server lives at https://mcp.mochify.app. Any MCP-compatible client - Claude Desktop, Cursor, any agent runtime that supports remote connectors - can register it, authenticate via OAuth, and call its tools. The agent sends a request, Mochify's hosted MCP forwards it to the API, and the processed image comes back as a short-lived download URL on files.mochify.app.

The local MCP server is a single Rust binary (mochify) that ships via Homebrew, raw download, or cargo install. It runs as a direct CLI in your shell, and the same binary runs as a local MCP server when launched with mochify serve and registered in your Claude Desktop config. In both local modes, the agent sees only file paths and metadata - image bytes flow from your disk to the API via the local binary and never enter the agent's context window.

You don't pick one over the other for life. You pick the right one for the job at hand. The rest of this guide gets specific about which is which. For a one-page tour of what either surface can do, with the prompt to type for each, see the Mochify MCP server page.

First-party MCP support like this is still rare among image compressors - TinyPNG, for instance, has no official MCP server or CLI as of July 2026. See how Mochify's agent surfaces compare to TinyPNG's for the full picture.

How the Hosted MCP Server Works

The hosted server is a connector that any MCP-compatible AI assistant can register and call. Once OAuth is complete, the agent has five tools available: squish for image processing, create_upload for getting an image attached to the chat to Mochify, pdf and pdf_create for documents, and check_usage for quota checks. The squish tool can also hide things the assistant points at: our guide to blurring faces or a license plate from your assistant shows the redaction parameters on two real photos.

Setup, in one paragraph

In Claude Desktop, go to Settings → Connectors, add https://mcp.mochify.app, then complete an OAuth flow that authorises Mochify to process images on your behalf. Cursor and other clients follow the same shape. The full step-by-step is in our MCP setup guide. Authentication is OAuth-based, the connector talks to our servers over HTTPS, and the agent doesn't need to manage an API key directly.

The squish tool

The squish tool accepts a public HTTPS URL to fetch the image from, an uploadId from create_upload, or - for a small file whose bytes the agent can actually read - base64 bytes plus a media type. It returns a short-lived download URL for the processed image - a five-minute TTL on files.mochify.app, with an explicit "expires in ~5 minutes" note in the response so the agent and any downstream tool know exactly when the link goes dead.

JPEG is the default output (encoded with Google's jpegli encoder, which delivers roughly 35% better compression than libjpeg-turbo at matched quality). AVIF, JPEG XL, WebP, and PNG are also supported. Options include resize, smart-crop to a subject, EXIF stripping, brightness, clarity, smartCompress, HDR gain-map preservation, and AI background removal. The assistant can also crop to (region) or hide (redactBoxes) an area it picks by looking at the image - "hide the number plate", "crop to the logo" - and Mochify receives only the coordinates. redactFaces hides faces with Mochify's own detector.

Retention, honestly

The original image you send to Mochify is streamed into the encoder in RAM, processed, and discarded. There are no disk writes of the source, and no logs containing image data.

What URL passback adds is a brief pickup window for the compressed result. After encoding, Mochify holds the processed bytes in a pickup store keyed by an unguessable hash, with a five-minute TTL. After five minutes the result is evicted regardless of whether anything fetched it.

There is one more, narrower exception, added in October 2026: upload links. An assistant sees an image attached to a chat as pixels, not as a file, so it often has no way to send Mochify the bytes. create_upload gives a one-time link instead: you drop the original there (or an assistant with file access uploads it directly). That original is kept in private storage that is never publicly served, and deleted the moment processing starts - or after 15 minutes if it is never used. A link works once, and only for the account that created it. Images sent by URL never touch it.

Where the agent's tokens go

Now that the hosted MCP returns a download URL instead of an inline image, the token-cost story has shifted. URL input is genuinely cheap on both sides: a URL in, a URL out. An image attached to the chat no longer has to be base64-encoded into the tool call either: it travels through an upload link, so the agent handles a short ID rather than the image on the way in, and a URL on the way back.

When you use the hosted MCP through Claude, what passes through the agent provider's systems is now just the download URL string, unless the agent itself fetches the file and brings the bytes into the conversation. The image bytes only enter the chat provider's infrastructure if the agent decides they need to.

How the Local Install Works

The local install is a single Rust binary that runs as either a direct CLI or as a local MCP server that Claude Desktop spawns as a subprocess. In either mode, the agent sees only file paths and compression metadata - never image bytes, and nothing held server-side after the compressed result is written to your disk.

Installation and auth

macOS (Homebrew):

brew tap getmochify/mochify
brew install mochify

One auth step covers both CLI and MCP modes:

mochify auth login

This opens your browser, you sign in with your Mochify account, and credentials are written to ~/.config/mochify/credentials.toml. No environment variables to manage, no API key to copy and paste.

Direct CLI mode

The CLI takes one or more file paths and a set of options. The -p flag is the headline feature - describe the goal in plain English:

mochify photo.jpg -p "optimize for eBay"
mochify *.heic -p "convert to WebP, 1200px wide, strip EXIF" -o ./out

It also accepts file paths on stdin, which is what makes it slot cleanly into any Unix pipeline:

find . -name "*.jpg" | mochify -t webp -o ./out
ls *.heic | mochify -t jpg

Local MCP server mode

Same binary, different invocation. Add this to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mochify": {
      "command": "mochify",
      "args": ["serve"]
    }
  }
}

Restart Claude Desktop. The squish tool now appears in the connections panel and uses the credentials from your earlier mochify auth login. No OAuth round-trip, no remote connector to refresh, no token expiry to worry about.

When to Use Which

Pick by what's true about your task, not by which tool you've heard of.

Worked Example 1: Hosted MCP with a Public URL

URL-input mode is the cheapest hosted MCP workflow: no image bytes touch the agent's context window in either direction - a URL string in, a URL string out.

A blogger is in Claude Desktop with the Mochify connector registered. They say: "Convert this hero image to AVIF and resize to 1200px wide for my blog: https://example.com/photo.jpg"

For format context: web.dev's AVIF compression study places AVIF at 40–50% smaller files than JPEG at matched visual quality. Browser support sits at over 95% globally per caniuse.com/avif, so the output is safe to serve as the primary format on most modern sites.

Worked Example 2: Hosted MCP with an Uploaded Image

This was historically the workflow most people tried first, and it disappointed in three independent ways. As of October 2026 all three are fixed. We're going to be just as direct about what's solid as we were about what wasn't - including a correction to how we used to describe the first one.

Where this leaves us: the drag-into-chat workflow now works for full-resolution photos, not just small screenshots. The cost is one honest trade. In a chat client without file access, you open the link and drop the photo there - one extra step - and the original then sits in private storage until it is processed (deleted as processing starts, or after 15 minutes). If you'd rather nothing were stored at all, Worked Example 1 (URL input) and Worked Example 3 (local MCP server) store no originals.

A worked run: drag a car photo into Claude with "Hide the number plate and convert it to AVIF." Claude calls create_upload, then either uploads the attachment itself (when it has file access) or hands you the link to drop the photo on. It finds the plate by looking at the image and calls squish({ uploadId: "9de3...e190", redactBoxes: [[0.503, 0.642, 0.183, 0.063]], type: "avif" }). Mochify deletes the uploaded original as it reads it, hides the plate, and returns:

Image processed successfully (image/avif, 32.6 KB).
Download URL (expires in ~5 minutes): https://files.mochify.app/629b...d46.avif
Redacted 1 area(s).

Mochify never sees a description of the image and no Mochify model looks at it: the assistant you already use did the looking, and Mochify received four numbers.

Claude either fetches that URL and shows you the result, or hands you the link directly. The compressed file lives on files.mochify.app for the rest of the five-minute window and then disappears.

Worked Example 3: Local MCP Server in Claude Desktop

The local MCP server is the right surface for chat-driven file work: image bytes flow directly from disk to the API and back to disk, no agent context touched, no pickup store involved.

"Convert all the JPEGs in /Users/sam/Desktop/product-shoot/ to AVIF at 1200px wide and save them to /Users/sam/Desktop/product-shoot/web/"

Worked Example 4: Direct CLI in Claude Code or a Build Pipeline

The direct CLI is the cheapest workflow per image by orders of magnitude - zero image bytes in any agent context, works with no agent at all, and slots cleanly into any Unix pipeline or CI step.

A developer working on a Next.js site opens Claude Code and asks: "Optimize everything in public/images to AVIF and WebP, then add a preload tag for the hero image."

The same pattern works without an agent at all. A content engineer building an unattended publishing pipeline:

# Generate the hero, optimize to AVIF + WebP, then commit
generate-hero-image "$DRAFT_PATH" /tmp/hero.png
mochify /tmp/hero.png -p "AVIF web-ready hero, 1600 wide" -o ./public/heroes/
mochify /tmp/hero.png -t webp -w 1600 -o ./public/heroes/
git add ./public/heroes/ && git commit -m "Add hero for $DRAFT_PATH"

Or the stdin pipe pattern for batch jobs:

find ./uploads -name "*.heic" | mochify -t jpg -o ./out

No upload step, no download step, no chat round-trip, no per-image agent token cost. For the full Claude-Code-specific walkthrough, see our guide to compressing images inside Claude Code. For container-based pipelines, see our self-hosting image optimization with Docker guide.

The Honest Answer on Token Cost

The hosted MCP server used to be a workflow saver but not a token saver, because compressed results returned inline as binary. With URL passback, that's no longer true on the return side. The local install remains the cheapest workflow per image, because no image bytes ever enter the agent's context in either direction. For the underlying numbers behind these tradeoffs, see our breakdown of how many tokens does an image use?

The hosted MCP server with URL input is now genuinely cheap both ways - a URL string in, a URL string out. An image attached to the chat is now cheap too: it travels through an upload link rather than as base64 in the tool call, so the agent handles a short ID on the way in and a URL on the way back.

The local install (CLI or mochify serve) is still the cheapest workflow per image. Nothing about the image ever enters the agent's context - not on the way in, not on the way back. For batch workflows it is still the clear winner: 100 images through the hosted upload path means 100 separate upload links, while the local install takes a folder path and puts a handful of summary lines in.

The same paths-not-bytes principle carries over to documents: you can extract, split, and convert PDF pages in an agent pipeline without ever putting page bytes in the agent's context either.

The practical rule

• A few chat-driven image edits per week with no install - use the hosted MCP and don't worry about it.
• Chat-driven work where the files are already on your laptop - install the local MCP server (mochify serve).
• Anything resembling a pipeline (build step, content workflow, batch processing, repo-wide cleanup, agentic content generation) - use the direct CLI.

Benchmark: 1600px PNG source, three formats

Source is a lossless 1600px PNG - the large reductions reflect PNG→lossy format conversion as well as compression. For a JPEG-to-JPEG comparison, Google's jpegli announcement reports 35% better compression than libjpeg-turbo at matched quality, and web.dev's AVIF benchmarks place AVIF 40–50% below comparable JPEG.

FAQ

Related Guides

• How to Use Mochify via MCP: AI Agent Image Compression : The practical setup walkthrough for connecting Mochify to Claude Desktop and other MCP clients.
• How Mochify's Natural Language Feature Works : Deep dive on the Magic Flow language layer that sits in front of squish.
• AI Agent Workflow Automation for Photographers : An end-to-end pipeline example using Claude, Dispatch, and the Mochify MCP server.
• Jpegli: Why It Changes the Quality-Per-Byte Game : How the JPEG output that Mochify produces gets 35% smaller files at matched quality.
• Privacy & Image Optimization: A Comprehensive Guide : The zero-retention story that underpins every Mochify surface, including the MCP server.
• How to Compress and Optimize AI-Generated Images : Optimizing AI-generated images through the MCP server: which formats win and how to automate the optimize-after-generation step.
• LLM Image Token Costs: How Many Tokens Does an Image Use? : The per-model math behind image tokens, and why the MCP server returns file paths instead of image bytes.