MCP configuration tools

The tools behind the configuration door /mcpconfig: the ones an environment is set up with. Products and prices, the front end and the theme, e-mail templates and the booking workflow. A key with scope config opens this door; how to connect is described in Connecting an AI agent to the MCP server. The daily work sits behind a different door — see MCP operations tools.

Plan and apply are two tools

Every writing act here consists of two tools: ..._plan shows what would change and writes nothing, ..._apply carries it out. That is not a formality but the heart of how this door is used safely: you show a plan to somebody who says yes to it, and only then is anything written. They each have their own right, so you can let somebody look without letting them change.

An _apply that finds nothing to change is a success, not an error: if the value already was what was asked for, the answer says nothing changed. A client that lost its answer can therefore simply try again.

Two locks, plus the production lock

Before anything is written here, two locks must be open: one set by the supplier for the whole environment, and one set by the license holder. If either is closed, even the plan is refused — otherwise the door you cannot open would still describe in full detail what is behind it.

On top of that, the heaviest tools face a third condition: on a production environment they do not run at all. Those are the tools with level 2 in the table below — the statuses and the automatic status transitions. Changing those decides which e-mail goes out at which status change, and at the next job run that is real post to real customers. Changing theme CSS is allowed on production: that is visible and reversible.

The tools

Making a product bookable

A product can only be booked once it has periods, opening hours, prices and a calendar. The quickest way is copying: object_copy creates a new product as a copy of an existing one, with everything attached, and starts it switched off. You then change what is different and switch it on with product_set_active.

Starting from scratch, the order is:

1. object_create: the product itself.
2. object_set_periods: how long it is booked, for example an hour, a half day or a day.
3. object_set_opening_hours: when it is open, in one or more groups.
4. object_set_price_schemas: the prices per period, in one or more groups.
5. object_set_calendar: which price group and opening-hours group apply on which dates.
6. Where needed object_set_extras, object_set_participants, object_set_questions, object_set_resources and object_set_attributes.
7. product_set_active: switch it on. availability_why_not_bookable tells you why a product cannot be booked on a date yet.

A number of things are guarded along the way:

• Every list is complete. You send all periods, opening hours or options that should exist afterwards. Anything not in the list is removed. Existing rows are updated and keep their number.
• A calendar row may only name groups that exist, and a group the calendar still uses cannot be removed. To switch price groups, add the new group first, switch the calendar and only then leave out the old group.
• Overlapping times on one day and overlapping calendar rows are refused before anything is stored.
• Write times as hh:mm. 24:00 is midnight, 26:00 is 02:00 the next day.
• Questions exist per language. The structure (type, required, order and the answer options) applies in every language. Translate the question text and the answer labels with translation_set. A question you leave out is removed in every language.
• A GPS location is stored to about seven digits: 51.578721 becomes 51.57872, accurate to about one metre.
• A product, package or location of another licence does not exist for these tools.

A package is set up the same way: combi_create or combi_copy, then combi_set_parts (which products and periods it books), combi_set_extras, combi_set_price_schemas and combi_set_calendar. combi_update switches it on, but only once it has parts.

Multiple locations

If you sell at more than one location, set up a branch per location and link the products that can be booked there. The search-and-book page can then filter by location.

1. franchise_describe shows the existing locations, and how many locations your licence allows.
2. franchise_create creates a location with name and address. Set the name in other languages with translation_set.
3. franchise_set_objects links the products. object_copy can also link a new product to a location straight away.
4. content_block_patch changes the search-and-book page, for example to add a location filter, without sending the whole script again. If the script was changed in the admin in the meantime, the change is refused and the assistant reads it again.

• Your licence determines how many locations you can create. At the maximum a new location is refused; raising the maximum is a change to your licence.
• Existing bookings keep their location. If they should move to the location the product now belongs to, ask for that explicitly.
• The name of a location must be unique. Two locations with the same name cannot be told apart by a visitor.

Furnishing the front end

A front end consists of content blocks, pages that show those blocks, a menu, a theme and a homepage. With the tools this goes in the following order: create and fill blocks (content_block_create, content_block_update), turn them into pages (page_create), fill the menu (menu_set_items), link the menu to the theme (theme_set_menu) and choose the homepage (homepage_set). Finally, page_check_links shows whether any links still lead nowhere.

Along the way a number of things are guarded, so that a mistake does not only show up for the visitor:

