# SudoMock MCP Server

> Generate photorealistic product mockups from Claude, Cursor, Windsurf, and VS Code.

[Model Context Protocol](https://modelcontextprotocol.io/introduction) server for the [SudoMock](https://sudomock.com) 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`.

```bash
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](https://sudomock.com/dashboard/api-keys).

<details>
<summary>JSON config for other clients (Cursor, Windsurf, VS Code)</summary>

```json
{
  "mcpServers": {
    "sudomock": {
      "command": "npx",
      "args": ["-y", "@sudomock/mcp"],
      "env": {
        "SUDOMOCK_API_KEY": "sm_your_key_here"
      }
    }
  }
}
```

</details>

> **Note:** A hosted remote (HTTP/OAuth) transport is not available yet. This
> package only ships the local stdio server shown above.

## Tools

| Tool | Description | Credits |
|------|-------------|---------|
| `list_mockups` | List your uploaded mockup templates | 0 |
| `get_mockup_details` | Get smart object UUIDs, dimensions, blend modes; with `include_layers`, every layer and its UUID, including the layers inside smart objects | 0 |
| `render_mockup` | Render a mockup with artwork and/or editable text; `hidden_layers` leaves chosen layers out | 1 |
| `remove_background` | Get a transparent-PNG cutout at a public URL that stays available for 7 days | 25 |
| `list_fonts` | List the fonts available for text layers, including your uploads | 0 |
| `create_upload_url` | Get an upload URL for a local file and the file URL it will have | 0 |
| `create_2d_mockup` | Create a photo mockup and detect printable surfaces automatically | 25 |
| `render_2d_surface` | Print artwork across a whole product surface (all-over) | 5 |
| `render_2d_print_area` | Print artwork into one saved print area (a drawn zone) | 5 |
| `render_video` | Animate a mockup into a video clip (always async) | cost-based (one per account at no charge, then cost-based) |
| `upload_psd` | Upload a Photoshop PSD/PSB template (sync or async) | 0 |
| `list_2d_mockups` | List saved photo mockup templates; use `customizable_only` for shopper-ready items | 0 |
| `get_2d_mockup` | Get one photo mockup's saved print areas and its product surfaces | 0 |
| `update_2d_print_areas` | Replace a photo mockup's print-area geometry | 0 |
| `delete_2d_mockup` | Delete a photo mockup template | 0 |
| `get_job` | Check the status of an async job by job_id | 0 |
| `wait_for_job` | Poll an async job until it succeeds or fails | 0 |
| `list_jobs` | List async render, video, upload, and photo mockup jobs | 0 |
| `get_account` | Check plan, credits, prepaid balance, and usage | 0 |
| `update_mockup` | Rename a mockup template | 0 |
| `delete_mockup` | Delete a mockup template | 0 |
| `create_webhook_endpoint` | Register a webhook for async job completion, pinned to an event naming | 0 |
| `list_webhook_endpoints` | List your webhook endpoints | 0 |
| `update_webhook_endpoint` | Edit or enable/disable a webhook endpoint | 0 |
| `delete_webhook_endpoint` | Delete a webhook endpoint | 0 |
| `rotate_webhook_secret` | Rotate a webhook signing secret | 0 |
| `test_webhook_endpoint` | Send a signed `webhook.test` event | 0 |
| `list_webhook_deliveries` | List delivery attempts for an endpoint | 0 |
| `replay_webhook_delivery` | Replay a single failed delivery | 0 |
| `replay_failed_webhook_deliveries` | Replay every failed delivery for an endpoint | 0 |

### 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.

| Name in the table | Also answers to |
|------|------|
| `list_mockups` | `list_psd_mockups` |
| `get_mockup_details` | `get_psd_mockup` |
| `update_mockup` | `update_psd_mockup` |
| `delete_mockup` | `delete_psd_mockup` |
| `render_mockup` | `render_psd_mockup` |
| `create_2d_mockup` | `create_photo_mockup` |
| `list_2d_mockups` | `list_photo_mockups` |
| `get_2d_mockup` | `get_photo_mockup` |
| `update_2d_print_areas` | `update_photo_mockup_print_areas` |
| `delete_2d_mockup` | `delete_photo_mockup` |
| `render_2d_surface`, `render_2d_print_area` | `render_photo_mockup` |
| `get_2d_mockup` | `get_2d_mockup_details` |
| `test_webhook_endpoint` | `send_webhook_test_event` |
| `render_photo_mockup` | `render_2d_mockup` |

`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 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.

### 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](https://sudomock.com/dashboard) -- Manage mockups and API keys
- [API Docs](https://sudomock.com/docs) -- Full REST API reference
- [Pricing](https://sudomock.com/pricing)
- [Status](https://sudomock.statuspage.io) -- Service uptime

## License

MIT