# Tools

> Every read and write tool of the OpenWAF MCP server, the role it needs and the REST route behind it.

The OpenWAF MCP server has 21 read tools and 23 write tools. Each one calls an OpenWAF API route with your credential, so it can do exactly what that credential can do through the API, nothing more.

Zones are named by domain (`example.com`) or by id; records and rules by the id that `list_records` and `list_rules` return. Every result comes as a short text summary plus the full data as JSON (`structuredContent`, with the same shape as the REST response).

## Read tools

Every role, `readonly` included. In the routes, `…` stands for `/v1/orgs/{org}/zones/{zone}` or the organization's path.

| Tool | What it does | REST route |
|---|---|---|
| `list_zones` | Visible zones: status, DNS mode, name servers or CNAME target, client, version | `GET …/zones` |
| `get_zone` | Zone, current version, delegation or TXT verification status, and edge settings | `GET …/zones/{z}, …/delegation, …/edge` |
| `list_records` | DNS records with their ids | `GET …/records` |
| `list_rules` | Edge rules (IP, country, WAF exceptions, rate limits) | `GET …/rules` |
| `list_certificates` | Certificates and TLS status of each site | `GET …/certs` |
| `zone_history` | Configuration versions (also of a deleted zone, by id) | `GET …/versions` |
| `zone_diff` | Differences between two versions (by default, the current one against the previous one) | `GET …/diff` |
| `zone_propagation` | Version applied by each edge node | `GET …/propagation` |
| `zone_hosts` | External zones: whether each proxied name points at the edge | `GET …/hosts` |
| `email_check` | The zone's mail in the public DNS: MX, SPF (nested lookups), DKIM, DMARC, proxied names, conflicts | `GET …/email/check` |
| `audit_log` | Audit log (`admin`, or `tech` limited to a client) | `GET …/audit` |
| `zone_usage` | Daily traffic: requests, blocked requests, bytes, DNS queries | `GET …/usage` |
| `rum_report` | Real-user Core Web Vitals: p75 with its rating, band split, previous period, LCP parts, breakdown and worst elements | `GET …/rum/report` |
| `ai_agents_report` | AI agents on the zone, by view: overview, crawlers, spoofers, optimization, signals, traps, bursts, endpoints, mcp or events | `GET …/ai-agents/*` |
| `ai_agents_catalog` | AI bot catalog: operator, category, verification methods, version and state of each source | `GET …/ai-agents/catalog` |
| `list_clients` | The agency's clients and their number of zones | `GET …/clients` |
| `effective_config` | The merged configuration the edge receives for one name | `GET …/hosts/{host}/effective` |
| `list_origin_certs` | Certificates issued by the OpenWAF Origin CA: names, key type, serial, expiry and status (never keys) | `GET …/origin-certs` |
| `origin_tls_status` | TLS to the origin of each proxied name: mode, verified name, mTLS, what the control plane sees, and 525/526 errors in 24 h | `GET …/origin-tls/status` |
| `egress_status` | The organization's AI egress: whether it is on, targets with their credential fingerprint, and agents | `GET …/egress, …/egress/targets, …/egress/agents` |
| `egress_events` | Calls from your own agents that the egress gateway rejected | `GET …/egress/events` |

## Write tools

Role `tech` or higher; the egress tools need `admin`. A `readonly` credential does not see these in `tools/list` at all.

