# Herramientas

> Cada herramienta de lectura y de escritura del servidor MCP de OpenWAF, el rol que necesita y la ruta REST que llama.

El servidor MCP de OpenWAF tiene 21 herramientas de lectura y 23 de escritura. Cada una llama a una ruta de la API de OpenWAF con tu credencial, así que puede hacer exactamente lo que esa credencial puede hacer en la API, nada más.

Las zonas se nombran por dominio (`example.com`) o por id; los registros y las reglas, por el id que devuelven `list_records` y `list_rules`. Cada resultado trae un resumen corto en texto y los datos completos como JSON (`structuredContent`, con la misma forma que la respuesta REST).

## Herramientas de lectura

Todos los roles, también `readonly`. En las rutas, `…` es `/v1/orgs/{org}/zones/{zone}` o la ruta de la organización.

| Herramienta | Qué hace | Ruta REST |
|---|---|---|
| `list_zones` | Zonas visibles: estado, modo DNS, servidores de nombres o destino CNAME, cliente, versión | `GET …/zones` |
| `get_zone` | Zona, versión actual, estado de la delegación o de la verificación TXT, y ajustes de borde | `GET …/zones/{z}, …/delegation, …/edge` |
| `list_records` | Registros DNS con sus ids | `GET …/records` |
| `list_rules` | Reglas de borde (IP, país, excepciones del WAF, límites) | `GET …/rules` |
| `list_certificates` | Certificados y estado TLS de cada sitio | `GET …/certs` |
| `zone_history` | Versiones de configuración (también de una zona borrada, por id) | `GET …/versions` |
| `zone_diff` | Diferencias entre dos versiones (por defecto, la actual contra la anterior) | `GET …/diff` |
| `zone_propagation` | Versión aplicada por cada nodo del borde | `GET …/propagation` |
| `zone_hosts` | Zonas externas: si cada nombre con proxy apunta al borde | `GET …/hosts` |
| `email_check` | Correo de la zona en el DNS público: MX, SPF (búsquedas anidadas), DKIM, DMARC, nombres con proxy, conflictos | `GET …/email/check` |
| `audit_log` | Registro de auditoría (`admin`, o `tech` limitado a un cliente) | `GET …/audit` |
| `zone_usage` | Tráfico diario: peticiones, bloqueadas, bytes, consultas DNS | `GET …/usage` |
| `rum_report` | Core Web Vitals de los visitantes: p75 con su valoración, reparto por bandas, periodo anterior, partes del LCP, desglose y peores elementos | `GET …/rum/report` |
| `ai_agents_report` | Agentes de IA de la zona, por vista: overview, crawlers, spoofers, optimization, signals, traps, bursts, endpoints, mcp o events | `GET …/ai-agents/*` |
| `ai_agents_catalog` | Catálogo de bots de IA: operador, categoría, métodos de verificación, versión y estado de cada fuente | `GET …/ai-agents/catalog` |
| `list_clients` | Clientes de la agencia y número de zonas | `GET …/clients` |
| `effective_config` | La configuración ya fusionada que recibe el borde para un nombre | `GET …/hosts/{host}/effective` |
| `list_origin_certs` | Certificados emitidos por la OpenWAF Origin CA: nombres, tipo de clave, serial, caducidad y estado (nunca claves) | `GET …/origin-certs` |
| `origin_tls_status` | TLS hacia el origen de cada nombre con proxy: modo, nombre verificado, mTLS, lo que ve el control plane y errores 525/526 en 24 h | `GET …/origin-tls/status` |
| `egress_status` | Egress de IA de la organización: si está activado, destinos con la huella de su credencial, y agentes | `GET …/egress, …/egress/targets, …/egress/agents` |
| `egress_events` | Llamadas de tus propios agentes que rechazó la pasarela de egress | `GET …/egress/events` |

## Herramientas de escritura

Rol `tech` o superior; las de egress necesitan `admin`. Una credencial `readonly` ni siquiera las ve en `tools/list`.

