Appearance
Privileged Tools in Easy MCP AI
Privileged tools give an AI client powers beyond normal content editing: rewriting text across your whole database, or reading the source files of your themes and plugins. They are switched off on every site until an administrator turns them on. This guide explains what they do, how to switch one on, and which users and connections can reach it.
In this article
What Privileged Tools Are
A privileged tool does something an ordinary WordPress screen does not let an editor do, so Easy MCP AI keeps it behind extra checks. Two privileged tools are available:
| Tool | What it does | Guide |
|---|---|---|
wp_privileged_search_replace_run | Finds a piece of text everywhere in your database and replaces it, for example an old domain after a site move. It writes to the database | Search and Replace Across the Database |
wp_privileged_files_read_query | Reads, lists, searches and outlines the files of your themes and plugins, so the AI can answer questions like "which template renders my home page". It writes nothing | Read Theme and Plugin Files with AI |
Every privileged tool shares the same rules:
- It is off until an administrator switches it on.
- It is only available to WordPress users with the required capability.
- It only runs while the Audit log and Change history are both switched on, so every call leaves a record.
- Its tool description tells the AI client that it is privileged, so the client knows what it holds.
Switch a Privileged Tool On
- In WordPress, go to Easy MCP AI > Settings.
- Scroll to the Advanced card and find Disabled tools. Every privileged tool is listed there and is checked, which means it is switched off.
- Clear the checkbox next to the tool you want to use, for example
wp_privileged_files_read_query. - Click Save changes.
- Refresh the tool list in your AI client so it loads the new tool. See Enabled Tools Not Showing in Your AI Client for the steps in each client.
To switch the tool off again, check its box and save.
💡 Tip: On sites you manage from code, you can switch a privileged tool on in wp-config.php instead, and lock it so it cannot be changed from the admin screens. See Switch Tools On or Off from wp-config.php.
Who Can Use Them
A privileged tool runs as the WordPress user behind the connection, like every other tool. On top of that, the user needs a specific capability:
| Tool | Single site | Multisite network |
|---|---|---|
wp_privileged_search_replace_run | An administrator (the manage_options capability) | A site administrator can replace text in their own site's tables. Replacing in every site's tables or the network tables needs a super admin |
wp_privileged_files_read_query | An administrator (the manage_options capability) | A super admin only, because theme and plugin files are shared by every site in the network |
A user without the capability does not see the tool in their AI client, and a direct call is refused.
📝 Info: Reading files is not blocked by the DISALLOW_FILE_EDIT setting in wp-config.php. That setting removes WordPress's built-in theme and plugin editors, and the file tool cannot edit anything.
Which Connections Can Reach Them
Switching a tool on makes it available on your site. Each connection still needs access to it:
API Tokens
- A token with the Full access level reaches every tool that is switched on, privileged tools included. While a privileged tool is on, the token dialog shows a warning under Full access that names it.
- A token with the Custom level reaches a privileged tool only when that tool is selected.
- The Read-only level never includes a privileged tool.
For the token settings, see Creating and Managing API Tokens.
OAuth Connections
When a client connects over OAuth, the consent screen shows what it asked for:
- With Full access, the screen shows a notice listing the privileged actions the connection will include, for example "Read files on the server".
- With Custom, each privileged tool that is switched on has its own row, marked Privileged. Check that row to allow it.
On the Connections > OAuth tab, a grant that includes privileged tools has + privileged added to its access level, for example Full access + privileged, or reads Privileged only when it includes nothing else. For more on grants, see Managing OAuth Access.
Approvals and Limits
Approval Before a Call Runs
Privileged tools follow the Ask before destructive actions setting under Easy MCP AI > Settings > Access & safety:
wp_privileged_search_replace_run: while the setting is on, every run waits for your approval, including a dry run. Checking the progress of a run that is already approved does not ask again.wp_privileged_files_read_query: it only reads, so it never waits for approval.
The Always ask for list still applies to both: add a tool name there to make every call to it wait for approval.
Limits
- A connection can make at most 60 privileged tool calls per minute, counted across all privileged tools, on top of the site-wide Rate limit.
- A call stops after about 30 seconds. A search and replace that needs longer continues in the background; see Search and Replace Across the Database.
- A result longer than 64 KB is cut, with a note saying how much was left out. The file tool keeps its answers under that size and tells the AI where to continue.
Review What They Did
Every call to a privileged tool is recorded in the Audit log, with the WordPress user, the connection and the arguments the AI sent, including calls that were refused. A search and replace that writes to the database also adds one entry to Change history when it finishes. See Using the Easy MCP AI Audit Log.
If the Audit log or Change history is switched off under Easy MCP AI > Settings > Logging & history, every privileged call is refused with a message that names the setting to turn back on.