SudoMock MCP Server
Generate photorealistic product mockups from Claude, Cursor, Windsurf, and VS Code.
Model Context Protocol server for the SudoMock mockup generation API. Upload PSD templates, place artwork onto smart objects, edit supported text layers, and get rendered image URLs -- all through natural language.
Quick Start
This is a local stdio server: your MCP client launches it as a child process
via npx and authenticates with your SUDOMOCK_API_KEY.
claude mcp add sudomock \
-e SUDOMOCK_API_KEY=sm_your_key_here \
-- npx -y @sudomock/mcp
Get your API key at sudomock.com/dashboard/api-keys.
{
"mcpServers": {
"sudomock": {
"command": "npx",
"args": ["-y", "@sudomock/mcp"],
"env": {
"SUDOMOCK_API_KEY": "sm_your_key_here"
}
}
}
}
Note: A hosted remote (HTTP/OAuth) transport is not available yet. This package only ships the local stdio server shown above.
Tools
Both spellings work
The product calls its two kinds of template PSD mockups and photo mockups, and the tools answer to those names too. Nothing above was renamed: every name in the table keeps working exactly as it always has, and the spelling beside it is the same tool with the same arguments. Reach for either.
render_photo_mockup is the one that is not simply a second name for a single
tool. It renders either kind of target from one tool: pass the mockup as
mockup_id and name exactly one of surface_uuid (sized by coverage or an
explicit width + height) or print_area_uuid (sized by fit or an
explicit width + height). Picking the target by picking a tool, with
mockup_uuid, is what render_2d_surface and render_2d_print_area still do.
render_2d_mockup is render_photo_mockup under a second name, with the
mockup passed as mockup_uuid.
Async jobs
render_mockup, upload_psd, create_2d_mockup, and both photo mockup render tools
accept is_async: true, and render_video is always async. These return a
job_id immediately (HTTP 202) instead of a final result. (create_2d_mockup
and the photo mockup render tools are synchronous by default and return the mockup /
render directly.) Poll it with get_job, or let wait_for_job block until the job
reaches a terminal status and hands back result_url, mockup_uuid,
credits_charged, and payg ({credits, unit_price, cost} for pay-as-you-go
jobs, otherwise null).
For a photo mockup render, pick the tool that matches the target you read from
get_2d_mockup. Every printable product in the photo, and the main wall of a
room photo, is a surface with its own surface_uuid: render_2d_surface
prints across the whole of one, and takes either a coverage percentage or an
explicit width + height. A print area
is a bounded zone somebody drew on a product, such as a chest logo:
render_2d_print_area takes its print_area_uuid, and either a fit or an
explicit width + height. A product can have both, and they are separate
targets -- a saved print area does not close off the surface it sits on.
Sizing has one answer per render: send the relative option or the exact box,
never both, and send width and height together. position, offset_x,
offset_y and rotation place the artwork on either kind of target. Anything
you leave out is left out of the request, so the renderer's own default
applies rather than a copy of it kept here.
Each entry in a photo mockup's surfaces carries a label, what was detected
there, such as pillow or wall, so you can tell surfaces apart before you
pick one. update_2d_print_areas takes an optional print_area_id on each
area: an area that sends one of the mockup's ids keeps it, and an area without
one gets a new id.
Patterns
tile repeats the artwork as a pattern across the whole target, and
tile_spacing leaves a gap between the tiles: a percentage of the tile size,
0 to 100, so the horizontal gap is that percent of the tile width and the
vertical gap that percent of the tile height. It is used only when tile is
true.
- On a PSD template both go in a
smart_objectsentry'sassetonrender_mockup.sizeis one tile,fitplaces the artwork inside each tile, andpositionsets where the grid starts. render_videotakes them as parameters for the smart object it fills, withasset_widthandasset_heightas the size of one tile.- The photo mockup render tools take them as parameters. The sizing answer
(
coverage,fit, orwidthandheight) is one tile, andpositionwithoffset_xandoffset_ysets where the grid starts.
A tile needs a size; without one the API answers 422.
Background removal
remove_background returns a transparent-PNG URL valid for 7 days. You can
pass that URL straight back as artwork_url during that window. To clean
artwork inline during a single render instead, pass
remove_background: true to render_mockup or either photo mockup render tool. Either way it
costs 25 credits per artwork, refunded automatically if processing fails.
Webhooks
Register an endpoint with create_webhook_endpoint to be notified when async
jobs finish. Deliveries are signed with TWO headers: X-SudoMock-Signature
(a hex HMAC-SHA256 over ${timestamp}.${rawBody} using the secret returned at
creation/rotation) and X-SudoMock-Timestamp (unix seconds). Verify in constant
time and reject if |now - timestamp| > 300s.
Render, upload, and video job deliveries use
{event, job_id, kind, status, result_url, error, created_at}. The typed photo
mockup creation events add version, mockup_id, name, and either
print_areas (ready) or reason (rejected). The typed photo mockup render
events carry mockup_id, result_url, a public {error_code, message} failure
when applicable, and optional export_format / duration_ms. Event types:
render.succeeded, render.failed, upload.succeeded, video.succeeded,
video.failed, photo_mockup.ready, photo_mockup.rejected,
photo_mockup.failed, photo_mockup_render.succeeded,
photo_mockup_render.failed, webhook.test.
The five photo mockup events also have a legacy spelling: 2d_mockup.ready,
2d_mockup.rejected, 2d_mockup.failed, 2d_render.succeeded,
2d_render.failed (with kind 2d_create / 2d_render in the payload).
Which spelling an endpoint receives is its event_naming pin, set at
create_webhook_endpoint and returned on every endpoint: current (the names
above) or legacy. A create without a pin takes current only when
event_types names photo mockup events by their family names alone, and
legacy otherwise, including an empty list. Endpoints registered before the pin
existed stay on legacy, so a receiver written against the old names keeps
working unchanged. Once that receiver handles the new names, move it with
update_webhook_endpoint and event_naming: "current"; sent on its own, the
re-pin re-spells the endpoint's stored subscription list to match.
Logs
Each tool call writes one JSON line to stderr, which your MCP host keeps in its
log file: the tool name, how long the call took, and whether it succeeded, for
example {"event":"mcp_tool_call","tool":"list_mockups","duration_ms":312,"ok":true}.
Arguments, API keys, file contents and API responses are never logged. Every
API request identifies this package as mcp-stdio/<version> in its
User-Agent and X-SudoMock-Client headers.
Pricing and account limits
Subscriptions from $0.002 per render. Without one, $0.05 per render, the same rate standalone mockup APIs charge on a paid plan. Funding the balance takes a $5 minimum first payment. Photo mockups and video are priced by what they cost to produce rather than at the flat render rate, which is why the Credits column above is not uniform.
A new account starts with 500 credits, granted once, and needs no card to spend them. Until a card is verified and the $5 minimum is funded, that account is in trial, and every render it makes is watermarked and capped at 1,024 px. It can keep 5 PSD templates, run one render at a time, and a template that has gone 13 days without a render is removed.
Funding the balance lifts all of it at once. The watermark and the width cap come off, stored templates go to 150, renders run 25 at a time alongside 10 concurrent uploads, and templates stop being removed for sitting idle.
Trial is not a separate plan. It is the unfunded state of the pay-as-you-go tier, so
get_account reports the same tier before and after funding; the balance is what
changes.
Because of that, an account paying as it goes has no monthly allowance, and
get_account reports credits_limit and credits_remaining as 0 while the
account is perfectly able to pay. Read prepaid_balance alongside them, or read
funding_summary, which states both in one line and never reports a funded account
as 0 / 0.
Example requests
- "List my mockup templates"
- "Render the t-shirt mockup with this design: https://example.com/logo.png"
- "Replace the editable headline text, then render the mockup"
- "Cut out the background from this product photo, then render it on the tote bag"
- "List my photo mockups, then render the first one with this artwork: https://example.com/logo.png"
- "Render this design asynchronously and wait for it to finish"
- "Queue that photo mockup render async and give me the job id to track"
- "Animate the hoodie mockup into a 5-second video clip"
- "Upload this PSD as a new template: https://example.com/mockup.psd"
- "Set up a webhook at https://example.com/hooks so I get notified when renders finish"
- "How many credits do I have left?"
Links
- Dashboard -- Manage mockups and API keys
- API Docs -- Full REST API reference
- Pricing
- Status -- Service uptime
License
MIT
