ZenCreator MCP Docs
/
Connect
View as Markdown Open in ChatGPT Open in Claude

Concepts — the mental model#

This page explains how the ZenCreator MCP server is put together so you can reason about it before you start calling tools. Read it once and the tool reference, the model catalog, and the workflows will all click into place.

If you just want to connect and go, start with the quickstart.

MCP tools vs generation tools & models#

This is the single most important distinction in the whole product. There are two layers, and they use the word "tool" for different things.

Layer 1 — MCP tools. These are the callable tools your AI client sees in its tool list. There are roughly 28 of them and every one is prefixed zencreator_ (for example zencreator_create_task, zencreator_list_tools, zencreator_get_me). This is the API surface of the MCP server. It is documented across the reference pages under tools/: generation, assets, templates, and account.

Layer 2 — generation tools & models. These are values you pass in, not tools your client calls. When you submit a generation you call the MCP tool zencreator_create_task and pass a tool_name argument — and tool_name is a generation tool such as by_prompt, image_editor, videogen, faceswap, upscaler, or lipsync. Each generation tool exposes its own set of models (for example by_prompt offers models like GENERAL_NSFW, SDXL_NSFW, NANO_BANANA, QWEN_IMAGE, SEEDREAM_5, WAN_2_7_IMAGE, FLUX_KLEIN_NSFW). Generation tools and their models are documented in models.md.

Put plainly:

zencreator_create_task is an MCP tool. by_prompt is a generation tool you pass to it as tool_name. SDXL_NSFW is a model you pass to by_prompt.

A typical flow touches both layers:

  1. Discover what is available with the MCP tool zencreator_list_tools (lists generation tools, prices, and whether any are blocked).
  2. Inspect one generation tool's exact inputs with zencreator_get_tool_schema — call this before you submit, so you know the schema, prompt guidance, and which models it supports.
  3. Submit with zencreator_create_task, passing tool_name (the generation tool) plus its inputs.

See tools/generation.md for the MCP-tool side and models.md for the generation-tool / model side.

Tasks and calls#

Generation is organized as tasks and calls.

  • A task wraps 1 to 50 generation calls. Each call is one generation request (one tool_name + its inputs). Batching many calls into a single task is how you fan out variations or render a set of images in one submission.
  • Submitting is asynchronous. zencreator_create_task returns a task id immediately; the generation runs in the background. The task id is your handle for everything that follows.
  • Poll progress with zencreator_get_task. It returns the task and its calls with their statuses. status='failed' is terminal — read calls[].error for the reason and don't retry without confirming with the user. Use zencreator_get_processing_tasks for a cheap "is anything still running?" check.
  • Per-call output is lazy. On a polled task, each call's output field comes back null even after it completes. To get the actual result — including the generated asset ids — call zencreator_get_call_result(call_id) for that call. This is the only way to discover the asset ids a completed generation produced.
  • For a one-shot blocking flow, use zencreator_run_and_wait: it submits and blocks until the task reaches a terminal status, then auto-fetches the outputs and asset ids for you. This is the best choice for images you want in the same turn. Do not use it for video — video is too slow to block on; submit with zencreator_create_task and poll instead.

The full pattern for fetching results:

  1. zencreator_create_task(tool_name, …) → task id.
  2. zencreator_get_task(task_id) until a call shows status='completed'.
  3. zencreator_get_call_result(call_id) for each completed call → extract asset ids.

See tools/generation.md for parameters and the workflows page for end-to-end recipes.

Assets#

Both the inputs and the outputs of generation are assets, each identified by an immutable asset_id. An asset is a stored piece of media (image, video, or audio). Asset ids never change, so you can pass an output asset id straight back in as the input to another generation (face-swap a result, upscale it, animate it, and so on).

  • Bring your own media with zencreator_upload_asset — upload an image, video, or audio from a URL or base64, and get back an asset_id you can reference in generation inputs.
  • Inspect an asset's media type with zencreator_get_asset.
  • Download the original with zencreator_get_asset_download_url (single) or zencreator_get_asset_download_urls (batch) — these return short-lived presigned URLs to the full-resolution original.
  • Preview with zencreator_get_asset_preview_url (single) or zencreator_get_asset_preview_urls (batch) — these return a reduced-size web preview (a downscaled thumbnail, commonly WebP, not the original), and can additionally attach the preview image inline so it renders directly in the chat (see Response format for the inline caps).

See tools/assets.md for full parameters.

Templates (presets)#

A template (a.k.a. preset) is a pre-built set of generation inputs — a ready-made starting point you can submit as-is or tweak.

  • Browse with zencreator_list_templates (paginated).
  • Fetch one in full, including a ready-to-submit input, with zencreator_get_template.
  • Submit in one shot with zencreator_use_template: it fetches the template, merges any overrides you supply, and submits — no manual schema wrangling.

