Admin MCP tools
The admin MCP is a stateless Streamable-HTTP JSON-RPC endpoint at POST https://api.mozaik-dev.com/mcp (no sessions, no SSE — every POST is answered with JSON). Auth is a bearer mzk_ token only; the store is derived from the token — a store/storeId argument in tool input is refused as a validation error. Every tool call is synthesized into an ordinary HTTP request and replayed through the same router the admin panel uses, so auth, scope gates and the proposal divert are byte-identical to the public API.
initialize negotiates the protocol (2026-07-28 with legacy auto-detect) and enforces the client floor: a clientInfo that identifies as our CLI/Dev MCP below 0.1.0 is refused with -32001 client_too_old and the exact upgrade command (npm i -g @mozaik/cli@0.1.0). Third-party MCP clients are never refused for lacking a version.
Tool names are the registry's dotted ids verbatim — one tool per command, one per catalog route with a non-owner policy (commands.run/commands.list are omitted: commands are 1:1 tools already). The list below is buildToolList() with the full admin scope; a real token sees the scope-filtered subset. Resources: mzk://store, mzk://proposal/current, mzk://draft, mzk://sections-meta, mzk://docs/{path}.
Developer view (Geliştirici token — executes directly)
| tool | kind | policy | summary |
|---|---|---|---|
catalog.category.archive | command | propose | Archive a category (products keep their assignment; hidden from active lists). |
catalog.category.create | command | propose | Create a category (flat compliance taxonomy; taksitCap = BDDK installment cap). |
catalog.category.update | command | propose | Update a category's name, installment cap, or position. |
catalog.collection.archive | command | propose | Archive a collection — its page 404s; product memberships are kept. |
catalog.collection.create | command | propose | Create a collection (handle derived from title when omitted). |
catalog.collection.setProducts | command | propose | Wholesale-replace a collection's product list (order = array order = manual sort). |
catalog.collection.update | command | propose | Patch collection fields. |
catalog.digital.codes.add | command | propose | Add e-pin codes to a pooled digital product (sealed at rest; duplicates skipped). |
catalog.digital.codes.void | command | propose | Void unused pool codes (oldest first) — they can never be allocated; nothing is deleted. |
catalog.media.commit | command | propose | Commit a staged upload into the media library (variants generated async). |
catalog.media.delete | command | propose | Permanently delete an UNUSED media file (refused while referenced by catalog, live design, or the draft). |
catalog.price.set | command | propose | Set the price (kuruş) of a product (prd_) or variant (var_). compareAt only on products; null clears it. Variant price null = inherit product price. |
catalog.product.archive | command | propose | Archive a product — removed from the storefront, history kept. |
catalog.product.create | command | propose | Create a product. price/compareAt in kuruş; stock null = untracked; handle derived from title when omitted. |
catalog.product.setDigital | command | propose | Set a product's digital/shipping posture: requiresShipping, delivered digital content, withdrawal exception. |
catalog.product.setMedia | command | propose | Wholesale-replace a product's media list (order = array order; alt is per-usage). |
catalog.product.setVariants | command | propose | Wholesale-replace a product's variant STRUCTURE (order = array order). Existing variants update title/sku only; initial price/stock allowed solely for new variants. |
catalog.product.update | command | propose | Patch product fields. Price and stock are NOT here — use catalog.price.set / catalog.stock.set. |
catalog.stock.adjust | command | propose | Adjust stock by a ± delta (receiving, stocktake, connector sync). Fails on untracked items; expectedStock = compare-and-set. |
catalog.stock.set | command | propose | Set stock of a product (prd_) or variant (var_). null = untracked (always available). |
customer.anonymize | command | propose | Anonymize a customer row (KVKK request) — order snapshots stay under the statutory retention. |
customer.identity.unlink | command | propose | Clear a Mozaik ID pointer from this store's customers (revoke/erasure healing). |
extension.configure | command | propose | Set an extension's configuration (validated against its schema). Does not enable it. |
extension.disable | command | propose | Disable an extension. Its payment method / hooks / panels stop immediately. |
extension.enable | command | propose | Enable an installed extension. Requires its secrets set and config valid. |
extension.hook.deactivate | command | propose | Deactivate (or reactivate) an extension's hooks without disabling the extension. |
extension.install | command | propose | Install an extension for this store (disabled until configured + enabled). Grants the manifest's scopes. |
extension.uninstall | command | propose | Uninstall a disabled extension. Config is archived in the audit row; secrets and data are kept. |
extension.upgrade | command | propose | Upgrade an installed extension to the platform's current manifest version. |
metafield.definition.create | command | propose | Define a typed custom field on products, variants, collections, or the store. |
metafield.definition.delete | command | propose | Delete a metafield definition AND every value stored under it. |
metafield.definition.update | command | propose | Update a metafield definition's label, description, or validations (type/key are immutable). |
metafield.set | command | propose | Set a metafield value on a product, variant, collection, or the store. |
metafield.unset | command | propose | Remove a metafield value. |
order.cancel | command | propose | Cancel an unpaid order (pending_cod/awaiting_transfer) — restocks lines. |
order.cod.collect | command | propose | Record that the carrier's COD cash for a shipped/delivered order reached the merchant — order becomes paid. |
order.note.add | command | propose | Append a merchant note to an order's timeline. |
order.return.approve | command | propose | Approve a return — issues the instructions the shopper sees (snapshotted as evidence). |
order.return.receive | command | propose | Record the returned goods arriving — per-line condition; saleable lines restock (ledgered). |
order.return.reject | command | propose | Reject a return with a stated reason (the shopper mail carries the THH/consumer-court recourse). |
order.ship | command | propose | Create a shipment for an order's shippable lines (a cargo extension or a manual carrier) — writes the VUK 509 forward fields. |
order.shipment.cancel | command | propose | Cancel a shipment before carrier handoff completes — resets the order to unfulfilled when nothing else is active. |
order.shipment.track | command | propose | Record a carrier state transition (webhook/poll/manual) and aggregate the order's fulfillment status. |
order.transfer.confirm | command | propose | Confirm a bank-transfer payment arrived — order becomes paid; digital content is released. |
proposal.submit | command | direct | Submit an open proposal for the store owner's review (the owner is mailed a link). The proposalId comes from your first recorded mutation's response — or proposals.list. |
proposal.withdraw | command | direct | Withdraw a proposal that has not been applied. |
settings.checkout.update | command | propose | Update checkout legal settings: delivery estimate, return-cargo carrier/cost disclosure. |
settings.flag.set | command | propose | Set or clear a store readiness flag (ETBİS beyanı, rehber kartları). |
settings.identity.update | command | propose | Set the legal merchant identity (6563 m.3) — complete rows only; rendered live in the footer. |
settings.store.update | command | propose | Update store settings (display name). Projected to KV tenant records. |
store.syncKv | command | direct | Re-project store state (t:, l:, live b:, g:) from Postgres to KV; bumps generation once. |
audit.list | route | read | Recent audit rows for the store (optionally by entity). |
cargo.carriers.list | route | read | Platform carrier reference table (codes, labels, tracking availability). |
catalog.categories.list | route | read | List categories. |
catalog.collections.get | route | read | Get one collection with members. |
catalog.collections.list | route | read | List collections. |
catalog.products.get | route | read | Get one product with variants, media and stock. |
catalog.products.list | route | read | List products (keyset cursor, filters). |
catalog.stockMovements.list | route | read | Stock ledger rows for a product or variant. |
design.draft.delete | route | workspace | Discard the draft (expectedRev). |
design.draft.get | route | read | Read the draft bundle (rev, hash, body, preview link). |
design.draft.put | route | workspace | Replace the draft bundle under optimistic concurrency (expectedRev). |
design.draftFromTemplate | route | workspace | Instantiate a starter template as the draft. |
design.previewUrl.get | route | read | Signed preview link: ?hash= freezes a snapshot, ?workspace= follows that workspace's current draft (the dev-loop link). |
design.templates.list | route | read | Starter template cards. |
design.version.get | route | read | Full body of a published version. |
design.versions.list | route | read | Published version ledger (seq, hash, label, live marker). |
ext.cargo.sender | route | propose | Create the sender address at the cargo provider and store its id in the extension config. |
extensions.list | route | read | Installed + available extensions with config, secrets state and manifest UI hints (owner-only). |
extensions.ops.get | route | read | The extension's agent contract with LIVE readiness: every op, what it needs (secrets/config/enabled), and exactly what blocks it right now. Secrets appear as keys only. |
media.list | route | read | List media objects. |
media.upload | route | workspace | Stage a binary upload (raw body); commit with catalog.media.commit. |
meta.get | route | read | Platform build identity and compatibility fingerprint (buildId, registryHash, minCli). |
metafields.definitions.list | route | read | Metafield definitions (owner-only). |
orders.belge.get | route | read | Fetch a legal document snapshot of an order. |
orders.cargo.book | route | propose | Accept a carrier offer, create the label and ship the order. |
orders.cargo.offers | route | quote | Create a provider quote for the order and return carrier offers (no store mutation). |
orders.cargo.ship | route | propose | Ship with the merchant's own carrier (manual tracking). |
orders.cod.collect | route | propose | Mark a cash-on-delivery order as collected. |
orders.get | route | read | Get one order with lines, payment, shipments, returns, timeline. |
orders.list | route | read | List orders. |
orders.note.add | route | propose | Add a merchant note to the order timeline. |
orders.refund | route | propose | Refund part or all of a captured payment through the original PSP extension. |
orders.shipment.cancel | route | propose | Cancel a shipment before pickup. |
orders.shipment.label | route | quote | Fetch the shipping label URL from the provider. |
orders.shipment.track | route | propose | Record a shipment status transition by hand. |
orders.shipment.update | route | propose | Poll the provider and apply the current tracking status. |
proposals.get | route | read | One proposal with its items, recorded previews and (for design items) a preview link. |
proposals.list | route | read | List proposals; agent tokens see only their own. |
returns.approve | route | propose | Approve a return request with shipping instructions; mails the shopper. |
returns.get | route | read | Get one return request. |
returns.list | route | read | List return requests. |
returns.reject | route | propose | Reject a return request with a reason; mails the shopper. |
routes.list | route | read | List typed routes with JSON Schemas (the twin of commands.list). |
scopes.list | route | read | Scope registry: TR labels, sensitivity and who may hold each scope (any token / developer tokens / sessions only). |
sections.meta.get | route | read | Section catalog with props/blocks JSON Schemas and placement rules. |
store.checkoutSettings.get | route | read | Checkout settings (owner-only). |
store.health.get | route | read | Store readiness checklist (draft/live, identity, flags). |
store.identity.get | route | read | Legal identity block (owner-only). |
tokens.whoami | route | read | Describe the calling credential: store, kind, scopes, expiry, workspace — what an agent should call first. |
validate.bundle | route | quote | Validate a store bundle (schema + referential integrity) without saving anything. Media readiness is checked at draft save, which is the enforcement point. |
validate.command | route | quote | Validate a command payload against its registered schema without running it (no preview, no mutation). |
validate.manifest | route | quote | Validate an extension manifest against zExtensionManifest, including the agent-contract rules. |
workspaces.adopt | route | workspace | Copy a workspace draft into the builder's main draft under optimistic concurrency (never a merge). |
workspaces.list | route | read | List draft workspaces: the builder's main draft plus every agent/developer workspace with its draft rev and sandbox state. |
Agent view (Ajan token — propose tools are recorded, not applied)
The same names; propose tools answer PROPOSED (not applied) and record the call into the token's open proposal for the owner to review.
| tool | kind | policy | proposal-recorded | summary |
|---|---|---|---|---|
catalog.category.archive | command | propose | ✓ | Archive a category (products keep their assignment; hidden from active lists). |
catalog.category.create | command | propose | ✓ | Create a category (flat compliance taxonomy; taksitCap = BDDK installment cap). |
catalog.category.update | command | propose | ✓ | Update a category's name, installment cap, or position. |
catalog.collection.archive | command | propose | ✓ | Archive a collection — its page 404s; product memberships are kept. |
catalog.collection.create | command | propose | ✓ | Create a collection (handle derived from title when omitted). |
catalog.collection.setProducts | command | propose | ✓ | Wholesale-replace a collection's product list (order = array order = manual sort). |
catalog.collection.update | command | propose | ✓ | Patch collection fields. |
catalog.digital.codes.add | command | propose | ✓ | Add e-pin codes to a pooled digital product (sealed at rest; duplicates skipped). |
catalog.digital.codes.void | command | propose | ✓ | Void unused pool codes (oldest first) — they can never be allocated; nothing is deleted. |
catalog.media.commit | command | propose | ✓ | Commit a staged upload into the media library (variants generated async). |
catalog.media.delete | command | propose | ✓ | Permanently delete an UNUSED media file (refused while referenced by catalog, live design, or the draft). |
catalog.price.set | command | propose | ✓ | Set the price (kuruş) of a product (prd_) or variant (var_). compareAt only on products; null clears it. Variant price null = inherit product price. |
catalog.product.archive | command | propose | ✓ | Archive a product — removed from the storefront, history kept. |
catalog.product.create | command | propose | ✓ | Create a product. price/compareAt in kuruş; stock null = untracked; handle derived from title when omitted. |
catalog.product.setDigital | command | propose | ✓ | Set a product's digital/shipping posture: requiresShipping, delivered digital content, withdrawal exception. |
catalog.product.setMedia | command | propose | ✓ | Wholesale-replace a product's media list (order = array order; alt is per-usage). |
catalog.product.setVariants | command | propose | ✓ | Wholesale-replace a product's variant STRUCTURE (order = array order). Existing variants update title/sku only; initial price/stock allowed solely for new variants. |
catalog.product.update | command | propose | ✓ | Patch product fields. Price and stock are NOT here — use catalog.price.set / catalog.stock.set. |
catalog.stock.adjust | command | propose | ✓ | Adjust stock by a ± delta (receiving, stocktake, connector sync). Fails on untracked items; expectedStock = compare-and-set. |
catalog.stock.set | command | propose | ✓ | Set stock of a product (prd_) or variant (var_). null = untracked (always available). |
customer.anonymize | command | propose | ✓ | Anonymize a customer row (KVKK request) — order snapshots stay under the statutory retention. |
customer.identity.unlink | command | propose | ✓ | Clear a Mozaik ID pointer from this store's customers (revoke/erasure healing). |
extension.configure | command | propose | ✓ | Set an extension's configuration (validated against its schema). Does not enable it. |
extension.disable | command | propose | ✓ | Disable an extension. Its payment method / hooks / panels stop immediately. |
extension.enable | command | propose | ✓ | Enable an installed extension. Requires its secrets set and config valid. |
extension.hook.deactivate | command | propose | ✓ | Deactivate (or reactivate) an extension's hooks without disabling the extension. |
extension.install | command | propose | ✓ | Install an extension for this store (disabled until configured + enabled). Grants the manifest's scopes. |
extension.uninstall | command | propose | ✓ | Uninstall a disabled extension. Config is archived in the audit row; secrets and data are kept. |
extension.upgrade | command | propose | ✓ | Upgrade an installed extension to the platform's current manifest version. |
metafield.definition.create | command | propose | ✓ | Define a typed custom field on products, variants, collections, or the store. |
metafield.definition.delete | command | propose | ✓ | Delete a metafield definition AND every value stored under it. |
metafield.definition.update | command | propose | ✓ | Update a metafield definition's label, description, or validations (type/key are immutable). |
metafield.set | command | propose | ✓ | Set a metafield value on a product, variant, collection, or the store. |
metafield.unset | command | propose | ✓ | Remove a metafield value. |
order.cancel | command | propose | ✓ | Cancel an unpaid order (pending_cod/awaiting_transfer) — restocks lines. |
order.cod.collect | command | propose | ✓ | Record that the carrier's COD cash for a shipped/delivered order reached the merchant — order becomes paid. |
order.note.add | command | propose | ✓ | Append a merchant note to an order's timeline. |
order.return.approve | command | propose | ✓ | Approve a return — issues the instructions the shopper sees (snapshotted as evidence). |
order.return.receive | command | propose | ✓ | Record the returned goods arriving — per-line condition; saleable lines restock (ledgered). |
order.return.reject | command | propose | ✓ | Reject a return with a stated reason (the shopper mail carries the THH/consumer-court recourse). |
order.ship | command | propose | ✓ | Create a shipment for an order's shippable lines (a cargo extension or a manual carrier) — writes the VUK 509 forward fields. |
order.shipment.cancel | command | propose | ✓ | Cancel a shipment before carrier handoff completes — resets the order to unfulfilled when nothing else is active. |
order.shipment.track | command | propose | ✓ | Record a carrier state transition (webhook/poll/manual) and aggregate the order's fulfillment status. |
order.transfer.confirm | command | propose | ✓ | Confirm a bank-transfer payment arrived — order becomes paid; digital content is released. |
proposal.submit | command | direct | Submit an open proposal for the store owner's review (the owner is mailed a link). The proposalId comes from your first recorded mutation's response — or proposals.list. | |
proposal.withdraw | command | direct | Withdraw a proposal that has not been applied. | |
settings.checkout.update | command | propose | ✓ | Update checkout legal settings: delivery estimate, return-cargo carrier/cost disclosure. |
settings.flag.set | command | propose | ✓ | Set or clear a store readiness flag (ETBİS beyanı, rehber kartları). |
settings.identity.update | command | propose | ✓ | Set the legal merchant identity (6563 m.3) — complete rows only; rendered live in the footer. |
settings.store.update | command | propose | ✓ | Update store settings (display name). Projected to KV tenant records. |
store.syncKv | command | direct | Re-project store state (t:, l:, live b:, g:) from Postgres to KV; bumps generation once. | |
audit.list | route | read | Recent audit rows for the store (optionally by entity). | |
cargo.carriers.list | route | read | Platform carrier reference table (codes, labels, tracking availability). | |
catalog.categories.list | route | read | List categories. | |
catalog.collections.get | route | read | Get one collection with members. | |
catalog.collections.list | route | read | List collections. | |
catalog.products.get | route | read | Get one product with variants, media and stock. | |
catalog.products.list | route | read | List products (keyset cursor, filters). | |
catalog.stockMovements.list | route | read | Stock ledger rows for a product or variant. | |
design.draft.delete | route | workspace | Discard the draft (expectedRev). | |
design.draft.get | route | read | Read the draft bundle (rev, hash, body, preview link). | |
design.draft.put | route | workspace | Replace the draft bundle under optimistic concurrency (expectedRev). | |
design.draftFromTemplate | route | workspace | Instantiate a starter template as the draft. | |
design.previewUrl.get | route | read | Signed preview link: ?hash= freezes a snapshot, ?workspace= follows that workspace's current draft (the dev-loop link). | |
design.templates.list | route | read | Starter template cards. | |
design.version.get | route | read | Full body of a published version. | |
design.versions.list | route | read | Published version ledger (seq, hash, label, live marker). | |
ext.cargo.sender | route | propose | ✓ | Create the sender address at the cargo provider and store its id in the extension config. |
extensions.list | route | read | Installed + available extensions with config, secrets state and manifest UI hints (owner-only). | |
extensions.ops.get | route | read | The extension's agent contract with LIVE readiness: every op, what it needs (secrets/config/enabled), and exactly what blocks it right now. Secrets appear as keys only. | |
media.list | route | read | List media objects. | |
media.upload | route | workspace | Stage a binary upload (raw body); commit with catalog.media.commit. | |
meta.get | route | read | Platform build identity and compatibility fingerprint (buildId, registryHash, minCli). | |
metafields.definitions.list | route | read | Metafield definitions (owner-only). | |
orders.belge.get | route | read | Fetch a legal document snapshot of an order. | |
orders.cargo.book | route | propose | ✓ | Accept a carrier offer, create the label and ship the order. |
orders.cargo.offers | route | quote | Create a provider quote for the order and return carrier offers (no store mutation). | |
orders.cargo.ship | route | propose | ✓ | Ship with the merchant's own carrier (manual tracking). |
orders.cod.collect | route | propose | ✓ | Mark a cash-on-delivery order as collected. |
orders.get | route | read | Get one order with lines, payment, shipments, returns, timeline. | |
orders.list | route | read | List orders. | |
orders.note.add | route | propose | ✓ | Add a merchant note to the order timeline. |
orders.refund | route | propose | ✓ | Refund part or all of a captured payment through the original PSP extension. |
orders.shipment.cancel | route | propose | ✓ | Cancel a shipment before pickup. |
orders.shipment.label | route | quote | Fetch the shipping label URL from the provider. | |
orders.shipment.track | route | propose | ✓ | Record a shipment status transition by hand. |
orders.shipment.update | route | propose | ✓ | Poll the provider and apply the current tracking status. |
proposals.get | route | read | One proposal with its items, recorded previews and (for design items) a preview link. | |
proposals.list | route | read | List proposals; agent tokens see only their own. | |
returns.approve | route | propose | ✓ | Approve a return request with shipping instructions; mails the shopper. |
returns.get | route | read | Get one return request. | |
returns.list | route | read | List return requests. | |
returns.reject | route | propose | ✓ | Reject a return request with a reason; mails the shopper. |
routes.list | route | read | List typed routes with JSON Schemas (the twin of commands.list). | |
scopes.list | route | read | Scope registry: TR labels, sensitivity and who may hold each scope (any token / developer tokens / sessions only). | |
sections.meta.get | route | read | Section catalog with props/blocks JSON Schemas and placement rules. | |
store.checkoutSettings.get | route | read | Checkout settings (owner-only). | |
store.health.get | route | read | Store readiness checklist (draft/live, identity, flags). | |
store.identity.get | route | read | Legal identity block (owner-only). | |
tokens.whoami | route | read | Describe the calling credential: store, kind, scopes, expiry, workspace — what an agent should call first. | |
validate.bundle | route | quote | Validate a store bundle (schema + referential integrity) without saving anything. Media readiness is checked at draft save, which is the enforcement point. | |
validate.command | route | quote | Validate a command payload against its registered schema without running it (no preview, no mutation). | |
validate.manifest | route | quote | Validate an extension manifest against zExtensionManifest, including the agent-contract rules. | |
workspaces.adopt | route | workspace | Copy a workspace draft into the builder's main draft under optimistic concurrency (never a merge). | |
workspaces.list | route | read | List draft workspaces: the builder's main draft plus every agent/developer workspace with its draft rev and sandbox state. |
Generated from the live platform registries at build time — reference pages cannot go stale. Markdown variant: /reference/mcp-tools.md