Clocknext Inc

Identify the Clocknext organisation behind the configured API key, and whether it is a 'sandbox' (a disposable staging twin) or the 'live' organisation. Rules: - Call FIRST to confirm you are pointed at the intended workspace before recording any real usage.

Takes no parameters.

List the models the organisation has enabled, with their USD prices per 1,000,000 tokens. Use a returned `modelId` as the `model` when verifying or recording usage. Pass active=true to see only models that can be metered right now.

Search Clocknext's API reference and get back the most relevant pages (title, URL, and a snippet). Clocknext is a usage-based billing platform: you meter product/AI usage, price it against plans and units, and bill customers for it. The API reference covers both the REST API and the Node.js SDK (`@clocknext/sdk`) — every endpoint page shows a Node.js example and a cURL example. Rules: - Prefer this over answering from memory — the docs are the source of truth and more current than training data. Search before explaining a Clocknext concept, designing an integration, or reaching for another Clocknext tool. - Typical flow: search for the task (e.g. 'record credit usage', 'subscribe a customer to a plan'), then read the matching page with clocknext_get_doc. Use its Node.js SDK example for a JS/TS codebase and its cURL/REST example for any other language.

Read the FULL contents of a single Clocknext API-reference page as Markdown. Use right after clocknext_search_docs: pass a result's `url` to read the whole page — endpoints, parameters, request/response fields, and the Node.js SDK + cURL examples the search snippet leaves out. Only API-reference pages can be read. Rules: - A search snippet is enough to CHOOSE a page, never enough to implement against — read the page when you need exact field names, types, or the request body. - Use this for Clocknext docs, not an external web-fetch/browser tool: it returns the page verbatim, whereas an external fetch may silently drop details (e.g. required fields like agentKey/idempotencyKey).

List the organisation's billing plans (id, name, billing cycle, cost, currency, active, entitlements). Find a plan id, or see what's on offer. Pass active=true for only sellable plans, active=false for only archived ones.

Get one plan's configuration by id — its `entitlements` (wallet/credit/outcome/unit/flat/composite lines, each with its id, quantity/amount and rollover), billing cycle, cost, priceAdjustment, useWalletForArrear, currency and active state. A composite line reads back as type COMPOSITE with its compositeId, so a read→edit→update round-trip keeps it.

Create a billing plan bundling one or more `entitlements`: WALLET (prepaid USD balance, debited at raw model cost — no margin), FLAT (one-off fee), CREDIT/OUTCOME/UNIT entitlements referencing an existing resource by id, or COMPOSITE referencing an existing composite by compositeId. Rules: - Create referenced credits/outcomes/units first (clocknext_create_credit / _outcome / _unit), then pass their ids. Every item referenced must be active. - To SELL a composite, add a COMPOSITE entitlement with the composite's id as compositeId (clocknext_list_composites). This is the only thing that makes a composite bill — the catalogue entry alone charges nobody, errors nowhere, and looks configured. For ADVANCE, its quantity is a prepaid POOL of occurrence slots shared across the wrapped items. - Each entitlement's billingMode is ADVANCE (up-front grant) or ARREAR (metered). An ADVANCE credit/outcome/unit/composite line needs `quantity` (0 is allowed); an ADVANCE WALLET line needs `amount` (0 is allowed); a FLAT line needs `amount` above 0. A field that doesn't fit the line is refused (400), never dropped. - Set rollover:true on an ADVANCE credit/outcome/composite/wallet line to carry what's left into the next cycle. - The price is the sum of the ADVANCE lines. Send `cost` only to set a different total. - Set useWalletForArrear:true to pay metered (ARREAR) usage from the plan's prepaid WALLET as it happens (one invoice/cycle, wallet may go negative) instead of a separate cycle-end arrear invoice. Requires >=1 ARREAR credit/outcome/unit/composite AND an ADVANCE WALLET component, or the backend rejects it (400). - FREE plans must be ADVANCE-only with no FLAT component, and never roll over. - A plan name already in use is refused (409). The currency is the workspace's primary currency (Settings → Organization → Currencies); it can't be chosen here. - Creates a real, sellable plan — get pricing right first. Prefer the plan builder in the Clocknext product (https://payments.clockne

