Sudomock MCP

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.

JSON config for other clients (Cursor, Windsurf, VS Code)

{

"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 and fix_seams are 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_objects entry's asset on render_mockup. size is one tile, fit places the artwork inside each tile, and position sets where the grid starts.
• render_video takes them as parameters for the smart object it fills, with asset_width and asset_height as the size of one tile.
• The photo mockup render tools take them as parameters. The sizing answer (coverage, fit, or width and height) is one tile, and position with offset_x and offset_y sets where the grid starts.

A tile needs a size; without one the API answers 422.

Check the tile with check_seams before you render it. It answers at once, at no charge, with status: seamless, faint_seam or visible_seam. seams lists each side that does not join cleanly, left_right (where the right edge meets the left) or top_bottom (where the bottom edge meets the top), with the pixel ranges along it. fixable and unfixable_reason (transparent_edges or too_large) say whether the tile can be repaired, and previous_fix holds your latest fix of the same image, if there is one. Pass crop_aspect, the width divided by the height of one tile in your render, to check the image cropped to that shape the way fit: "crop" crops it.

fix_seams takes the same input and repairs the tile so it repeats without a visible seam. It is always async: read the job with get_job or wait_for_job. The finished job carries result_url, alternative_url (a second repaired version when one is available, otherwise null), result_status (the seam check of the result) and changes (edges or whole_tile); while it runs, stage reads queued, fixing or finishing. A fix that fails with error_code TILE_NOT_FIXABLE carries error_details.reason: not_a_pattern_tile or no_clean_result. Seam fix: 60 credits, refunded automatically if the fix fails; seam check: free.

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 5 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, seam_fix.succeeded, seam_fix.failed, webhook.test. Seam fix deliveries carry result_url and alternative_url.

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