Skip to content

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 user rule gives that person one budget across all of them.
  • Multisite networks. A user rule 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
PartWhat it meansAccepted values
SelectorWhat the rule counts*, a tool name, a name pattern, category:<slug>, writes or reads
NumberHow many are allowed in each windowA whole number from 1
WindowHow long each count lastsminute, hour or day
ScopeWho shares the countuser, 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 ​

SelectorCountsExample
*Every request a connection makes: connecting, listing tools, reading resources and prompts, and every tool call*=300/minute/credential
A tool nameCalls to that one toolwp_create_post=50/day/user
A name patternCalls to every tool whose name matcheswp_wc_*=200/hour/site
category:<slug>Calls to every tool in a categorycategory:woocommerce=300/hour/site
writesCalls that change somethingwrites=500/hour/user
readsCalls that only readreads=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, and wp_[!d]* matches every tool whose name does not start with wp_d.
  • * and wp_* 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 with wp_.
  • 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_run counts by command, so option get is a read and option update is a write. A dry run of wp_update_page_layout is a read.

Category Slugs ​

A category: rule names one of these slugs:

SlugCovers
posts, pages, cptPosts, pages and custom post type items
mediaThe media library
commentsComments, including bulk moderation
taxonomyCategories, tags and other terms
usersUsers and user meta
metaPost meta
menus, widgets, blocks, templates, styles, appearance, themesSite design and themes
pluginsInstalling, activating and updating plugins
site, site_health, search, revisions, cacheSite settings and information, Site Health, search, revisions and caches
history, audit, approvalsChange history, the audit log and approvals
skills, feedbackwp_get_skill and wp_send_feedback
restThe REST route tools (wp_rest_read, wp_rest_write, wp_rest_delete, wp_rest_routes)
cliwp_cli_run
mailwp_send_email
privilegedThe privileged tools
abilitiesTools from the WordPress Abilities API (wp_ability_*)
builders, diviPage-builder layouts and Divi
woocommerce, acf, buddypress, events-calendar, contact-form-7, redirection, loco-translate, translations, smart-slider-3Plugin integrations
yoast-seo, rank-math, seopress, aioseo, the-seo-framework, slim-seoSEO plugin integrations
ga, gsc, dfs, semrush, seranking, ahrefs, sitekitGoogle 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 ​

ScopeWho shares the countOn a multisite network
userOne WordPress user, across all their API keys and OAuth connectionsOne count across every subsite
siteEveryone using the site, togetherEach subsite counts separately
credentialOne connection: one API key, or one AI client a user approved through OAuthEach 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, each wp_create_post call 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 writes rule does not lift a strict wp_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:

LimitWhere it is setDefault
Rate limitEasy MCP AI > Settings > Access & safety, or the EASY_MCP_AI_RATE_LIMIT_PER_MINUTE constant120 requests a minute per connection
Privileged-tool limitFixed60 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.
RulesWhat happens
NoneThe Rate limit and the privileged-tool limit apply as usual.
writes=500/hour/userWrites need room both in the user's hourly 500 and in each connection's Rate limit.
*=300/minute/credentialEvery 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/userOne 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/credentialRead calls can go up to 600 a minute. Writes, connecting and listing tools still count toward the Rate limit.
wp_privileged_*=20/minute/credentialPrivileged 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_post without 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:

ToolCounts
wp_wc_batch_update_products, wp_wc_batch_update_orders, wp_wc_batch_update_variationsEach item in the create, update and delete lists
wp_bulk_moderate_commentsEach comment, counted once even if it is listed twice
wp_redirection_delete_redirects, wp_rm_delete_redirectsEach redirect, counted once even if it is listed twice
wp_send_emailEach 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 as wp post create, is counted against that tool's rules and against writes or reads. A rule that names wp_cli_run counts 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_email rule counts only wp_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:

RuleMessage starts with
writes=500/hour/user on a multisite networkRate 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/siteRate limit exceeded: tools matching wp_wc_* are limited to 200 an hour for the whole site
category:dfs=100/day/siteRate limit exceeded: dfs tools are limited to 100 a day for the whole site
*=300/minute/credentialRate 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:

EntryWhat happens
The selector is fine but the rest is not: writes=lots/hour/user, writes=500/hour, writes=0/hour/user, writes=500/week/userEvery call the selector names is refused until you fix the entry. Other tools keep working.
The selector cannot be read: create posts=5/hour/userThe entry names no tool and limits nothing.
A 21st entry or laterIt refuses every call it names, like an entry that cannot be read.
A misspelled tool name or category: wp_create_pots=5/hour/userA 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 _throttle entry with the status Refused. Its arguments name the rule and the tool. Search for _throttle to 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 seeWhyWhat 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 entryFix the entry. Diagnostics names it.
A rule seems to do nothingThe tool name or category is misspelled, or the selector cannot be readCheck the name under Easy MCP AI > Tools and the Per-token rate limit check in Diagnostics.
A limit resets earlier than expectedThe site has no object cache, so the window started with the first call, not on the hourThis is how windows work without an object cache. See Windows.
A limit was used up faster than expectedBatch calls count each item, failed calls count, a call that waits for approval counts twice, and per-minute and * rules count refused callsSee What Counts as a Call.
The count started again after you edited wp-config.phpA changed rule is a new rule with a new countExpected. Leave a rule unchanged to keep its count.
The Rate limit field is lockedA per-minute * rule replaces itChange 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.

Was this helpful?