Understanding the Universal Audit Log

Where to find the Audit Log

In wp-admin, go to Royal MCP Pro → Audit Log. The page is capability-gated to manage_options, so only administrators can view it. Editors and lower-cap roles won't see the menu item.

If you're on a multi-admin site and you want the audit log restricted to specific administrators, gate it further via a custom capability or a plugin like Members / User Role Editor — the underlying page always defers to the current user's cap check.

What gets logged

Every request that hits the Royal MCP endpoint with an MCP tools/call method gets recorded. That includes:

• Free-tier tool calls (e.g. wp_get_posts, wp_update_post) — yes, the audit log is universal across Free and Pro tools.
• Pro-tier tool calls (e.g. divi_clone_page, wc_bulk_price_update) — these are the ones the log was designed around, and the ones that can also produce an undo token.
• Tool calls that were rejected because the license was expired or the caller lacked permission — these are logged with the appropriate status so you can see attempted calls, not just successful ones. See the status values below.
• Tool calls from every MCP client — Claude Desktop, ChatGPT, Cursor, custom SDK calls, direct REST posts. The client's name and version are captured when the request includes them.

Anatomy of an audit row

Each row stores 18 pieces of information. The list view surfaces the most useful ones as columns; the rest are visible when you expand a row or in the CSV export. Grouped by purpose:

Identity — who called what and when

• id — unique row identifier
• created_at — UTC timestamp of the request
• tool_name — e.g. divi_clone_page, wp_update_post
• user_id — the WordPress user the request was authenticated as
• auth_method — how the caller authenticated (OAuth, application password, API key, etc.)
• session_id — conversation / session identifier when the client sends one; groups related calls together
• client_meta_json — the MCP client name + version if the client identified itself in the request
• route — the REST route the call came in on

Input — what was requested

• args_hash — SHA256 of the request arguments; useful for detecting exact duplicates without inspecting content
• args_json — the full arguments as JSON. Sensitive keys are scrubbed before storage (see Value scrubbing)

Outcome — what happened

• response_status — one of the enum values documented in the next section
• response_summary — the first 250 characters of the response text, value-scrubbed
• affected_object_type — e.g. post, product, widget when the tool acted on one specific WordPress object
• affected_object_id — that object's ID

Reversibility — can this be undone?

