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.

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 two tools available: squish for image processing, and check_usage for quota checks.

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 either a public HTTPS URL to fetch the image from, or raw base64 image 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.

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.

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. Upload input is still expensive on the way in because the image is base64-encoded into the tool-call payload, but the return is a short text URL rather than a binary blob — a one-way cost rather than two-way.

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 "optimise 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. One of those three is now fixed. We're going to be just as direct about what's solid as we were about what wasn't.

Where this leaves us: the drag-into-chat workflow is now genuinely usable for small images where the quality hit from chat-client upload pre-processing doesn't matter — a screenshot you're prepping for a Notion page, a thumbnail you want as AVIF, a quick conversion of a small graphic. It is not the right workflow for a hero image, a product photo, or anything where you'd want pixel-accurate output. For those, use Worked Example 1 (URL input) or Worked Example 3 (local MCP server).

A worked run: drag a small PNG screenshot into Claude with "Make this web-ready." Claude calls squish({ data: "<base64...>", mediaType: "image/png", optimizeForWeb: true }). Magic Flow infers AVIF output with sensible web-ready defaults and EXIF stripping. Mochify processes the vision-processed copy of your screenshot and returns:

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

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: "Optimise 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, optimise 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 container-based pipelines, see our self-hosting image optimisation 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.

The hosted MCP server with URL input is now genuinely cheap both ways — a URL string in, a URL string out. Upload input is still expensive on the way in because the image is base64-encoded into the tool-call payload, but the return is a short text URL rather than a binary blob; it's a one-way cost rather than a two-way one.

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 the difference is dramatic: compressing 100 images via the hosted-MCP upload path would push 100 base64 payloads through your agent's context; compressing them via the local install puts a handful of summary lines in.

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.