Appearance
Limit AI Calls per User, Site or Connection
The Rate limit setting caps how many requests one AI connection can make in a minute. Throttle rules go further. With the EASY_MCP_AI_THROTTLES constant you can limit one tool, a group of tools, every write or every read. A rule can count per WordPress user across all their connections, for a whole site, or per connection, over a minute, an hour or a day. This guide explains the rule format, how rules work together with the built-in limits, what counts as a call, and gives ready-to-use examples.
In this article
When to Use Throttle Rules
Throttle rules are cost and safety controls for sites where AI clients do real work:
- One budget per person. The Rate limit counts each connection separately, so a user with three AI clients gets three allowances. A
userrule gives that person one budget across all of them. - Multisite networks. A
userrule counts one person across every subsite of the network, so moving to another subsite does not start a new count. - Actions that are hard to undo. Cap deletions, user changes or plugin changes per hour.
- Actions that reach people or cost money. Cap emails per day for the whole site, or calls to paid SEO data providers.
- One heavy integration. Raise the per-minute limit for one kind of call without raising it for everything else.
Rules are set only in wp-config.php, an environment variable, or code. There is no admin screen for them, so nobody can change them from WordPress. Rules apply to every user, including administrators and network super admins.
Set Your First Rule
Add the constant to wp-config.php above the line /* That's all, stop editing! */:
php
define( 'EASY_MCP_AI_THROTTLES', 'writes=500/hour/user' );Every WordPress user can now make at most 500 writes an hour, counted across all their API keys and OAuth connections. When a user reaches the limit, their next write is refused with a message that says when to try again. Their reads keep working.
To set several rules, separate them with commas or new lines:
php
define( 'EASY_MCP_AI_THROTTLES', 'writes=500/hour/user, wp_delete_*=20/hour/user, wp_send_email=50/day/site' );Each request reads the rules again, so a change applies from the next request.
Use an Environment Variable
You can set an environment variable with the same name instead, for example in your hosting panel or container configuration:
sh
EASY_MCP_AI_THROTTLES="writes=500/hour/user,wp_send_email=50/day/site"When both are set, the wp-config.php constant is used and the environment variable is ignored.
Use an Array
In wp-config.php you can also pass a list of rules, which is easier to read and comment:
php
define( 'EASY_MCP_AI_THROTTLES', array(
'writes=500/hour/user', // every user's writes, across their connections
'wp_delete_*=20/hour/user', // deletions are hard to undo
'wp_send_email=50/day/site', // emails reach real people
) );How a Rule Is Written
Every rule has four parts:
text
selector=number/window/scope| Part | What it means | Accepted values |
|---|---|---|
| Selector | What the rule counts | *, a tool name, a name pattern, category:<slug>, writes or reads |
| Number | How many are allowed in each window | A whole number from 1 |
| Window | How long each count lasts | minute, hour or day |
| Scope | Who shares the count | user, site or credential |
The scope is required. A rule without one, such as writes=500/hour, cannot be read, and it refuses every call it names until you add the scope. See Mistakes in a Rule.
Spaces and capital letters are ignored, so Writes = 500 / Hour / User is the same rule as writes=500/hour/user. A rule written twice counts once. You can set at most 20 rules.
Selectors
| Selector | Counts | Example |
|---|---|---|
* | Every request a connection makes: connecting, listing tools, reading resources and prompts, and every tool call | *=300/minute/credential |
| A tool name | Calls to that one tool | wp_create_post=50/day/user |
| A name pattern | Calls to every tool whose name matches | wp_wc_*=200/hour/site |
category:<slug> | Calls to every tool in a category | category:woocommerce=300/hour/site |
writes | Calls that change something | writes=500/hour/user |
reads | Calls that only read | reads=2000/hour/user |
Things to know about selectors:
- Tool names must match exactly. You can find each tool's name under Easy MCP AI > Tools. A misspelled name is still a valid rule, but it matches no tool and limits nothing.
- Patterns use
*for any number of characters,?for one character, and brackets for one character from a set. For example,*delete*matches every tool with "delete" in its name, andwp_[!d]*matches every tool whose name does not start withwp_d. *andwp_*are different.*on its own counts every request, including connecting and listing tools.wp_*is a pattern that counts tool calls only, because every tool name starts withwp_.- Writes and reads. A write is any call to a tool that is not marked read-only. A few tools decide for each call.
wp_cli_runcounts by command, sooption getis a read andoption updateis a write. A dry run ofwp_update_page_layoutis a read.
Category Slugs
A category: rule names one of these slugs:
| Slug | Covers |
|---|---|
posts, pages, cpt | Posts, pages and custom post type items |
media | The media library |
comments | Comments, including bulk moderation |
taxonomy | Categories, tags and other terms |
users | Users and user meta |
meta | Post meta |
menus, widgets, blocks, templates, styles, appearance, themes | Site design and themes |
plugins | Installing, activating and updating plugins |
site, site_health, search, revisions, cache | Site settings and information, Site Health, search, revisions and caches |
history, audit, approvals | Change history, the audit log and approvals |
skills, feedback | wp_get_skill and wp_send_feedback |
rest | The REST route tools (wp_rest_read, wp_rest_write, wp_rest_delete, wp_rest_routes) |
cli | wp_cli_run |
mail | wp_send_email |
privileged | The privileged tools |
abilities | Tools from the WordPress Abilities API (wp_ability_*) |
builders, divi | Page-builder layouts and Divi |
woocommerce, acf, buddypress, events-calendar, contact-form-7, redirection, loco-translate, translations, smart-slider-3 | Plugin integrations |
yoast-seo, rank-math, seopress, aioseo, the-seo-framework, slim-seo | SEO plugin integrations |
ga, gsc, dfs, semrush, seranking, ahrefs, sitekit | Google Analytics, Search Console, DataForSEO, Semrush, SE Ranking, Ahrefs and Site Kit |
A slug that is not in this list is still a valid rule, but it matches no tool.
Windows
A window is how long a count lasts before it starts again from zero. There are three: minute, hour and day. There is no monthly window, so write a monthly budget as a daily one.
When each window starts depends on whether your site has a persistent object cache, such as Redis or Memcached:
- With an object cache, windows follow the clock. A minute window ends at the start of the next minute, an hour window on the hour, and a day window at 00:00 UTC.
- Without an object cache, a window starts with the first call it counts and lasts one minute, hour or day from then. A one-a-minute rule that counted a call at 10:15:40 refuses the next call until 10:16:40.
The Rate limit and the privileged-tool limit always start their minute with the first request they count.
Scopes
| Scope | Who shares the count | On a multisite network |
|---|---|---|
user | One WordPress user, across all their API keys and OAuth connections | One count across every subsite |
site | Everyone using the site, together | Each subsite counts separately |
credential | One connection: one API key, or one AI client a user approved through OAuth | Each subsite counts separately |
A credential count belongs to the approved AI client, not to one access token, so a client that refreshes its token keeps its count.
How Rules Work Together
- Every rule that matches a call applies, each with its own count. The first rule that is full refuses the call. With
writes=500/hour/user, wp_create_post=50/day/user, eachwp_create_postcall counts toward both rules, and the 51st post of the day is refused even if the user has writes left this hour. - A broader rule never loosens a narrower one. A generous
writesrule does not lift a strictwp_delete_*rule. - A refused call is given back. When a limit refuses a call, the call is taken back from every rule it had already counted against, so retrying a refused call does not use up your other limits.
- Changing a rule starts its count again. A rule with a new number, window or scope is a new rule with a new count.
How Rules Work with the Built-In Limits
Easy MCP AI has two limits that apply without any rule:
| Limit | Where it is set | Default |
|---|---|---|
| Rate limit | Easy MCP AI > Settings > Access & safety, or the EASY_MCP_AI_RATE_LIMIT_PER_MINUTE constant | 120 requests a minute per connection |
| Privileged-tool limit | Fixed | 60 privileged tool calls a minute per connection |
A rule changes them like this:
- An hourly or daily rule adds a volume limit. The built-in limits stay in place for the calls it matches.
- A per-minute rule replaces both built-in limits for the calls it matches. Those calls no longer count toward the Rate limit or the privileged-tool limit; the rule's own number applies instead.
| Rules | What happens |
|---|---|
| None | The Rate limit and the privileged-tool limit apply as usual. |
writes=500/hour/user | Writes need room both in the user's hourly 500 and in each connection's Rate limit. |
*=300/minute/credential | Every request of a connection counts toward 300 a minute instead of the Rate limit. The Rate limit field shows as locked, with a note naming EASY_MCP_AI_THROTTLES. |
*=200/minute/user | One person gets 200 requests a minute across all their connections, instead of each connection getting the Rate limit. The field shows as locked. |
reads=600/minute/credential | Read calls can go up to 600 a minute. Writes, connecting and listing tools still count toward the Rate limit. |
wp_privileged_*=20/minute/credential | Privileged calls are limited to 20 a minute, instead of 60, and no longer count toward the Rate limit. |
What Counts as a Call
When a Call Is Counted
Each call is counted at one of two points, depending on the rule:
*rules and per-minute rules are counted at the same point as the Rate limit: once the connection's allowed tools include the tool, and before the plugin checks anything else. A call that is then refused, because the tool is switched off, the user lacks the permission, or an argument is wrong, still counts. A call to a tool that does not exist also counts. This keeps a stream of refused calls limited too. A call to a tool outside the connection's allowed tools is refused first and never counts.- Hourly and daily rules that name tools count a call only after it passes the plugin's own checks: the tool is switched on, the user has the permission, and every argument is one the tool accepts, of the right type. From that point every call counts. That includes a call the tool itself refuses, such as
wp_create_postwithout a title, and a call that fails while it runs.
A call that waits for approval counts when it pauses, and again when the AI client sends it once more after you approve it. A call refused by a limit never counts.
Batch Tools Count Each Item
Tools that write several items in one call count each item, so writes=500/hour/user means 500 items, however they are batched:
| Tool | Counts |
|---|---|
wp_wc_batch_update_products, wp_wc_batch_update_orders, wp_wc_batch_update_variations | Each item in the create, update and delete lists |
wp_bulk_moderate_comments | Each comment, counted once even if it is listed twice |
wp_redirection_delete_redirects, wp_rm_delete_redirects | Each redirect, counted once even if it is listed twice |
wp_send_email | Each recipient |
A batch counts its items toward every rule that names it, including writes and category: rules. A * rule counts the whole request once. Every other tool counts one per call.
A call with more items than a rule allows is always refused. Under wp_send_email=2/day/site, one email to three people can never be sent. The refusal says so, and asks the AI client to send fewer items at a time.
WP-CLI Commands, Restores and Background Tasks
wp_cli_run: a command that runs through another tool, such aswp post create, is counted against that tool's rules and againstwritesorreads. A rule that nameswp_cli_runcounts each command. The Rate limit and*rules count the command once, however many tools it uses. See Run WP-CLI Commands with AI.wp_history_apply: each tool call it makes to restore a change is counted against that tool's rules, and also as a request toward the Rate limit and*rules. A restore refused by a limit is reported as failed, with the limit's message as the reason. See Restore AI Changes from Change History.- Background tasks: the call that starts a long-running task counts. The steps the task then runs in the background do not.
What Is Not Counted
- Work done outside Easy MCP AI: the WordPress REST API with an Application Password, the WordPress admin, WP-CLI run on the server, and scheduled cron events.
- Emails WordPress or a plugin sends as a side effect of another tool, such as a new-user notification or a WooCommerce order email. A
wp_send_emailrule counts onlywp_send_email. - Nothing is counted per IP address, because an office network or an AI provider can share one address among many people.
When a Limit Is Reached
The AI client receives an error that names the rule, who it counts, and when to try again:
text
Rate limit exceeded: wp_create_post is limited to 20 an hour per user, across all their connections (EASY_MCP_AI_THROTTLES). Try again in 14 minutes.The wording follows the rule:
| Rule | Message starts with |
|---|---|
writes=500/hour/user on a multisite network | Rate limit exceeded: writes are limited to 500 an hour per user, across all their connections and every site of this network |
wp_wc_*=200/hour/site | Rate limit exceeded: tools matching wp_wc_* are limited to 200 an hour for the whole site |
category:dfs=100/day/site | Rate limit exceeded: dfs tools are limited to 100 a day for the whole site |
*=300/minute/credential | Rate limit exceeded: requests are limited to 300 a minute per connection |
When a batch call is refused, the message adds This call counts as 25, one for each item it writes; send fewer items at a time.
The AI client can pass the message on to you, or try again after the time it names. A wp_cli_run command that works on several items, such as post delete 12 13 14, stops at the first item a limit refuses, and the items after it are not touched.
For developers, the error is a JSON-RPC error with code -32003. Its data gives the limit, the seconds until the window ends, the rule, and its scope:
json
{
"jsonrpc": "2.0",
"id": 7,
"error": {
"code": -32003,
"message": "Rate limit exceeded: wp_create_post is limited to 20 an hour per user, across all their connections (EASY_MCP_AI_THROTTLES). Try again in 14 minutes.",
"data": {
"limit": 20,
"retry_after": 812,
"rule": "wp_create_post=20/hour/user",
"scope": "user"
}
}
}A refusal by the Rate limit says Rate limit exceeded. Please try again later., and a refusal by the privileged-tool limit says Privileged tool rate limit exceeded. Please try again in a minute.
Mistakes in a Rule
A typo must never lift a limit, so a rule that cannot be read refuses the calls it was meant to limit:
| Entry | What happens |
|---|---|
The selector is fine but the rest is not: writes=lots/hour/user, writes=500/hour, writes=0/hour/user, writes=500/week/user | Every call the selector names is refused until you fix the entry. Other tools keep working. |
The selector cannot be read: create posts=5/hour/user | The entry names no tool and limits nothing. |
| A 21st entry or later | It refuses every call it names, like an entry that cannot be read. |
A misspelled tool name or category: wp_create_pots=5/hour/user | A valid rule that matches no tool, so it limits nothing. Nothing warns about it. |
A refused call caused by an unreadable entry tells the AI client:
text
Rate limit exceeded: the throttle rule "writes=lots/hour/user" in EASY_MCP_AI_THROTTLES cannot be read, so every call it names is refused until it is fixed. A rule is written selector=number/window/scope, for example writes=500/hour/user. Nothing was changed.Check What Is Set
- Diagnostics. On Easy MCP AI > Dashboard, open Diagnostics and find the Per-token rate limit check under Access & safety. It warns about every entry that cannot be read and every entry that names nothing. While a per-minute
*rule replaces the Rate limit, it says so and names the rule. - Settings. On Easy MCP AI > Settings > Access & safety, the Rate limit field is locked while a per-minute
*rule replaces it. - Audit log. On Easy MCP AI > Activity, each rule's first refusal in a window appears as a
_throttleentry with the status Refused. Its arguments name the rule and the tool. Search for_throttleto find them. Later refusals in the same window are not listed again, and the refused calls themselves are not listed one by one. With an object cache you get one entry per rule, count and window. Without one, refusals at the same moment can each add an entry. See Using the Easy MCP AI Audit Log.
Examples
Give Each Person One Write Budget
php
define( 'EASY_MCP_AI_THROTTLES', 'writes=500/hour/user, writes=2000/day/user' );Each user can make 500 writes an hour and 2,000 a day, however many AI clients they connect and, on a network, whichever subsites they work on. Reads are not limited beyond the Rate limit.
Limit Actions That Are Hard to Undo
php
define( 'EASY_MCP_AI_THROTTLES', '*delete*=20/hour/user, wp_update_user=10/hour/site, wp_*_plugin=10/day/site' );*delete* matches every tool with "delete" in its name, including wp_delete_post, wp_wc_delete_product and wp_rest_delete. A pattern such as wp_delete_* would miss the last two. wp_*_plugin matches the tools that install, activate, deactivate, update, uninstall and delete plugins, but not wp_list_plugins.
Stop Mass Content Generation
php
define( 'EASY_MCP_AI_THROTTLES', 'wp_create_post=50/day/user, wp_create_page=20/day/user, wp_duplicate_post=20/day/user' );Posts created through wp_cli_run count too, because each post create command runs wp_create_post. A client can also create content through the REST route tools, so add wp_rest_write=100/day/user if those tools are switched on.
Limit Emails to Real People
php
define( 'EASY_MCP_AI_THROTTLES', 'wp_send_email=50/day/site, wp_create_user=10/day/site' );The whole site can send at most 50 emails a day through wp_send_email, each recipient counted. wp_create_user can send the new user a welcome email, so creating users is limited too. See Send Service Emails with AI.
Keep Paid Data Providers Within Budget
php
define( 'EASY_MCP_AI_THROTTLES', 'category:dfs=100/day/site, category:semrush=50/day/site, category:seranking=50/day/site' );Each provider's tools share one daily budget for the site. A call that fails still counts.
Limit a WooCommerce Store
php
define( 'EASY_MCP_AI_THROTTLES', 'category:woocommerce=300/hour/site, wp_wc_batch_update_products=500/day/site' );A batch update of 100 products counts as 100 toward both rules.
Limit Privileged Tools
php
define( 'EASY_MCP_AI_THROTTLES', 'wp_privileged_*=20/minute/credential, wp_privileged_search_replace_run=10/day/site' );The per-minute rule replaces the 60-a-minute privileged-tool limit with 20, and the daily rule caps search and replace runs for the site. See Privileged Tools in Easy MCP AI.
Allow One Heavy Integration More
php
define( 'EASY_MCP_AI_THROTTLES', 'reads=600/minute/credential' );A reporting or sync client that reads a lot can make up to 600 read calls a minute, while writes stay under the Rate limit. To raise the limit for everything instead, use *=300/minute/credential.
Cap the Whole Site per Day
php
define( 'EASY_MCP_AI_THROTTLES', '*=20000/day/site' );All connections together can make at most 20,000 requests a day, including refused ones.
Limit WordPress Ability Tools
php
define( 'EASY_MCP_AI_THROTTLES', 'category:abilities=500/hour/user' );This counts every tool another plugin adds through the WordPress Abilities API. To limit one plugin's abilities only, use a pattern such as wp_ability_woocommerce_*.
Set Rules from Code
The easy_mcp_ai_throttles filter receives the list of entries from the constant or environment variable and returns the list to use. Each entry it returns is read exactly as an entry in the constant. Put the code in a must-use plugin, so it cannot be switched off from the admin.
Use stricter rules on production only:
php
add_filter( 'easy_mcp_ai_throttles', function ( $entries ) {
if ( 'production' === wp_get_environment_type() ) {
$entries[] = 'writes=200/hour/user';
}
return $entries;
} );Use different rules on one subsite of a network:
php
add_filter( 'easy_mcp_ai_throttles', function ( $entries ) {
if ( 3 === get_current_blog_id() ) { // the shop
$entries[] = 'category:woocommerce=300/hour/site';
}
return $entries;
} );Give administrators a larger budget than everyone else:
php
add_filter( 'easy_mcp_ai_throttles', function ( $entries ) {
$entries[] = current_user_can( 'manage_options' ) ? 'writes=2000/hour/user' : 'writes=300/hour/user';
return $entries;
} );Things to know about the filter:
- Always return an array. Anything else removes every rule.
- The filter can run several times in one request. Return the same list each time for the same request.
- Diagnostics and the Settings screen read the rules as the administrator viewing them. A rule your filter adds only for some users or subsites shows there only when it applies to that administrator.
Limits of Throttle Rules
- Concurrent calls. Without an object cache, calls that arrive at the same moment can go over a limit by the calls in flight. With an object cache the count is exact.
- Evicted counts. An object cache that runs short of memory can drop a count, which then starts again from zero.
- Cost control, not access control. Rules limit how much a connection does. What it may do is decided by the user's role, the connection's allowed tools, and the tools switched on under Easy MCP AI > Tools.
- Deleting the plugin removes the counts stored in the database. Counts held in an object cache expire with their window.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| Every call to a tool is refused with "cannot be read" | An entry that names the tool has a bad number, window or scope, or is past the 20th entry | Fix the entry. Diagnostics names it. |
| A rule seems to do nothing | The tool name or category is misspelled, or the selector cannot be read | Check the name under Easy MCP AI > Tools and the Per-token rate limit check in Diagnostics. |
| A limit resets earlier than expected | The site has no object cache, so the window started with the first call, not on the hour | This is how windows work without an object cache. See Windows. |
| A limit was used up faster than expected | Batch calls count each item, failed calls count, a call that waits for approval counts twice, and per-minute and * rules count refused calls | See What Counts as a Call. |
The count started again after you edited wp-config.php | A changed rule is a new rule with a new count | Expected. Leave a rule unchanged to keep its count. |
| The Rate limit field is locked | A per-minute * rule replaces it | Change or remove the * rule in wp-config.php. |
For the other constants Easy MCP AI reads, see Configuring Easy MCP AI with wp-config.php Constants. To switch tools off entirely instead of limiting them, see Switch Tools On or Off from wp-config.php.