Optional semantic search — on deployments that have the search subsystem enabled, three extra MCP tools are available: zencreator_search_templates (semantic + keyword search), zencreator_get_template_card (a synthesized summary card), and zencreator_search_index_status (a diagnostic). These may not be available on every deployment — if they don't appear in your client's tool list, the server you're connected to doesn't have search enabled; fall back to zencreator_list_templates.

See tools/templates.md.

Credits & pricing#

Generation spends credits. Cost varies by generation tool, model, resolution, and duration, and the numbers are backend-driven — so never assume a price.

  • Estimate before you commit. Call zencreator_estimate_price to get the exact credit cost of a specific candidate input, or zencreator_compare_prices to shop the cost across all models of a generation tool (cheapest first, sweeping resolutions where relevant). State the cost to the user before submitting.

  • Running out is signaled, not silent. If a generation runs out of credits the tool returns HTTP 402 with a structured signal:

    {
  "error_code": "insufficient_credits",
  "out_of_credits": true,
  "purchase_url": "https://app.zencreator.pro/billing",
  "message": "You're out of ZenCreator credits. Top up at https://app.zencreator.pro/billing to keep generating."
}

    The same out_of_credits flag and purchase_url also appear in the zencreator_get_me payload, so "out of credits" reads identically whether you check ahead of time or hit it mid-generation.

  • Top up at https://app.zencreator.pro/billing.

  • Review spending history with zencreator_list_credit_transactions (paginated).

For the pricing tools' parameters see tools/generation.md, and for fixing a stuck or out-of-credits state see troubleshooting.

NSFW & trusted accounts#

ZenCreator supports uncensored / NSFW generation. Two account gates govern access, both visible on your profile via zencreator_get_me:

  • nsfw_allowed — whether adult content is enabled on the account. If this is false, the fix is to enable adult content in your ZenCreator account settings, then retry.
  • is_trusted — whether the account has Trusted Status, which unlocks ZenCreator's extended capabilities: uncensored NSFW generation, 18+ templates and LoRAs, Face Swap tools, and more flexible generation options. An account becomes trusted automatically after its first successful payment (purchasing any credit pack in the Billing section); the status is then permanent. Trusted-only models are marked (trusted) in the model catalog (for example SDXL_NSFW, FLUX_KLEIN_NSFW, [email protected]), and a few whole tools are trusted-only — male_undresser, flux_klein_lora, and text_to_video. Without trusted status you can't use them.

If your orchestrating client refuses to author explicit prompts, the optional zencreator_craft_prompt tool exists precisely for this: it delegates NSFW / model-specific prompt writing to an uncensored sidecar LLM and spends no ZenCreator credits. It is only present when the prompt-agent sidecar is configured on the deployment. See models.md for which models are trusted-only and for per-model prompt guidance.

Response format#

Every MCP tool follows the same response contract.

  • response_format argument. Each tool takes response_format, which is "markdown" (the default) or "json". markdown gives a human-readable summary; json returns the full structured payload as text.
  • structuredContent is always present. Regardless of response_format, the tool also returns a complete machine-readable structuredContent object, so clients with output-schema support always get the full data.
  • Truncation. Responses larger than about 25,000 characters are truncated, with a hint to paginate (use limit / offset — see Pagination) or switch to response_format: "json" and ask for fewer fields.
  • Inline previews. The asset preview tools can additionally attach the preview image inline as an MCP image content block, so it renders in the chat. Inline caps: 2 MB per image and 8 MB total per call. Anything over a cap falls back to a URL with an inline_skipped note instead of being inlined.

Pagination#

List tools (zencreator_list_tasks, zencreator_list_templates, zencreator_list_credit_transactions, …) share one pagination convention:

  • Inputs: limit (1–100, default 20) and offset (≥ 0, default 0).

  • Output envelope:

    {
  "total": 0,
  "count": 0,
  "offset": 0,
  "items": [],
  "has_more": false,
  "next_offset": 20
}

To page forward, pass the returned next_offset back in as the next request's offset. next_offset is only present when has_more is true.

How the work is split#

It helps to know which side does what.

  • Your AI client / the LLM interprets the user's intent and orchestrates: it decides which generation tool and model fit the request, drafts prompts, chains steps (generate → fetch result → upscale → animate), and decides when to confirm cost or risk with the user.
  • The MCP server structures the request, enforces the input schemas, prices the work, talks to the ZenCreator backend on the user's behalf, and returns structured results. It owns no creative judgment — it validates, executes, and reports.

In practice that means: let the agent reason about what to make, but lean on zencreator_get_tool_schema for the exact shape of the request, zencreator_estimate_price / zencreator_compare_prices for what it costs, and zencreator_get_call_result for what came back.

Next steps#