Account & Credits Tools#

API reference for the MCP tools that report on the signed-in ZenCreator account: profile, credit balance, and the credit-spend ledger. These tools never spend credits — they are read-only.

There are two tools in this group:

• zencreator_get_me — profile + current credit balance + account flags.
• 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 allowed adult content, 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 — whether adult content is enabled on the account. User-actionable (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 is the exception — it is user-actionable. If nsfw_allowed is false and the user is asking for an NSFW generation, tell them: "Adult content is disabled on your ZenCreator account; enable it in account settings, then retry." Do not silently downgrade an NSFW request to SFW — that hides the real reason and wastes credits. If nsfw_allowed is true, say nothing about it. The "markdown" response already surfaces this warning automatically when the flag is false; pass it through as-is. The markdown form 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_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.