| Herramienta | Qué hace | Rol | Ruta REST |
|---|---|---|---|
| `add_zone` | Alta de una zona, modo `delegated` o `external` | `tech` | `POST …/zones` |
| `create_record` | Crea un registro DNS | `tech` | `POST …/records` |
| `update_record` | Cambia campos de un registro | `tech` | `PATCH …/records/{id}` |
| `delete_record` | **Destructiva**: borra un registro | `tech` | `DELETE …/records/{id}` |
| `apply_records_batch` | Altas, cambios y bajas de registros en una sola versión (**destructiva** si borra) | `tech` | `POST …/records/batch` |
| `update_settings` | Ajustes de borde (modo y nivel del WAF, límite, origen, HSTS, puerta de acceso, redirecciones, caché, 103 Early Hints, RUM, `rate_rules` por ruta…); con `host`, los ajustes propios de ese nombre | `tech` | `PATCH …/edge` |
| `ai_agents_settings` | Lee los ajustes `ai_agents` de la zona o de un nombre; con `patch` o `template`, los cambia | `tech` | `GET/PATCH …/edge` |
| `agent_readiness_scan` | Escanea ahora la preparación de un nombre para agentes de IA (una vez por nombre y minuto); no cambia configuración | `tech` | `POST …/agent-readiness/scan` |
| `add_rule` | Añade una regla de borde; `hosts` la limita a esos nombres | `tech` | `POST …/rules` |
| `remove_rule` | **Destructiva**: quita una regla | `tech` | `DELETE …/rules/{id}` |
| `revert_zone` | **Destructiva**: restaura una versión anterior como versión nueva | `tech` | `POST …/revert` |
| `check_zone` | Comprueba ya la delegación o el TXT de verificación (sin motivo ni confirmación) | `tech` | `POST …/delegation/check` |
| `delete_zone` | **Destructiva**: borra la zona | `tech` | `DELETE …/zones/{z}` |
| `purge_cache` | Purga la caché del borde: exactamente uno de `purge_everything`, `files`, `prefixes`, `hosts` o `tags` | `tech` | `POST …/cache/purge` |
| `create_origin_cert` | Emite un certificado de la OpenWAF Origin CA para nombres de la zona; la clave generada va solo en esa respuesta, o envía un `csr` | `tech` | `POST …/origin-certs` |
| `revoke_origin_cert` | **Destructiva**: revoca un certificado de origen | `tech` | `DELETE …/origin-certs/{id}` |
| `egress_create_agent` | Crea un agente de egress; devuelve su token sustituto **una sola vez** | `admin` | `POST …/egress/agents` |
| `egress_update_agent` | Cambia descripción, destinos, inspección o `disabled` de un agente | `admin` | `PATCH …/egress/agents/{id}` |
| `egress_rotate_token` | **Destructiva**: token nuevo (una sola vez); el anterior deja de valer | `admin` | `POST …/egress/agents/{id}/rotate-token` |
| `egress_delete_agent` | **Destructiva**: borra un agente | `admin` | `DELETE …/egress/agents/{id}` |
| `egress_add_target` | Destino propio `https://` con nombre DNS público | `admin` | `POST …/egress/targets` |
| `egress_remove_target` | **Destructiva**: borra un destino propio y su credencial (no si un agente lo usa) | `admin` | `DELETE …/egress/targets/{t}` |
| `egress_remove_credential` | **Destructiva**: borra la clave del proveedor de un destino | `admin` | `DELETE …/egress/targets/{t}/credential` |

Las destructivas lo dicen en su descripción y llevan la anotación `destructiveHint`; las de lectura, `readOnlyHint`.

> **Nota: Las claves de proveedor nunca pasan por MCP**
>
> `egress_remove_credential` puede borrar la clave de un destino, pero ponerla no es posible por MCP porque pasaría por la conversación: se pone en el panel o con `PUT …/credential`. Mira [destinos y claves de proveedor](https://developers.openwaf.dev/es/egress/cloud/targets-and-keys/).


## Escrituras de configuración y el resto

Las escrituras que cambian la configuración de la zona crean una versión nueva y siguen el protocolo simular → confirmar con `expected_version` que se explica en [hacer cambios](https://developers.openwaf.dev/es/mcp/making-changes/). Unas pocas herramientas no son configuración versionada y van de otra forma:

- `check_zone` y `agent_readiness_scan` no cambian configuración: sin motivo ni confirmación.
- `add_zone` no tiene versión previa: se confirma sin `expected_version`.
- `purge_cache`, `create_origin_cert`, `revoke_origin_cert` y las de egress: `confirm=false` comprueba y enseña qué pasaría, `confirm=true` lo hace, sin `expected_version`. Quedan en la auditoría.

## Perfil ligero

La lista completa de herramientas le cuesta contexto al asistente en cada conversación. Con `?profile=lite` el servidor solo lista las herramientas de descubrimiento, un modo código de solo lectura y las lecturas de cada día, y todas las demás se siguen pudiendo llamar por su nombre. Mira [OAuth y tokens](https://developers.openwaf.dev/es/mcp/oauth-and-tokens/#lite-profile).