Un asistente nunca cambia tu configuración en un solo paso. Cada escritura de configuración se simula primero, ves el diff, y solo una segunda llamada con la versión que viste la aplica. Si otra persona cambió la zona entretanto, no se aplica nada.
Los argumentos de cada escritura
| Argumento | Qué es |
|---|---|
zone | La zona, por dominio o por id |
reason | Obligatorio, de 1 a 500 caracteres. Queda en la versión y en la auditoría |
confirm | false por defecto: simular. true: aplicar |
expected_version | La versión de la zona que devolvió la simulación. Obligatorio con confirm: true |
Simular, revisar, confirmar
- Simular. Con
confirmfalso (el valor por defecto) la herramienta ejecuta la escritura como prueba y no aplica nada. Devuelveapplied: false,current_version(la versión actual de la zona),new_version, el plan completo (plan: diferencias y avisos) y qué llamar después. Si ya pasasexpected_version, también se comprueba. - Enseñar el diff. El asistente tiene que enseñarte el plan antes de confirmar; las instrucciones del servidor y la descripción de cada herramienta se lo indican. Lee el diff: es exactamente lo que va a cambiar.
- Confirmar con la versión. Con
confirm: truela herramienta exigeexpected_version(sin ella, errorexpected_version_required) y se la envía a la API comoIf-Match. Si va bien:applied: true,version(la nueva) yresult(la respuesta REST).
Conflictos de versión
Si la zona cambió después de la simulación, no se aplica nada: la herramienta responde version_conflict (HTTP 412) con la current_version, y el texto pide volver a simular y revisar el plan nuevo.
{"error":{"code":"version_conflict","message":"the configuration changed: the current version is 2"},"current_version":2,"status":412}Ejemplo
Tú: añade www apuntando a 192.0.2.10 en example.com
El asistente llama a
create_recordcon{"zone":"example.com","type":"A","name":"www","content":"192.0.2.10","reason":"alta de www desde MCP"}y recibe:Simulation only: nothing was applied. The zone is at version 1; applying creates version 2: 1 change: add "records[id=…]": {"content":"192.0.2.10",…,"name":"www.example.com",…,"type":"A"} To apply, call create_record again with the same arguments, confirm=true and expected_version=1.Te enseña el cambio y tú confirmas.
Llama otra vez con
"confirm": true, "expected_version": 1y recibeApplied: the zone is now at version 2.Una segunda escritura con
expected_version: 1falla conversion_conflict (HTTP 412): the configuration changed: the current version is 2y la indicación de volver a simular.
Excepciones
add_zoneno tiene versión previa: se confirma sinexpected_version.revert_zonesimula contra la versión actual si no se daexpected_version.check_zoneyagent_readiness_scanno cambian configuración: sin motivo ni confirmación.purge_cache,create_origin_cert,revoke_origin_certy las de egress no son configuración versionada:confirm=falsecomprueba,confirm=trueactúa, sinexpected_version.
Errores
Un fallo es un resultado con isError: true cuyo structuredContent es el sobre de error de la API más el estado HTTP, con los mismos códigos y mensajes que la API: invalid (con field), reason_required, forbidden, not_found (también para zonas de otra organización o fuera del ámbito del token), zone_exists, missing_certs, org_suspended, unavailable, etc. Los argumentos que no cumplen el esquema, como un tipo de registro desconocido o un motivo vacío, se rechazan antes de llamar a la API.
Auditoría e historial
Los cambios hechos por MCP se auditan como los de la API: actor token:<id> y, en los datos de la entrada, "channel": "mcp" además de reason, version y from_version. El historial de versiones de la zona muestra el mismo actor y motivo. El propio asistente puede leerlos con audit_log, zone_history y zone_diff.
Deshacer un cambio
revert_zone restaura la configuración de una versión anterior (registros, ajustes de borde y reglas) como una versión nueva; es destructiva porque deshace los cambios hechos después de esa versión. Sigue el mismo protocolo simular → confirmar, así que ves el diff antes de que se restaure nada.