# Agents

What an agent can read from the catalog over MCP, how it proposes a change that a person approves, the scopes that open it and how to connect a client.

An editor asks an assistant "which ski jackets still have no description?" or "what does the draft of the Touren-Ski X say?", and the answer comes from the catalog, not from the model's memory. The catalog serves an [MCP](https://modelcontextprotocol.io) endpoint for this. An agent reads products, published Type definitions and category references, but it never changes anything itself: it proposes creating, copying, editing or publishing a product, and nothing happens until a person approves it in the admin.

## What an agent can read

| Tool                 | Asks                                                                                                                                                               | Answers                                                                                                                                                                                                                             |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `find_products`      | `text`, `category`, `status`, `where` (attributes and the values they hold), `missing` (an attribute with no value), `incomplete` (a language), `after` (a `next`) | At most 25 products: `ref`, `title`, `status`, the draft `revision`, `completeness` and `owned`, the fields a Source owns by path; `count`, `next` and the `sources` by name                                                        |
| `list_filters`       | nothing                                                                                                                                                            | The attributes `where` filters by, as the panel's grid does: each with its label and kind, the values a choice offers, or the `register` whose entries it links                                                                     |
| `find_entries`       | `register`, `text` (a name in any language, or a ref), `after` (a `next`)                                                                                          | At most 25 entries with their `ref` and `name`, `count` and `next`                                                                                                                                                                  |
| `list_product_types` | `after` (a `next`)                                                                                                                                                 | At most 25 published Types with `id`, `key` and `label`; the `schema` and `settings` version numbers and configured `locales`. Does not show the type designer's unpublished draft.                                                 |
| `read_product_type`  | `type` (a Type id), `after` (an attribute page's `next`)                                                                                                           | The Type's defaults and up to 25 attribute uses/declarations per page, including kinds/settings, choices, requirements, localization, product/variant level and axis flags; schema/settings versions and locales.                   |
| `find_categories`    | `text` (part of a ref or working title in any language), `after` (a `next`)                                                                                        | At most 25 categories in tree order, including unpublished ones: refs, parents, titles, slugs and publication; the tree's Source owner. This reads the same tree as the panel, not products in a category.                          |
| `read_draft`         | `ref`, `section` (`all`, `fields`, `variants` or `media`), `after` (a section's `next`), `version` (`draft` or `live`)                                             | Draft/live names and selected sections, draft `revision`, schema/settings versions, `owned`, language completeness and the server's `publishCheck`. `all` is the default: fields plus first pages of variants and media references. |

Words in `text` match a product's name, ref, SKUs and searchable text. A brand, like every link to a register's entry, is not text: "how many products from Deuter?" is `list_filters` to see that the brand links the Brands register, `find_entries` with `text: "Deuter"` for its ref, and `find_products` with `where: [{ attribute, values: [ref] }]`, whose `count` is the answer.

`publishCheck` is the catalog's own publish run on a copy, so it says what Publish says: `ready` with warnings, `unchanged`, `blocked` with the audit's errors, or `incomplete` with what the Type requires and lacks, such as the EAN of a variant. Nothing is filed.

Every answer is structured content that matches the tool's `outputSchema`, which comes from the same contract as the panel's routes. Lists are capped at 25 rows per page and answers at 64 KB. An oversized answer is refused, never silently cut. Narrow `read_draft` to a section when needed; an individual section that still exceeds 64 KB is refused too. The agent never chooses the shop, the endpoint or the page size: the shop is the catalog the token was issued for, the person is the token's, and the cap is the catalog's.

### Reading every section

Type discovery, Type attributes and categories answer with `rows`, `count`, `complete` and, when another page exists, `next`. Follow `next` as `after` with the same question. Schema/settings changes invalidate Type cursors; changes to the matching category list invalidate its cursor.

Each document in `read_draft` has `type`, `name` and a document-level `complete` flag. Its optional `fields` contains slugs, search metadata, attributes, ordered category refs and retired values. `variants` and `media` are separate pages with `rows`, `count`, `complete` and `next`. Variants include all stored details, including shipping, tax category, net content, limits and appointment needs. Media references retain IDs, dimensions, digest, alt/decorative metadata, focal point and variant-option assignments, without delivery URLs. Reading a media reference does not ingest or assign an image.

For example, continue `draft.variants.next` with the same `ref`, `section: "variants"`, `version: "draft"` and `after: next`. Continue the live version's media with `section: "media"`, `version: "live"`. A continuation returns only the selected document and section; an omitted section is **not empty**. Without `after`, both documents are returned where a live version exists. A document is `complete: true` only when one `all` answer contains all its fields and every variant/media reference. A page's `complete: true` only says there is no further page of that section.

Every continuation carries the draft revision, schema/settings versions and live version it started with. A change to any invalidates the cursor; restart rather than combining different snapshots. Publishing or editing still needs its own exact-action approval, regardless of what was read.

What a Source owns is shown, not hidden: an agent that reads `owned` knows which fields an editor cannot change here.

## What an agent can propose

| Tool                | Asks                                                                                                    | Answers                                                                                                  |
| ------------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `create_product`    | New `ref`, `type`, `locale`, `name`, `schema` and `settings` from Type discovery                        | Approval of one new unpublished editorial draft, including its generated slug; then `ref` and `revision` |
| `duplicate_product` | New `ref`, `locale`, `name`, plus `source`, source `basedOn`, `schema` and `settings` from `read_draft` | Approval of the complete editorial copy and exclusions; then the new `ref` and `revision`                |
| `edit_draft`        | `ref`, `basedOn`, `schema`, `settings` from `read_draft` and up to 200 native field `edits`             | A request for approval; after it, `ref` and the draft `revision` the approved change made                |
| `publish_product`   | `ref`, `basedOn` and the `locales` to release                                                           | A request for approval, separate from any change to the draft; after it, the `version` made              |

An edit uses the panel's native operations: `set` or `clear` a field path, `add_variant` with a fresh variant id and axes, or `remove_variant` by id. Supported paths include names, slugs, search texts, typed product and variant attributes, axes, variant details, categories and existing media references. Read `read_product_type` for each attribute's kind and allowed values; rich text takes simple HTML or its structured document. Prices, stock and product deletion cannot be proposed, and nothing is changed in bulk. A product whose field a Source owns refuses that field: it can only be changed there.

Creation uses the panel's native Type/name/locale semantics. Complete it afterwards with `edit_draft`; publication always needs its own approval. A copy takes the whole working draft, not a partial MCP page: names (with the requested name in its locale), search texts, categories, media references and variant axes, with fresh variant IDs. It clears all slugs, SKUs, variant commercial overrides (shipping, tax category, net content, limits and appointments), retired values and GTIN/MPN attributes. Offers, stock, Source ownership, scheduling, publication and history never transfer. The original and its Source claims stay unchanged; a new editorial copy will not follow that Source.

An attribute's **When duplicating** setting in the Type designer explicitly says Copy or Clear (`copyOnDuplicate`). Brand and description roles default to Copy; GTIN and MPN always Clear, even if marked Copy. A present non-axis value with neither a role rule nor an explicit setting refuses the copy. Axes are the Type's explicit variant structure; an axis classified as an identifier refuses duplication instead of losing that structure. No identifier is inferred from its key or label.

The approval keeps the exact new document, fresh variant identities and excluded values. A new target must still be absent, the schema/settings must still match, and a copy's source revision must still match. These conditions are rechecked atomically with the authenticated approval, not by calling an unconditional create route after consent. A conflicting proposal never upserts an existing target. Repeated approval or a lost-response retry returns the same product and revision.

Variants are edited individually, never by replacing or clearing the whole variants list. A media or category list replaces its entire contents: read every page before proposing it and retain entries the person did not ask to change. Media edits name existing library references, not delivery URLs; the catalog resolves them through its native media rules.

No tool writes a product on the first call. The first call checks what is certain already and answers it at once: a person without the Products edit level, a stale draft or Schema/settings version, a field a Source owns, an invalid value, a publish that its checks refuse. Otherwise the catalog records a **proposal** in the shop's database: the person (the token's), the client, the shop and endpoint, the product, the operation, the edits and the versions they were written against. It expires after 15 minutes and is removed a day after that, with the changes it proposed. Approval checks these conditions again, and a draft change never changes the live version.

### How a client handles the approval

The answer is `resultType: "input_required"` with one input request, `approval`, an `elicitation/create` in URL mode whose URL is the approval view on the admin's own address, and a `requestState` holding the proposal's handle. The client shows the full URL, asks the person before it opens it, and opens it in a browser where they are signed in to the admin. There the person sees the product, the revision, each changed field with before and after, and chooses _Approve_ or _Reject_. When they have, the client calls the tool again with the same arguments, the `inputResponses` and the `requestState` it was given, byte for byte.

The retry finishes the call:

- Pending: the same request for approval again.
- Approved: the one outcome, "Saved as revision 43." or "Published as version 7.", every time it is asked, with nothing written again.
- Rejected or expired: an error that says so and that nothing was changed.
- Approved but not applicable: the draft changed meanwhile or a Source took the field; an error says why and that nothing was changed. A revoked session or lost Products level instead refuses approval and leaves the proposal pending.
- A `requestState` that was altered, another call's arguments, another client or another person's token: refused as belonging to no pending proposal.

That a client answered the request, even with _accept_, approves nothing: only the person's click in the admin does. No tool approves, and a token of this endpoint cannot open the approval view or its routes; they take the signed-in person's own session, and only the person the proposal is for.

When the person clicks _Approve_, the admin's page asks the sign-in for a grant: a token for that one proposal and that one browser session, which lives 30 seconds and is handed out only against the session cookie. The catalog takes nothing else for an approval, so the staff token the page keeps for 15 minutes, or a copy of it, approves nothing. A grant is not proof of who the person is now: once the catalog holds the proposal's and the product's locks, it asks the sign-in again, which reads that session and the person's membership as they are at that moment. A session that ended, or a person removed or without the Products level, writes nothing, and the owner's publishing override follows the role just read. If the sign-in does not answer, nothing is written either and the person approves again.

A client that does not support URL mode gets the approval URL in the tool's error result instead. The person opens it, approves, and asks the assistant again with the same arguments; the catalog answers the outcome of that proposal.

The admin's own chat embeds the native approval: short changes show every before/after value and _Approve_/_Reject_ inline; longer or structural changes open the complete review in a dialog over the current screen. Closing the dialog decides nothing. A successful decision resumes the original pending call automatically; a failed resume offers _Retry_ without another save. External clients still use the standalone approval URL and unchanged retry arguments/state. OpenCode V2 documents the same URL input requests; other clients may show the manual fallback.

## Who may ask

The endpoint is `{catalog address}/mcp`, MCP revision 2026-07-28, streamable HTTP, `POST` only, with no session: every request carries its own version and capabilities and any instance answers it. A client that speaks another revision is refused with `-32022`, naming `2026-07-28`. `server/discover` answers what the endpoint offers, and `tools/list` comes in a fixed order with `ttlMs` of five minutes and `cacheScope: "private"`, so a client may keep the list for one person and its prompt cache stays stable. There is no sampling, no roots, no logging and no event stream.

Every request carries an access token from the shop's staff sign-in, and every request is judged again:

- The token must be issued for this endpoint (`aud` is the endpoint's address, exactly) by this shop's sign-in. A token for another endpoint or another shop is refused; the refusal says so without naming anything of the other.
- It must carry the scope the tool needs: `catalog:products.read` for finding and reading, `catalog:products.write` for creating, copying, editing and publishing. Without it the answer is `403` with `insufficient_scope` naming only the scope that is missing, so a client that can read keeps reading while it asks the person for the write scope. A scope never widens the person's role: proposing needs the Products edit level, checked from the token on the first call and again when the person approves.
- The person must be on the staff and hold the Products area at view or edit. The token carries their roles as the sign-in read them from the staff when it issued the token, and it lives at most five minutes; the sign-in reads them again at each refresh and issues nothing to someone removed. So a person removed from the staff, or one who lost the area, is refused within five minutes at most.

A `401` carries `WWW-Authenticate: Bearer resource_metadata="…"`, which points at the resource's metadata ([RFC 9728](https://www.rfc-editor.org/rfc/rfc9728)) at `/.well-known/oauth-protected-resource/mcp`. It names the staff sign-in as the authorization server and `catalog:products.read` and `catalog:products.write` as the scopes, so a client finds where to sign in on its own. The person consents to the client and the scope there; a token copied from the panel does not open this endpoint.

A tool's annotations and descriptions help the model and enforce nothing: the checks above do.

## Connect a client

Give the client the endpoint, `https://catalog.example.com/mcp`. A client that follows the MCP authorization flow discovers the sign-in from the metadata, sends the person there once, and keeps the token it is issued, which lives at most five minutes.

## What is logged

A call logs its tool, whether it was answered, refused or failed, and how long it took. The tool is read from the `Mcp-Method` and `Mcp-Name` headers for the log, so no product content, question or person reaches the logs. Every consumed proposal, approved, rejected or refused by the product's rules, leaves one record in the shop's database: the person, the agent's client, the operation, the product and revision, the outcome and, where the rules refused, the problem's code, and never any text. An expired grant, revoked authority or unavailable sign-in consumes nothing and records no decision. The proposal itself holds the proposed text and goes a day after it expired. An approved change is published and saved under the approving person's name, as if they had made it in the panel.