Two changes are announced together today, and the second is only possible because of the first.
The snapWONDERS API now accepts a direct upload — one POST /api/upload with the file as the request body — alongside the existing TUS resumable protocol. And there is now an official MCP server that lets an AI assistant work on files sitting on your own machine.
Why upload needed a second option
Until now, every upload went over TUS, the resumable-upload protocol: create the upload, encode a metadata header, send the file as a sequence of PATCH requests, handle a resume if one fails. That is genuinely the right design for the platform's core case — people uploading large media over patchy connections, including Tor and I2P, where a dropped connection halfway through a 400 MB video should not mean starting again.
It is also about eighty lines of client code that has to be exactly right before you see a single result. For a developer that is an afternoon. For an AI agent assembling a request on the fly, it is a wall — and the agent has no way to tell the difference between "I implemented the chunk sequence wrong" and "the service rejected my file".
So the API now takes the simple path too. Create a session as you always did, then send the file in one request:
curl -X POST https://snapwonders.com/api/upload \
-H "X-Api-Key: sw_your_key" \
-H "X-Upload-Uid: uid-from-your-session" \
-H "Content-Type: image/jpeg" \
--data-binary @photo.jpg
To be clear about what this does and doesn't replace: session-create and job-start still bracket the upload, exactly as before. What has gone is the upload protocol in the middle — the metadata header, the chunk sequence, the resume handling. That is now one request.
The ceiling is 95 MB per file. Go over it and you get a 413 naming the actual limit and pointing you at the resumable endpoint, rather than a truncated request or a timeout. The exact number comes back as max_upload_bytes when you create a session, so read it from there rather than hard-coding 95 — it is the figure the server is actually enforcing.
Nothing about TUS has changed. It remains the path for anything larger.
The rule of thumb: under 95 MB, direct upload; above it, TUS. You should not have to think about it, so all four SDKs — Python, JavaScript/TypeScript, PHP and Go — now make that choice for you, reading the cap from the session rather than assuming it. You write the same line either way, and it stays correct if the ceiling ever moves.
The MCP server
Model Context Protocol is how AI assistants talk to outside tools. There are now two ways to connect an assistant to snapWONDERS, and they are for different jobs.
Remote or local — which one you want
| Remote (existing) | Local (new) | |
|---|---|---|
| What it is | A hosted endpoint at snapwonders.com/mcp |
A package that runs on your own computer |
| Install | Nothing — one config line | uvx snapwonders-mcp |
| Can it read your files? | No. You upload them first, then point it at the session | Yes. Name a path and it reads it |
| Tools | 19, mapping closely to the raw API | 4, each doing a whole task end to end |
| Best for | Agents working on files already in a session, or building a pipeline | Working on files sitting on your own machine |
| Networks | Clearnet only | Clearnet only |
Both call the same API and produce the same results. Neither replaces the other.
The remote server
Unchanged, and still the right choice when the assistant is orchestrating rather than handling files — it exposes the API closely, one tool per step, so an agent can drive the whole session/job/poll flow itself. Adding it to Claude Code is one line:
claude mcp add --transport http snapwonders https://snapwonders.com/mcp --header "X-Api-Key: sw_your_key"
Its limitation is simple and unavoidable: a server running on our infrastructure cannot see a file on yours. You have to upload it first — which is exactly the step you wanted the assistant to take care of.
The local server
This is the new one. It runs on your machine, so it can read the files you are actually talking about:
"Analyse ~/Downloads/suspicious.jpg and tell me if anything is hidden in it"
"Hide contract.pdf inside holiday.jpg with the password I gave you"
"Convert these three videos to WebM"
It exposes four tools — analyse_file, hide_file, reveal_file and convert_file — each of which does a whole task end to end: reads the file from disk, uploads it, runs the job, and waits for it. analyse_file hands its findings straight back to the assistant; the other three save their output files to disk, beside the original or in a directory you name. The assistant sees one call and one result, not a six-step protocol it can lose its place in.
That difference is deliberate. Four whole-task tools give an assistant fewer chances to lose its place than nineteen fine-grained ones — but they also give you less control, which is why the remote server keeps its full set.
Installing the local server
The server needs uv and a free snapWONDERS API key. In Claude Desktop, add this to your MCP configuration:
{
"mcpServers": {
"snapwonders": {
"command": "uvx",
"args": ["snapwonders-mcp"],
"env": { "SNAPWONDERS_API_KEY": "sw_your_key" }
}
}
}
uvx fetches and runs the package on demand, so there is nothing to install by hand. The API key is read from the environment only — it is never a tool argument, so it cannot end up in a conversation transcript or be talked out of the assistant by the content of a file it was asked to inspect.
The package is MIT-licensed and on GitHub at snapWONDERS/snapWONDERS-MCP.
What the local server does not do
Files still leave your machine — the analysis and steganography run on snapWONDERS servers, not locally. "Local MCP server" means the server process is local so it can read your disk; it does not mean the processing is. Successfully processed files are deleted on the same schedule as any other upload.
It has no tool to list or search your filesystem, so it cannot go looking for interesting files on its own. But it can read anything you can read, and the path comes from the assistant rather than from you directly — so an assistant acting on instructions it picked up from a web page or a document could try to send a file you never mentioned. Your MCP client's tool-approval prompt is the real gate here: read the path in the tool call before you approve it. We would rather say that plainly than let "runs locally" imply a sandbox that isn't there.
Everything else
Both changes are live now and free-tier usable. The developers hub has the full setup, the Swagger UI documents direct upload under Media Upload - Direct, and the OpenAPI spec covers both upload paths.
If you are already using the Python SDK, upgrading picks up direct upload with no code change on your side.
