Account & Credits Tools#

API reference for the MCP tools that report on the signed-in ZenCreator account: profile, credit balance, the credit-spend ledger, and the "Show 18+ content" setting. These tools never spend credits.

There are three tools in this group:

• zencreator_get_me — profile + current credit balance + account flags.
• zencreator_set_show_nsfw_content — turn "Show 18+ content" on or off.
• zencreator_list_credit_transactions — paginated history of credit movements.

Identity is bound to your MCP session by OAuth — there is no user_id argument to pass. Both tools always report on you, the authenticated user. See Concepts for how the session is established.

Standard response contract#

Every tool in this group takes a response_format argument ("markdown" default, or "json") and always returns a full machine-readable structuredContent object in addition to the text payload. "markdown" gives a human-readable summary; "json" returns the raw payload as text. Clients with output-schema support get the complete structuredContent either way. Responses over ~25,000 characters are truncated with a hint to paginate or switch to response_format:"json".

zencreator_get_me#

Return the authenticated user's profile and current credit balance.

Use it to check available credits before submitting a generation, to confirm the account is active, and to read the stable out_of_credits flag.

Parameters

Returns — structuredContent shape:

{
  "id":             "string",
  "email":          "string | null",
  "credits":        0,
  "role":           "string",
  "is_blocked":     false,
  "nsfw_allowed":   false,
  "active":         false,
  "is_paying":      false,
  "is_trusted":     false,
  "out_of_credits": false,
  "purchase_url":   "string | null"
}

Field notes:

• id — your account UUID. Internal; do not surface it in normal replies.
• email — account email, or null.
• credits — current credit balance (integer).
• role — account role (e.g. user, admin). Internal/diagnostic.
• is_blocked — true if the account is blocked; all generations fail until lifted. Internal/diagnostic.
• nsfw_allowed — the "Show 18+ content" toggle: whether 18+ content is shown. Not a generation gate (see below).
• active — whether the account is active. Internal/diagnostic.
• is_paying — whether the account is a paying account. Internal/diagnostic.
• is_trusted — whether the account may use the trusted-only models (models marked (trusted) in Models). Internal/diagnostic.
• out_of_credits — true when the balance is exhausted. A stable flag to branch on instead of parsing prose.
• purchase_url — billing link, populated only when out_of_credits is true; otherwise null.

The default surfaced answer is just email and credits. The fields tagged internal/diagnostic are decision flags for the agent, not facts to read back to the user verbatim — don't print "Role: …" / "Status: …" / "Flags: …" unless the user explicitly asks for that exact field.

nsfw_allowed does not affect generation — whether a task runs uncensored is decided by is_trusted (and the brand). Never stop, refuse or downgrade an NSFW generation because it is false. To change it, use zencreator_set_show_nsfw_content. The "markdown" response notes it when the setting is off, and likewise surfaces automatic warnings when out_of_credits or is_blocked is true.

Out of credits. When out_of_credits is true, tell the user their balance is empty and give them the purchase_url link to top up at https://app.zencreator.pro/billing. This is the same structured signal (out_of_credits + purchase_url) that any generation tool attaches when it fails with insufficient credits (see The out-of-credits signal), so the message reads identically whether you check ahead or hit it mid-generation. Surface it as-is rather than rephrasing.

Errors

• 401 — the MCP session is no longer authorized. The user must re-authorize the server (re-run the OAuth login in their client). See Troubleshooting.

Example

"How many credits do I have?" — the agent calls zencreator_get_me and reports the credits field.

Before a generation, the agent calls zencreator_get_me and compares credits against the price from zencreator_estimate_price before confirming the cost with you.

zencreator_set_show_nsfw_content#

Turn the "Show 18+ content" setting on or off — the same toggle as in the web app. It decides whether 18+ content is shown to you.

Generation does not need it, so the agent never touches it for a generation request. When you want an 18+ template or LoRA preset that is hidden and your account has Trusted Status, the agent asks whether to turn it on and does so on a yes (without Trusted Status turning it on unlocks nothing, so the agent does not offer it); when you ask to show or hide 18+ content, it does so right away. After a change it re-fetches the lists it already has.

Arguments

• enabled (boolean, required) — true turns the setting on, false turns it off.
• response_format ("markdown" | "json", default "markdown").

Returns

{ "nsfw_allowed": true }

Example

"Turn on 18+ content." — the agent calls zencreator_set_show_nsfw_content with enabled: true.

zencreator_list_credit_transactions#

Return a paginated list of the current user's credit transactions, newest first.

Use it to audit how credits were spent, to find the cost of a specific past task, or to confirm that a top-up was credited.

Parameters

Returns — the canonical paginated envelope as structuredContent:

{
  "total":  0,
  "count":  0,
  "offset": 0,
  "items": [
    {
      "id":               "string",
      "amount":           0,
      "resulting_amount": 0,
      "source":           "string",
      "created_at":       "string",
      "meta":             null
    }
  ],
  "has_more":    false,
  "next_offset": 0
}

Envelope keys:

• total — total number of transactions for the account.
• count — number of items in this page.
• offset — the offset this page was fetched at.
• items — the transactions on this page (see below).
• has_more — true if more pages remain.
• next_offset — offset to pass back to fetch the next page; present only when has_more is true.

Per-item fields:

• id — transaction UUID.
• amount — signed credit movement: positive = credit added (top-up, refund, promo), negative = debit (a charge for a generation).
• resulting_amount — the account balance immediately after this transaction.
• source — what produced the transaction, e.g. task, call, stripe, airdrop, refund.
• created_at — ISO 8601 timestamp.
• meta — free-form object or null. For charges it usually carries the originating task_id or call_id, which lets you map a debit back to a specific generation.

Errors

• 401 — the MCP session is no longer authorized. The user must re-authorize the server. See Troubleshooting.

Example

"Show my last 5 charges" — the agent calls with limit=5 and reports the items where amount is negative.

"Did my top-up go through?" — the agent scans recent items for a positive amount with source stripe.

The out-of-credits signal#

ZenCreator surfaces "out of credits" the same way everywhere, so it reads identically whether you check ahead with zencreator_get_me or run into it mid-generation.

When a generation runs out of credits, the backend returns HTTP 402 and the tool result carries this structured payload:

{
  "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."
}

zencreator_get_me exposes the same flag proactively: when the balance is exhausted it sets out_of_credits: true and populates purchase_url with the same billing link (and null while the account is in credit). Branch on out_of_credits rather than parsing the message text, and when it is true, direct the user to top up at https://app.zencreator.pro/billing.

To avoid hitting a 402 at all, estimate cost first with zencreator_estimate_price (or shop models with zencreator_compare_prices) and state the cost before submitting — see Generation tools. For deeper diagnosis of credit and NSFW issues, see Troubleshooting.

See also#

• Concepts — sessions, tasks, calls, assets, and credits.
• Troubleshooting — out of credits, NSFW disabled, re-authorization.
• Generation tools — pricing, estimation, and task submission.