• The content of a content block is checked before it is saved, the same way as in the editor. Text that would break the page, such as a stray curly brace or an {if} without {/if}, is refused. Put JavaScript and CSS with curly braces between {literal} and {/literal}.
• The menu in the header is chosen per language, and a language without a menu does not fall back to another language. The plan of theme_set_menu names every active language that has no menu afterwards.
• A menu set up for one language only needs labels in that language. A menu for all languages needs a label in every active language.
• The homepage is one setting for all languages. When a visitor switches language, the front end follows the linked language version of that page. The plan of homepage_set warns about every active language in which the page has no version.
• The link check only looks at links a visitor clicks. JavaScript does not count, even when it contains something like location.href.

Supplying a logo and house style

Do not paste a logo or a complete stylesheet into the conversation with your assistant. That is slow, and one wrong character makes the file unusable. The file goes into the media library of your environment first, and the assistant then refers to it.

1. Supply the file. Ask the assistant for an upload link (media_upload_link). Open the link, choose the file and click Upload. If the logo is already on your own website, the assistant can also fetch it itself (media_fetch).
2. Have it used. The assistant then sets the file as the logo (brand_set_logo or theme_set_logo) or as the stylesheet of the theme (theme_set_css). You do not have to paste anything into the admin.

Example: "Use the logo I am uploading now on our site and in the confirmation e-mail, and make the buttons dark green." The assistant creates an upload link, sets the logo after your upload, and changes only the button colour with theme_patch_css. The rest of the stylesheet is left untouched.

• An upload link works once and is valid for 15 minutes by default. If a file is refused, for example because it is not an image, the link stays usable.
• Allowed: images (png, jpg, gif, webp, svg, ico), stylesheets (css) and fonts (woff, woff2, ttf, otf), up to 5 MB. The file type is determined from the content, not from the name.
• Fetching only works from your licence's own domains: the domains in the setting CORS - Allowed domains.
• These tools need the right menu_config_manage_media (manage media), and the locks above must be open.
• For a small change, theme_patch_css first checks that the stylesheet is still the one the assistant read. If it was changed in the admin in the meantime, the change is refused and the assistant reads it again.

Customer profiles and customer statuses

A user profile gives a group of customers a price of their own: a fixed amount or a percentage discount. A profile also decides which products those customers see in the front end. A customer status records what a customer may do, such as booking or paying by invoice, and can give the customer a profile. For example: regular customers 10% discount, non-profits 25%, and a blacklist that may no longer book.

1. user_profile_create: the profile with the discount. A percentage can apply to the price before or after other discounts, with or without options.
2. user_profile_set_objects: which products the profile applies to.
3. customer_status_create: the customer status, with what the customer may do and the profile the status assigns. customer_status_describe shows the existing statuses.

Along the way a number of things are guarded:

• A profile without linked products applies to all products. Link products to it and customers with that profile see only those products. The plan of user_profile_set_objects warns in both cases.
• A customer only gets the profile of their status at the next status change. If they have no login yet but do have an e-mail address, they get a login without a password at that moment. The plan says so.
• Changing an existing customer status (customer_status_update) has level 2: it is not run on a production environment. May book and may pay by invoice change at once for every customer already in that status. A new status affects nobody yet.
• If a customer status is still on the system default, the first change makes a copy of its own for your licence, just like the screen does.
• The name of a customer status is set in the current language. Other languages are filled with translation_set.

The profiles need the right menu_object_userprofile, the customer statuses menu_config_status_customer.

Adding a language

Switching a front-end language on copies nothing. Everything that has no text in that language yet stays empty in the front end: product names, options, statuses, field labels, content blocks, the menu and the pages. Almost nothing falls back to the default language. The language tools turn that manual work into one structured job:

1. language_activate_plan shows how many texts are still empty per part. Only after approval does language_activate_apply switch the language on.
2. language_missing_report gives the work queue: per part, which texts are missing, with the source text included.
3. The agent translates and translation_set_plan shows per text what would change. translation_set_apply stores it.

Three things are always guarded. A text that is already filled is not overwritten unless that is explicitly asked for. Codes such as {NAME} or ##OWNER_ID## and the HTML markup of a text must come back exactly the same after translating. And a text may not be longer than its field allows. A content page in a new language needs its own url; it is not taken over from the original page.

E-mail and pdf templates are not covered here: those are separate documents per language, made with the template tools.

All these tools need the right menu_config_language, plus the right of the screen where the text is normally edited. Someone who may not change the products cannot translate them through AI either.

You ask for the exact, always current list with all input fields using the standard MCP method tools/list on the door itself. What you get back depends on your rights, so a shorter list than this usually means a right is missing.

Which rights each tool needs is described right by right on AI configuration tool rights.