| Tool | What it does | Role | REST route |
|---|---|---|---|
| `add_zone` | Add a zone, mode `delegated` or `external` | `tech` | `POST …/zones` |
| `create_record` | Create a DNS record | `tech` | `POST …/records` |
| `update_record` | Change fields of a record | `tech` | `PATCH …/records/{id}` |
| `delete_record` | **Destructive**: delete a record | `tech` | `DELETE …/records/{id}` |
| `apply_records_batch` | Create, change and delete records in one version (**destructive** when it deletes) | `tech` | `POST …/records/batch` |
| `update_settings` | Edge settings (WAF mode and level, rate limit, origin, HSTS, access gate, redirects, cache, 103 Early Hints, RUM, per-path `rate_rules`…); with `host`, that name's own settings | `tech` | `PATCH …/edge` |
| `ai_agents_settings` | Read the `ai_agents` settings of the zone or a name; with `patch` or `template`, change them | `tech` | `GET/PATCH …/edge` |
| `agent_readiness_scan` | Scan now how ready a name is for AI agents (once per name per minute); changes no configuration | `tech` | `POST …/agent-readiness/scan` |
| `add_rule` | Add an edge rule; `hosts` limits it to those names | `tech` | `POST …/rules` |
| `remove_rule` | **Destructive**: remove a rule | `tech` | `DELETE …/rules/{id}` |
| `revert_zone` | **Destructive**: restore an earlier version as a new version | `tech` | `POST …/revert` |
| `check_zone` | Check the delegation or the verification TXT now (no reason or confirmation) | `tech` | `POST …/delegation/check` |
| `delete_zone` | **Destructive**: delete the zone | `tech` | `DELETE …/zones/{z}` |
| `purge_cache` | Purge the edge cache: exactly one of `purge_everything`, `files`, `prefixes`, `hosts` or `tags` | `tech` | `POST …/cache/purge` |
| `create_origin_cert` | Issue an OpenWAF Origin CA certificate for names of the zone; a generated key is returned only in that response, or send a `csr` | `tech` | `POST …/origin-certs` |
| `revoke_origin_cert` | **Destructive**: revoke an origin certificate | `tech` | `DELETE …/origin-certs/{id}` |
| `egress_create_agent` | Create an egress agent; returns its placeholder token **once** | `admin` | `POST …/egress/agents` |
| `egress_update_agent` | Change an agent's description, targets, inspection or `disabled` | `admin` | `PATCH …/egress/agents/{id}` |
| `egress_rotate_token` | **Destructive**: new token (shown once); the old one stops working | `admin` | `POST …/egress/agents/{id}/rotate-token` |
| `egress_delete_agent` | **Destructive**: delete an agent | `admin` | `DELETE …/egress/agents/{id}` |
| `egress_add_target` | Add your own `https://` target with a public DNS name | `admin` | `POST …/egress/targets` |
| `egress_remove_target` | **Destructive**: delete your own target and its credential (not while an agent uses it) | `admin` | `DELETE …/egress/targets/{t}` |
| `egress_remove_credential` | **Destructive**: delete a target's provider key | `admin` | `DELETE …/egress/targets/{t}/credential` |

Destructive tools say so in their description and carry the `destructiveHint` annotation; read tools carry `readOnlyHint`.

> **Note: Provider keys never go through MCP**
>
> `egress_remove_credential` can delete a target's key, but setting one is not possible over MCP because it would pass through the conversation: set it in the dashboard or with `PUT …/credential`. See [targets and provider keys](https://developers.openwaf.dev/egress/cloud/targets-and-keys/).


## Configuration writes and the rest

Writes that change the zone's configuration create a new version and follow the simulate → confirm protocol with `expected_version`, described in [making changes](https://developers.openwaf.dev/mcp/making-changes/). A few tools are not versioned configuration and work differently:

- `check_zone` and `agent_readiness_scan` change no configuration: no reason, no confirmation.
- `add_zone` has no previous version: it is confirmed without `expected_version`.
- `purge_cache`, `create_origin_cert`, `revoke_origin_cert` and the egress tools: `confirm=false` checks and shows what would happen, `confirm=true` does it, without `expected_version`. They stay in the audit log.

## Lite profile

The full tool list costs the assistant context in every conversation. With `?profile=lite` the server lists only discovery tools, a read-only code mode and the everyday reads, and every other tool is still callable by name. See [OAuth and tokens](https://developers.openwaf.dev/mcp/oauth-and-tokens/#lite-profile).