Skip to content

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:

ToolWhat it doesGuide
wp_privileged_search_replace_runFinds a piece of text everywhere in your database and replaces it, for example an old domain after a site move. It writes to the databaseSearch and Replace Across the Database
wp_privileged_files_read_queryReads, 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 nothingRead 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 ​

  1. In WordPress, go to Easy MCP AI > Tools and search for the exact tool name, for example wp_privileged_files_read_query.
  2. Enable the tool and click Save changes. If a deployment setting locks the control, you cannot change the tool's enabled state here.
  3. 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, disable it in Easy MCP AI > Tools and click Save changes.

💡 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:

ToolSingle siteMultisite network
wp_privileged_search_replace_runAn 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_queryAn 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 ​

Configure approval for each privileged tool under Easy MCP AI > Tools:

  • wp_privileged_search_replace_run: when Require approval applies, every new run waits for your approval, including a dry run. Deployment settings take precedence, and operation-specific exceptions still apply. Checking the progress of an already-running job does not ask again.
  • wp_privileged_files_read_query: although it only reads files, its calls can still require approval when Require approval applies.

Approval is separate from access: it does not enable the tool or give a user or connection permission to use it. Those requirements still apply. Review any deployment lock before changing a tool's approval setting.

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 per-minute throttle rule that names privileged tools, such as wp_privileged_*=20/minute/credential, replaces both limits for those calls; see Limit AI Calls per User, Site or Connection.
  • 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.

Was this helpful?