# 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](./tools/generation.md),
the [model catalog](./models.md), and the [workflows](./workflows.md) will all click into place.

If you just want to connect and go, start with the [quickstart](./quickstart.md).

---

## 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/`](./tools/generation.md): [generation](./tools/generation.md),
[assets](./tools/assets.md), [templates](./tools/templates.md), and [account](./tools/account.md).

**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`](./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`](./tools/generation.md) for the MCP-tool side and
[`models.md`](./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`](./tools/generation.md) for parameters and the
[workflows](./workflows.md) 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](#response-format)
  for the inline caps).

See [`tools/assets.md`](./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`](./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:

  ```json
  {
    "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](https://app.zencreator.pro/billing).
- Review spending history with `zencreator_list_credit_transactions` (paginated).

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

---

## 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](./models.md)
  (for example `SDXL_NSFW`, `FLUX_KLEIN_NSFW`, `wan@2.7-nsfw`), 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`](./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](#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:

  ```json
  {
    "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

- [Quickstart](./quickstart.md) — connect and run your first generation.
- [Workflows](./workflows.md) — end-to-end recipes (text→image, edit, face-swap, video, lip-sync).
- [Generation tools & models](./models.md) — the `tool_name` values and their models.
- [Tool reference](./tools/generation.md) — every `zencreator_*` MCP tool.
- [Troubleshooting](./troubleshooting.md) — auth, credits, and common errors.
- Connect guides: [Claude Code](./connect/claude-code.md) ·
  [Claude.ai](./connect/claude-ai.md) · [Cursor](./connect/cursor.md) ·
  [ChatGPT](./connect/chatgpt.md).