• undo_token — 64-character hex token if the tool issued one; NULL if the operation isn't reversible
• undo_expires_at — when the token stops being redeemable
• undone_at — when the undo was actually executed (NULL if the operation still hasn't been undone)

For the full mechanics of undo tokens (which tools issue them, TTL rules, how to redeem), see Undo Token Errors.

Housekeeping

• user_deleted_at — timestamp populated when the row was tombstoned as part of a GDPR user-erasure request

The response_status values

Every row lands in one of six status buckets. These are the values you'll see in the Status column and the values available in the Status filter dropdown.

Filtering the audit log

The filter panel above the row list narrows results by any combination of these fields:

Quick-range presets

Under the filter form, four preset buttons snap the date range to common windows: Last 24h, Last 7 days, Last 30 days, and Clear dates. Use them as the fast path to "what happened today" or "what happened this week" without touching the date pickers.

The per-row Undo action

Rows that produced an undo token show an Undo link in the Actions column — but only while the token is still redeemable. The link shows when all three conditions hold:

1. The row has an undo_token stored
2. The token hasn't been consumed yet (undone_at is empty)
3. The token hasn't expired (current time is before undo_expires_at)

Once you're one condition short, the Undo link disappears from the Actions column. Rows that already got undone show status undone; rows whose window elapsed remain in their original status but no longer offer the action.

Clicking Undo

Clicking the link shows a browser confirmation prompt (Undo this operation? This uses the stored undo token and cannot be re-run.). Confirm, and the plugin redeems the stored undo payload against the same tool that created it. The Audit Log page then shows one of three notices:

• Operation undone. — success. The row's status becomes undone and its Undo link goes away.
• Undo failed. See details in the audit row. — the undo attempt ran into an error (usually because the target object has been modified further since the reversible payload was recorded). Read the row's response summary for details.
• This row has no active undo token. — the token was consumed or expired between the moment the link was rendered and the moment you clicked. Rare, but possible if two administrators are looking at the same page.

CSV export

The Export CSV (filtered rows) button on the Audit Log page downloads a spreadsheet of the currently-filtered rows. Details:

• Filename: royal-mcp-pro-audit-YYYYMMDD-HHMMSS.csv using your server's local time.
• Row cap: up to 5,000 rows per export. If your filter matches more than that, narrow it (tighter date range or add a tool-name filter) and export in slices.
• Content: every column in the underlying table — id, created_at, tool_name, user_id, auth_method, response_status, session_id, route, affected_object_type, affected_object_id, undo_token, undo_expires_at, undone_at, response_summary, client_meta_json, args_hash, and args_json.
• Filters carry over: whatever tool / user / status / date filters are active when you click Export are applied to the row set.
• Formula-injection defense: any cell value that starts with =, +, -, or @ gets a leading single-quote so spreadsheet apps treat it as text and don't try to execute a formula. Safe to open the export in Excel, Numbers, or Google Sheets.

Value scrubbing (before storage)

Both request arguments and response summaries pass through a scrubber before being written to the audit table. This protects credentials and PII from ending up in a long-lived log even if the tool happened to receive or return them.

Arguments (args_json)

The args scrubber looks for keys whose name matches a sensitive pattern and replaces the value with a redaction marker. Sensitive key patterns include: password, passwd, token, secret, api_key, apikey, access_key, authorization, bearer, session, cookie, signature, private_key, passphrase, mnemonic, seed_phrase, email, phone, ssn, credit_card, cvv, pin, address, and case-insensitive variants of each (dashes and hyphens equivalent to underscores).

Redacted scalar values become [redacted:sha256:<16-char-hash>]. Redacted arrays become [redacted:array:<count>]. You can still see that a field was present (and how big it was) without seeing the contents.

Response summary (response_summary)

Response text is truncated to 250 characters, then passed through four regex patterns that redact anything looking like:

• JWT tokens (three base64url segments separated by dots)
• Auth-preamble + long value (e.g. bearer abc123..., token xyz...) — matches bearer, token, api-key, apikey, secret, password, authorization, auth followed by a 16+ character value
• Email addresses
• Long hex strings (24+ hex characters — catches session IDs, API keys, hashes)

Retention & automatic pruning

Rows are pruned automatically after they age out. The default retention is 90 days.

• Filter to change it: royal_mcp_pro_audit_retention_days — return an integer number of days. Any row whose created_at is older than that at the moment the daily prune runs gets deleted.
• Never-prune mode: return 0 (or any value ≤ 0) from the filter and the daily prune bails without deleting anything. Rows accumulate indefinitely — be sure you actually want that before choosing this option, especially on high-traffic sites.
• When the prune runs: once a day via WP-Cron, on the royal_mcp_pro_audit_prune event. If WP-Cron isn't firing on your host (a not-uncommon shared-host issue), old rows won't be deleted until it recovers.

add_filter( 'royal_mcp_pro_audit_retention_days', function() {
    return 365;
} );

The royal_mcp_pro_diagnostics tool

Royal MCP Pro ships one MCP tool designed to be callable even when the license is expired: royal_mcp_pro_diagnostics. It exists so that when something goes wrong — expired license, missing schema, disagreement between what the plugin thinks it has and what's actually registered — you (or your AI) can inspect the state without needing an active license first.

Practically: on an expired license, every other Pro tool returns the "did NOT execute" service message, but this one returns a diagnostic payload. Point Claude at it and ask "run the diagnostics tool" to get a snapshot.

What it returns

The response is a structured payload with these top-level keys:

• pro_version, free_version, wp_version, php_version, site_url
• license — nested block with licensed, sdk_status, sdk_expires_at, sdk_last_check, and sdk_error
• pro_tool_count and pro_tool_slugs — every Pro tool currently registered
• pro_schema_count and pro_schema_slugs — every Pro tool with a valid schema
• handlers_without_schema, schemas_without_handler — drift-detection lists (both should be empty on a healthy install)
• active_profile — which endpoint profile is currently in effect
• endpoint_urls — the base MCP endpoint URL + any legacy aliases
• builders — whether Elementor / Divi / Elementor Pro are active + their versions
• seo_plugin_detected, redirection_active, sitevault_active, forgecache_active — sibling-plugin integration signals

Two optional argument flags extend the payload: include_plugins=true adds a list of every active plugin's basename/name/version, and include_audit_tail=true adds the last five Pro tool calls (id, timestamp, tool name, user ID, response status, response summary snippet). Handy for reporting an issue: run diagnostics with both flags on and you have a complete environmental snapshot to attach to a support ticket.

Common questions

Does the audit log affect performance?

Insertion happens on the same request that made the tool call, so there is a real (small) write cost per call. The write is a single indexed INSERT — well under 10ms on typical setups. Rows are pruned once a day, so the table stays bounded by your retention window.

Can I disable the audit log?

Not from the settings UI — the log is on by design. If you have a specific reason to disable audit capture (extreme write-throughput environment, e.g.), reach out at support@royalplugins.com and describe your workload. The plugin has filter hooks for advanced use cases; we can point you at the right one for your situation.

Do free-tier tool calls really get logged?

Yes. The audit log is a Pro feature, but once you're on Pro every tool call — Free or Pro — is captured. This is what makes it "universal": one place to see everything the AI did, not two separate logs.

Does the log survive plugin deactivation?

Yes. Deactivating the plugin leaves the wp_royal_mcp_pro_audit table in place. Uninstalling the plugin (deleting it entirely) drops the table — if you want to keep the data, export via CSV first.

Do rows include IP addresses?

No. The audit row doesn't record the caller's IP address. It records the WordPress user ID and auth method, which are more useful for accountability inside your team. If IP-level tracking is something you specifically need for compliance, reach out.

What about GDPR user-erasure requests?

The user_deleted_at column is populated when a WordPress user erasure request is processed. Rows for that user are marked but not physically deleted — the user identifier is scrubbed, and the row stays for operational continuity.

Still Stuck? Two-Step Support Path

If the Audit Log isn't showing what you expect — missing rows, wrong statuses, undo actions failing — work through these two steps in order.

Step 1: Confirm the log is capturing new rows

The fastest sanity check:

1. Note the top row's timestamp on the Audit Log page.
2. From your MCP client, run any simple tool (e.g. royal_mcp_connection_health).
3. Reload the Audit Log page. A new row for that tool call should be at the top.

If the new row appears: the log is healthy. Your issue is likely a filter that's excluding what you want to see — clear all filters and try again. If the new row does not appear: the audit capture path may be blocked. Move to Step 2.

Step 2: Email priority support

Email support@royalplugins.com from your purchase email address. Priority email support is included with every Pro license — typical response within 24 hours. Never include your license key in email; we look it up from your purchase address.