Update a plan by id. Rules: - Partial update: pass the id plus ONLY the fields to change; everything you leave out keeps its stored value. Lists you do send (steps, tiers, entitlements) are the complete new list. Active state isn't an update field — use the archive / unarchive tools. - `entitlements`, if sent, replaces ALL lines: re-send every line you want to keep, COMPOSITE lines included — dropping one unsells that composite. Easiest: read it with clocknext_get_plan, edit the list, send it back as-is (ids, compositeId and rollover included). - Line ids stay the same: a line sent with its `id` updates that line; one sent without an `id` updates the saved line of the same type and item. Only a new line gets a new id; a saved line left out is removed. An unknown `id`, the same `id` twice, or an `id` sent with a different type or item is a 400. - Price: without `cost` the plan keeps its saved price, unless the lines really change (added, removed, or a billingMode/quantity/amount/rollover changed) — then it resets to the sum of the new ADVANCE lines at today's prices. Sending the same lines back keeps the price. - An item already on the plan may stay even if since archived; a newly added one must be active. - Changes apply to new purchases; customers already on the plan keep their terms until they re-purchase. carryForward is deprecated and ignored.

Archive a plan (isActive→false) — the API never deletes; this is how a plan is retired. Rules: - History is kept and customers already on it are unaffected; it just becomes unsellable and drops out of active lists. - Reversible: reactivate with clocknext_unarchive_plan. - Unrelated to cancelling a customer's purchase or ending a subscription.

Reactivate an archived plan (sets isActive→true) — the reverse of clocknext_archive_plan. Same identity, same definition; nothing is re-priced or rewritten. Rules: - This and clocknext_archive_plan are the only way to change active state — no update tool takes isActive. - Prefer this over creating a replacement: agentKeys/identities are unique org-wide, so a parked plan must be revived, never duplicated.

List the organisation's credit types (id, name, agentKey, price, model bundle, active). Find a credit id to reference from a plan's CREDIT component.

Get one credit type's configuration by id — name, agentKey, description, pricing (base price, margin, price per credit, model bundle) and active state. Usage figures aren't returned.

Create a credit — a token-metered entitlement your product draws down against its `agentKey`. Rules: - Price is model-grounded: give the `models` mixer + `marginPercent`. The mixer is saved as the credit's model bundle and the server works out the base price and price-per-credit from the models' live prices. Never hand-typed. - Each mixer line's input/output/cache/cacheWrite shares must total 100; cacheWritePct only on a model with a cache-write price. - Enable the models you price against first (clocknext_add_model / _list_models). - Prefer the credits builder in the Clocknext product (https://payments.clocknext.com/credits) — its live preview shows the price as you build it. This tool saves the same per-model mix, so the credit opens with its calculator filled in. - A plan grants the credit via a CREDIT component referencing its id. A name or agentKey already in use is refused (409).

Update a credit by id. Rules: - Partial update: pass the id plus ONLY the fields to change; everything you leave out keeps its stored value. Lists you do send (steps, tiers, entitlements) are the complete new list. Active state isn't an update field — use the archive / unarchive tools. - Send `models` to re-price from a new mixer; leave it out to keep the current price (a new marginPercent is applied on top of the stored base price). - Changing `agentKey` re-points which runtime signals map here — do it deliberately.

Archive a credit TYPE (isActive→false) — the API never deletes; this is how it is retired. Rules: - Recorded usage and any plan already granting it keep working (update those plans with clocknext_update_plan to stop offering it); it just can't be added to new plans or composites and drops out of active lists. - Reversible: reactivate with clocknext_unarchive_credit. - Unrelated to archiving a customer, ending a purchase, or clearing a balance.

