Configuration

Configuration

All plugin settings live on Agent Hub > Settings and are stored per site. Only users with manage_xnetvn_agent_hub_wp — administrators by default — can change them; key owners still create their own keys on their profile (docs/user-guide.md, src/Auth/Capabilities.php).

The screen is organised into six groups. The option keys below are the real stored names in the non-autoloaded xnetvn_agent_hub_wp_settings array, and the defaults match WpSiteSettings::DEFAULTS (docs/en/ENVIRONMENT.md, src/Persistence/WpSiteSettings.php).

Access

Decides who may call the endpoint and the highest risk any key may request.

Option key	Default	Effect
enabled	true	Turns the MCP server off without deleting keys or settings — useful for maintenance or incident response.
allowed_roles_override	null	null means the default WordPress roles apply. An array is used only when the custom role list control is switched on; an empty list denies every role.
tier_ceiling	"destructive"	Highest tier any key on the site may request: read, write, destructive or admin. Existing higher-tier keys stop working when you lower it.
allow_admin_tier	false	Lets a key request the admin tier at creation. WordPress permissions still apply.
exposed_third_party_abilities	[]	Explicit pack/ability names, for example content/read-post; unknown names are rejected on save.
disable_adapter_default_server	false	Stops the MCP Adapter from registering its own default server; this plugin's endpoint keeps working.

admin is off by default and the ceiling defaults to destructive. Raising either widens the site's risk; lowering them is immediate (docs/en/architecture/overview.md).

Network

Option key	Default	Effect
allowed_origins	[]	Additional browser origins, one per line. Empty allows only this site; non-browser clients that send no Origin are unaffected.
site_ip_allowlist	[]	CIDR ranges allowed to reach the endpoint. Empty allows every address.
trusted_proxy_headers	[]	Only X-Forwarded-Proto is accepted, and only from a trusted proxy network.
trusted_proxy_cidrs	[]	Networks whose proxy headers are believed.
fallback_header_enabled	true	Accepts X-XNETVN-API-KEY when Authorization is missing. Turn it off if you do not need a second way to send the key.

Trusting a proxy header without a matching CIDR lets a client forge its address; the settings screen warns about this inline (src/Admin/Pages.php).

Limits

Option key	Default	Effect
max_keys_per_user	10	Refuses one more active key beyond this number.
max_key_lifetime_days	365	Longest expiry a key may request.
rate_limit_key_per_min	120	Requests one key may send per minute.
rate_limit_auth_fail_per_min_ip	10	Failed authentication attempts one address may make per minute before throttling.
output_max_bytes	262144	Largest tool response before truncation (256 KB).

Exceeding a per-minute budget returns 429 with a Retry-After header (src/Auth/Authenticator.php). These are deliberate budgets, not measured production capacity (docs/en/ENVIRONMENT.md).

Audit and data

Option key	Default	Effect
audit_retention_days	90	Days activity rows are kept before the daily cleanup removes them.
anonymize_ip	false	Stores only the IPv4 /24 or IPv6 /48 network in audit rows and key metadata.
delete_data_on_uninstall	true	Removes keys, activity and settings when the plugin is deleted. Turn it off before uninstalling if you must keep the data.

The cleanup runs as a daily scheduled event and works in bounded batches, rescheduling a continuation when a batch fills (src/Audit/Retention.php).

Notifications

notify_key_created, notify_key_revoked, notify_key_expiring and notify_unusual_ip all default to true and send WordPress mail to the key owner. Each owner can switch all key email off on their own profile; that preference applies across the site (docs/user-guide.md).

Media

Option key	Default	Effect
media_remote_fetch_enabled	false	Allows upload-media-from-url to fetch a public HTTPS file. When off, the ability returns a "remote fetch disabled" error and makes no request.
media_remote_max_bytes	10485760	Largest remote file (10 MB).
media_remote_timeout_seconds	15	Time before a remote request is abandoned.
media_remote_max_redirects	3	Redirects followed per download.
media_data_max_bytes	1048576	Largest inline upload (1 MB).
media_pixels_max	40000000	Largest image in pixels (40 MP).
media_mime_denylist	[]	Extra refused MIME types, one per line, in addition to the built-in list.

Allowed numeric ranges are enforced server-side: remote bytes 1024..67108864, inline bytes 1024..8388608, timeout 3..30 seconds, redirects 0..5, pixels 1000000..100000000. Other integer settings accept 1..4194304 (docs/en/ENVIRONMENT.md, src/Persistence/WpSiteSettings.php).

Secrets and credentials

The plugin stores no plaintext key. Each key is xnv_<key_id>_<secret>, shown once, and verified with hash_hmac('sha256', $secret, $pepper) against a 32-byte random pepper stored in the xnetvn_agent_hub_wp_pepper option with autoload disabled (docs/en/ENVIRONMENT.md, src/Auth/KeyHasher.php). Deleting or replacing the pepper invalidates every existing key, so treat it as part of your backup set (docs/en/guides/operation-guide.md).

To inspect the stored settings from the server:

wp option get xnetvn_agent_hub_wp_settings --format=json

The value is a PHP array in the options table, not a JSON document; WP-CLI renders it for reading only (docs/en/ENVIRONMENT.md).

Development-only constant

XNETVN_AGENT_HUB_WP_ALLOW_INSECURE permits HTTP, but only when the WordPress environment type is local or development. It never applies to a staging or production environment (src/Http/TransportGuard.php).

If a save fails

Settings are validated on the server. A rejected field produces "Settings were not saved. Check the field types, roles, origins and CIDR ranges" and the previous values stay in place — fix the named field and save again (src/Admin/Pages.php, docs/user-guide.md).

For step-by-step tasks such as creating keys, rotating them or enabling remote media, use the user guide rather than duplicating it here: https://github.com/xnetvn-com/xnetvn-agent-hub-wp/blob/main/docs/user-guide.md. See also Quick-Start and Compatibility.