Configuration bundle

The configuration bundle is your organisation’s own setup as one YAML document: alert rules, boards, notes, locations, registered devices, placements, tags, lint waivers, MOPs, synthetic checks, escalation levels and integration settings. Keep it in git, review changes to it, or copy a setup into another organisation. It holds no secrets.

Every member can export it and check a file against the organisation. Applying a file needs the engineer role or above. An import is always a dry run unless you apply it.

You can use it two ways:

Where	Export	Import
Dashboard: Configure › Team, the Configuration bundle card	Download YAML	Check a file…, then Apply
Claude	org.export_bundle({ sections? })	org.import_bundle({ yaml, sections?, prune?, apply? })

What is in a bundle?

Twelve sections, written in this order. A section holds only what people set up in SZ-MCP; items that came from NetBox are left out.

Section	Dashboard label	Items are matched by
rules	Alert rules	Rule name
boards	Boards	Board name
notes	Notes	Note target and text
locations	Locations	Location id (location:<slug>/…)
devices	Registered devices	MAC address
placements	Placements	Inventory id
tags	Tags	Inventory id
lintWaivers	Lint waivers	rule@key
mops	MOPs	MOP title
probes	Synthetic checks	Check name
escalations	Escalations	Escalation name
integrations	Integrations	Exported for reference only (see below)

The document starts with kind: sz-mcp-bundle and version: 1, the export time and the organisation’s name, then sections:.

Not in a bundle: the controller login, members and roles, the email contacts, the webhook and Jira settings, the write guard policy, the privacy settings, the scrape token, and every secret.

How do I import a bundle?

1. Open Configure › Team in the organisation you want to change, and click Check a file… in the Configuration bundle card. It accepts .yaml, .yml or .json, up to 3 MB.

2. Read the plan. For each section it shows how many items would be Created, Updated and Deleted, and how many are the Same. Hover over a count to see the item names. Invalid items and skipped items are listed below the table with their reasons.

3. To also delete what the file doesn’t name, turn on Prune (delete what the file doesn’t name). The plan is checked again.

4. Click Apply N changes and confirm. Without prune, the dialog says “Items are created and updated; nothing is deleted.” With prune, it says “Prune is on: what the file’s sections don’t name is deleted here.”

If the organisation already matches the file, the card says “Nothing to change: this organisation already matches the file.” Viewers and operators see the plan, with “An engineer or admin can apply it.” instead of the button.

Through Claude, org.import_bundle returns the same plan. Claude shows you the plan and asks before calling it again with apply: true. In a new organisation, run inventory.sync() first, so the placements and tags that name inventory ids can be resolved.

What does the plan contain?

Per section: create, update (with the fields that change), delete (only with prune), unchanged, and skipped. Skipped items are ones that can’t be applied here, each with a reason. Examples are an entity this organisation’s inventory doesn’t have yet, a missing location, an item that exists here from NetBox, or an integration.

• Prune deletes items the file’s sections don’t name. It is off by default and never touches integrations. Use sections to limit an import, and pruning, to the sections you name.
• A board that is updated keeps its id and its share links. A board deleted by prune loses its share links.
• Escalation addresses that are not organisation members get a confirmation email, and are mailed only once they confirm.

Why are integrations never imported?

A bundle carries no secrets, so SZ-MCP never writes an integration from one. Integrations are exported without their secrets, for reference. On import, each one is listed under skipped when it is:

• missing: “not set up here: an admin adds it on the dashboard (Settings › Integrations) with its secret”;
• different: “differs from the bundle: an admin changes it on the dashboard (a new target needs the secret again)”.

Who can apply which sections?

Action	Role
Export, and check a file (dry run)	Every role
Apply	Engineer, admin or owner
Apply a file that changes escalation levels	Admin or owner

An engineer applying a file that would change escalation levels gets an error on the escalations section, “changing escalation levels needs an admin (your role: engineer); leave the section out with sections: […]”, and nothing is changed. Leave that section out, or ask an admin.

Is an import all or nothing?

Validation is all or nothing; applying is not. Every item in every section is validated first. If any is invalid, nothing changes, and the result says “Some items are invalid (see errors in plans); nothing was changed.”

Once everything is valid, items are applied one by one. An item that fails while being applied is reported under failures, with its section, key and message, and the rest is still applied. The dashboard says “Applied. N item(s) failed; see below.” and lists them. Nothing is rolled back. Check the failed items, fix them, and import again: items already applied show as unchanged.

What are the limits and errors?

Limit	Value	At the limit
Bundle size	3 MB	The card refuses the file: “The file is over 3 MB.” Through Claude, a larger yaml is refused by the call’s argument check
Dashboard exports and imports	10 a minute per organisation	rate_limited: “Up to 10 a minute.”
Escalation levels	10 per organisation	An error on escalations: “at most 10 escalation levels; this would leave N”
Synthetic checks	intervalMinutes 5, 10, 15, 30 or 60; maxAps 1 to 5	An error on the item

Error	Message
invalid_yaml	The YAML parser’s message
invalid_bundle	kind must be sz-mcp-bundle (got …)., sections must be a mapping of section name to its items., or “Some items are invalid (see errors in plans); nothing was changed.”
unsupported_version	This server reads bundle version 1; the document is version …
write_blocked	Your role in this organisation (…) can't import a bundle; an engineer or admin can. A dry run (no apply) works for every role.

Sections in the file that SZ-MCP doesn’t know are ignored and listed under ignoredSections. A name in the sections argument that isn’t one of the twelve is refused by the call’s argument check.

The write_blocked message comes back through Claude; on the card, viewers and operators get no Apply button.

Next steps

Teams and roles Who can export, check and apply a bundle.

Privacy controls Settings the bundle doesn't carry: retention and pseudonymising.

Alert rules The rules section, and managing rules on their own as YAML.

Boards What a board holds, and the share links an update keeps.