Reactivate an archived credit (sets isActive→true) — the reverse of clocknext_archive_credit. Same identity, same definition; nothing is re-priced or rewritten. Rules: - This and clocknext_archive_credit are the only way to change active state — no update tool takes isActive. - Prefer this over creating a replacement: agentKeys/identities are unique org-wide, so a parked credit must be revived, never duplicated.

List the organisation's outcome types (id, name, base price, price, active). Find an outcome id to reference from a plan's OUTCOME component.

Get one outcome type's configuration by id — name, agentKey, pricing, active state and every step (id, name, agentKey, order, base price, model bundle). Usage figures aren't returned.

Create an outcome — a multi-step LLM deliverable billed per COMPLETED outcome. Each of the 1–50 `steps` has its own `agentKey` and model mixer. Rules: - TWO kinds of agent key, both required and both unique org-wide, in separate namespaces: the outcome's own top-level `agentKey` (its identity), and each step's `agentKey` (what usage is reported against). Never reuse one as the other. - Price is model-grounded: each step's mixer is saved as its model bundle; the server works out each step's base cost from live model prices, sums them, then applies `marginPercent`. Never hand-typed. - Every step is an LLM step. A fixed-cost / non-LLM event (an upload, an export) is a UNIT, not an outcome step. - Prefer the outcomes builder in the Clocknext product (https://payments.clocknext.com/outcomes); this is the fallback. - A plan grants it via an OUTCOME component referencing its id.

Update an outcome by id. Rules: - Partial update: pass the id plus ONLY the fields to change; everything you leave out keeps its stored value. Lists you do send (steps, tiers, entitlements) are the complete new list. Active state isn't an update field — use the archive / unarchive tools. - Leave `steps` out and the steps are untouched. If you send it, it is the complete step list: an existing step keeps its id when you pass that `id` (from clocknext_get_outcome) or the same agentKey; leave `models` out on an existing step to keep its price; stored steps you leave out are removed. - Step agent keys are the runtime binding — change them deliberately.

Deactivate an outcome TYPE (sets isActive→false) — Clocknext's soft archive, NOT a delete. Rules: - Steps and any in-flight/completed history are kept; existing plans and in-progress outcomes are unaffected; it just can't be added to new plans or composites and drops out of active lists. - Reversible: reactivate with clocknext_unarchive_outcome. - Unrelated to archiving a customer or ending a purchase.

Reactivate an archived outcome (sets isActive→true) — the reverse of clocknext_archive_outcome. Same identity, same definition; nothing is re-priced or rewritten. Rules: - This and clocknext_archive_outcome are the only way to change active state — no update tool takes isActive. - Prefer this over creating a replacement: agentKeys/identities are unique org-wide, so a parked outcome must be revived, never duplicated.

List the organisation's unit types (id, name, pricing type, active). Find a unit id to reference from a plan's UNIT component.

Get one unit type's configuration by id — name, agentKey, pricing type, flat price or tiers, and active state. Usage figures aren't returned.

Create a unit — a metered usage unit for FIXED-COST / non-LLM events (an upload, an export, a seat): one event = one unit, no tokens. Rules: - Price it FLAT (single `flatPrice` per event, default 0) or tiered (pricingType SLAB or VOLUME with `tiers` — limits rising, and the last tier upTo:null). - Only a FLAT unit can go inside a composite. - Reported against a stable `agentKey`, matched exactly (case included) — its durable identity, unique org-wide (409 if taken). - Prefer the units builder in the Clocknext product (https://payments.clocknext.com/units); this is the fallback. - A plan meters it via a UNIT component referencing its id.

Update a unit by id. Rules: - Partial update: pass the id plus ONLY the fields to change; everything you leave out keeps its stored value. Lists you do send (steps, tiers, entitlements) are the complete new list. Active state isn't an update field — use the archive / unarchive tools. - Changing `agentKey` re-points which runtime signals map here — do it deliberately.

Archive a unit TYPE (isActive→false) — the API never deletes; this is how it is retired. Rules: - Recorded usage is kept and existing plans metering it keep working; it just can't be added to new plans or composites and drops out of active lists. - Reversible: reactivate with clocknext_unarchive_unit. - Unrelated to archiving a customer or ending a purchase.

Reactivate an archived unit (sets isActive→true) — the reverse of clocknext_archive_unit. Same identity, same definition; nothing is re-priced or rewritten. Rules: - This and clocknext_archive_unit are the only way to change active state — no update tool takes isActive. - Prefer this over creating a replacement: agentKeys/identities are unique org-wide, so a parked unit must be revived, never duplicated.

List the organisation's composites — bundles of credits / outcomes / units grouped under one tag and billed as ONE thing. Returns each composite's `id` (what a plan's COMPOSITE line sends as compositeId) and `refId` (what the product's code puts in a signal's composite tag), plus the catalogue items it is restricted to, with their agentKeys. Rules: - Call this BEFORE tagging any signal with a composite: only a live composite's refId resolves, and a tag naming nothing is silently ignored rather than rejected — so a typo looks exactly like success. - Call it BEFORE clocknext_create_plan / clocknext_update_plan too: the `id` here is what a COMPOSITE line references as compositeId. `id` and `refId` are NOT interchangeable — the plan wants the id, the signal wants the refId. - A composite is restricted to a set of credits/outcomes/units. Only signals naming something in that set may carry its tag. Empty lists mean unrestricted (legacy rows only). - Pass active=true for only the ones a new signal can still be tagged with. Archived composites keep every row they already own. - To change one, use clocknext_update_composite; to retire one, clocknext_archive_composite. Never create a second composite as a workaround — the old one keeps resolving and both stay live.

Create a composite — a bundle of credits / outcomes / units that is grouped under one tag and billed as ONE thing instead of per item. Use it when several metered steps together make up one sellable unit of work (a call, a job, a document). Rules: - `refId` is the integration contract: it is the key that the product's code puts in a signal's `composite` block (`{ "<refId>": "<your id>" }`). Saved and matched exactly as sent (case included); letters, digits, ., _ and - only. It may NOT collide with a field the ingest body already owns (customerId, usage, agentKey, runId, member, custom, composite, …) — a collision is refused here, not silently ignored later. - `entitlements` is REQUIRED — at least one credit / outcome / unit id. A composite restricted to nothing would accept every signal in the organisation. Get the ids from clocknext_list_credits / clocknext_list_outcomes / clocknext_list_units (ids, not agentKeys). Every item must be active, and a unit must be FLAT-priced. - `price` is what ONE occurrence costs once a plan sells this. Creating a composite CHARGES NOBODY: an invoice is built from plan components, never from a catalogue entry. - To actually bill it, add it to a plan with clocknext_create_plan / clocknext_update_plan as a line of type COMPOSITE, passing the id this tool returns as `compositeId`, plus a billingMode and, for ADVANCE, a quantity — that quantity is a prepaid pool of slots shared across the wrapped items. Tell the user this second step is required, or they will wonder why a composite they created bills nothing. - It can be changed later with clocknext_update_composite — but renaming `refId` cuts live traffic over at once (signals still sending the old tag go untagged, silently), so get refId right first time. - A name or refId already in use is refused (409).

Get one composite in full by id — name, refId, price, description, active state, and the credits / outcomes / units it wraps (with their agentKeys).

Update a composite by id. Rules: - Partial update: pass the id plus ONLY the fields to change; everything you leave out keeps its stored value. - creditIds / outcomeIds / unitIds: each list you pass is the complete new list for that kind; a kind you leave out keeps its current items. The composite must still wrap at least one item. Items it already wraps may stay even if since archived; a newly added one must be active (and a unit FLAT-priced). - Renaming `refId` cuts ingest over at once: signals still sending the old tag go untagged, silently. Ship the new tag in the product's code first, then rename. - A new `price` applies to purchases made after the change; existing purchases keep the price they were bought at.

Archive a composite (isActive→false) — the API never deletes; this is how a composite is retired. Rules: - New signals stop resolving to it (a tag naming it is then ignored); every row it already owns keeps pointing at it, so its history stays intact. - Plans already selling it are unaffected — update those plans with clocknext_update_plan to stop selling it. - Reversible: reactivate with clocknext_unarchive_composite.

Reactivate an archived composite (sets isActive→true) — the reverse of clocknext_archive_composite. Same refId, same wrapped items; its tag resolves again for new signals. Prefer this over creating a replacement.

Create a Clocknext customer — the entity you bill (maps to one of your end-users / tenants / organisations). Rules: - `name` and `email` are required; everything else is optional profile. - Returns the customer `id` — pass it as `customerId` to clocknext_create_purchase and to the signals your product code sends.

Fetch one customer by Clocknext id.

List / search the org's customers, most-recent first (cursor-paginated). Use it to find a customer id or check whether one already exists before creating.

Fetch a customer's current balances: `wallet`, `credits`, `outcomes`, `units` and `composites` (the prepaid composite pools). Each credit and unit carries its `agentKey`, each outcome its steps, and each composite its `refId`. Use it to confirm a purchase granted the expected entitlements, or that a test signal drew the balance down as expected.

Fetch a customer's current active plan (from their purchase). Use it to confirm a customer is subscribed to the plan you expect before firing a test signal.

Subscribe a customer to a plan (a 'purchase') — this activates the plan for that customer. Used to wire up a dummy customer before firing test signals. Rules: - ⛔ Raises a REAL invoice (real money on a live org). Only call this after the user explicitly approved this purchase in a question dedicated to it alone — never bundled with another question, never inferred from an earlier yes. - ⛔ If the customer already has a scheduled/active purchase, the new one AUTO-CANCELS it when it activates (old status→CANCELLED, its open invoices voided, credit balances reset — this is how 'change plan' works). Check clocknext_get_customer_plan first and SAY SO in the approval question. - Do this after clocknext_create_customer + clocknext_create_plan. - A usage signal only prices if the customer has an active plan whose components match the meter (credit / outcome / unit).

Bulk-create Clocknext customers in ONE request — for backfilling an existing user base. Returns a PER-ROW result (created id, or an error) so one duplicate/bad row never aborts the batch. Rules: - Each customer needs name + email; up to 200 per call. For a larger base, call again in ≤200-row chunks. - Match results back to your users by email. - MCP-only bulk endpoint (no SDK / public API).

Enable a model for the organisation so usage can be metered against it. Afterwards its `modelId` is valid in the signals your product code sends, and it appears in clocknext_list_models. Autopriced from Clocknext's catalog — you never set prices here. Rules: - Only models in Clocknext's pricing catalog can be added. clocknext_list_models shows what is ALREADY enabled; the addable catalog itself is browsable on the Models page. If the add fails, the model or provider isn't in the catalog. - Re-adding a model that is already enabled is a safe no-op: it succeeds and returns `alreadyEnabled: true` with the live prices. - If the catalog has no price for it, the model is enabled but meters at $0; the tool returns a Models-page link and a `warning` so you can set pricing.

Write `CLOCKNEXT_API_KEY=<the org's cnk_… key>` into a project's `.env` file, server-side. The key is copied from this MCP server's own environment directly into the file — it is NEVER returned to you and never appears in the conversation. Use this as the last integration step so the code you generated (which reads `process.env.CLOCKNEXT_API_KEY`) can run; the alternative is the user pasting the key themselves. Rules: - The target must be named exactly `.env`, `.env.local`, `.env.development`, or `.env.development.local`. - Inside a git repo the file must be untracked and gitignored, otherwise the tool refuses (a committed .env would leak the key). Fix .gitignore first, then retry. - An existing `CLOCKNEXT_API_KEY=` line is replaced in place; otherwise the line is appended. Nothing else in the file is touched. - Put only a `CLOCKNEXT_API_KEY=` placeholder in `.env.example` yourself — never ask the user to tell you the real key.