You connect Claude, ChatGPT or Cursor to a WordPress site through the WordPress MCP Adapter. On a small test site it works instantly. On your real, plugin-heavy production site the connection fails before the AI does anything, and the server log shows a PHP fatal error: Allowed memory size exhausted. Or the connection works, but the AI feels slow, confused, and runs out of context halfway through a task.
In most cases, both symptoms trace back to one tool call. This guide explains why the MCP Adapter hits the PHP memory limit on large sites, why raising memory_limit is not a real fix, and the three changes that solve it for good.
Quick answer
The MCP Adapter’s discover-abilities tool returns every registered ability in a single response. On sites with hundreds of abilities, building and JSON-encoding that list can exhaust PHP memory, and even when it does not, it floods the AI client’s context window. The fix is to make discovery searchable and paged (60 abilities per call), add a read-only mcp-adapter/server-guide tool that maps the site, and send a connect-time server message that tells the client to call the guide first.
How the WordPress MCP Adapter works
The MCP Adapter is the official WordPress package that takes abilities registered through the WordPress Abilities API and exposes them to AI clients as Model Context Protocol tools. The WordPress AI team introduced it in the MCP Adapter announcement on Make WordPress, and the source lives in the WordPress/mcp-adapter repository on GitHub.
Instead of registering one MCP tool per ability, the adapter’s default server exposes just three:
discover-abilitieslists what the site can doget-ability-inforeturns the input schema for one abilityexecute-abilityruns it
It is a smart design. The AI client’s tool list stays short whether the site has ten abilities or a thousand. But it also means everything depends on discovery working well, and that is where the trouble starts.
Why discover-abilities causes the memory limit error
Every AI client begins a session the same way, by calling mcp-adapter/discover-abilities.
In the stock adapter, that tool has no input schema. The client cannot ask for a subset or a category, so it gets everything. Under the hood, the callback runs wp_get_abilities(), loops over every registered ability, keeps those exposed to MCP, builds a name, label and description entry for each, and returns the complete list in one response.
That is fine at a small scale, but abilities add up fast. An ability library, an SEO plugin, an email plugin and a cache plugin can each register dozens. One real production site we examined registers roughly 660 abilities across 17 groups. That is not an extreme setup. It is what a mature WordPress site looks like once plugins adopt the Abilities API, and as AI becomes a first-class part of WordPress, those numbers will only grow.
At that size, the first discovery call creates two separate problems, and both get worse as the site grows.
Problem 1: the PHP memory limit
Building the response means loading every ability object, assembling an array entry for each, and then JSON-encoding the whole array on top of that, all inside a request that has already loaded every other active plugin. On shared hosting with a memory_limit of 128 MB or 256 MB, that can trigger the fatal Allowed memory size exhausted error. The AI client does not get an explanation. It just sees a failed connection.
Problem 2: the AI context window
Even when the request survives, hundreds of ability descriptions land in the model’s context before it has started the real task. That means tokens spent on abilities the task will never use, less room for the actual work, and a model forced to pick the right tool from a very long list. On longer sessions this leads to rate limits and lost context.
Why raising the PHP memory limit is not a real fix
The instinctive response is to bump WP_MEMORY_LIMIT in wp-config.php or ask your host for more memory. It may work for a while, but it has three weaknesses:
- Many hosts will not let you raise it much, if at all.
- It only postpones the failure until the next few plugins add more abilities.
- It does nothing for the context window problem, which affects every large site regardless of server memory.
The root cause is a design issue: discovery asks for everything at once. The fix has to change that.
Fix 1: searchable, paged discover-abilities
The first change lets discover-abilities accept parameters and caps what it returns. A single call now returns at most 60 abilities, and each entry includes its category and tab_group alongside the name, label and description.
| Parameter | What it narrows by |
|---|---|
search | Free-text matching, for when the client roughly knows what it wants |
category | The ability’s registered category |
namespace | The prefix before the slash, such as content, blocks or rank-math |
tab_group | The group abilities are organised under, usually the most effective single filter |
page | The next page, only needed when the response includes has_more: true |
The tool’s description was rewritten too, because AI clients do not read documentation pages. The description is the only guidance they get. It now tells the model to narrow rather than page through everything, recommends tab_group as the best filter, explains has_more, points to get-ability-info for full schemas, and suggests the server guide when the model is unsure what the site contains.
A narrowed request looks like this (response trimmed):
// Request
{
"ability": "mcp-adapter/discover-abilities",
"input": { "namespace": "content", "search": "update" }
}
// Response
{
"abilities": [
{
"name": "content/update-post",
"label": "...",
"description": "...",
"category": "...",
"tab_group": "..."
}
],
"has_more": false
}The key result is that every response is now bounded. A site with 40 abilities and a site with 4,000 produce discovery responses of the same maximum size. Memory use and token cost stop scaling with the size of the registry.
Fix 2: an MCP server guide so filters are not guesswork
Filters solve one problem and create another: to use a filter, you need to know which values exist. A client connecting for the first time does not know whether the site has a rank-math namespace, what the groups are named, or how many abilities each holds. So it guesses, gets an empty result, and guesses again, burning calls and context.
The answer is a new read-only tool, mcp-adapter/server-guide. It does two jobs:
- Explains the server: how the three tools work, every filter they accept, and their real limits, including the 60-per-page cap.
- Maps the site: every category, namespace and group present, each with an ability count. There is no other way to get that overview without paging through the full registry.
It takes no input and changes nothing, so it is safe to call on every connection. One lightweight call gives the client a map, and its first discovery request can target the right tab_group.
Fix 3: a connect-time server message
A map only helps if the client looks at it first. Tool descriptions nudge in that direction, but a model can still jump straight into discovery. The most reliable way to set the order is the message a server sends when a client connects, which the client reads before calling any tool.
A new Default server message setting handles this. It is sent after the server’s own description, and the default text reads:
This server exposes WordPress abilities through three tools: discover-abilities to find them, get-ability-info to read one’s parameters, and execute-ability to run it. Call mcp-adapter/server-guide first. It reports every category, namespace and group on this site with a count for each, so you can narrow on the first attempt instead of guessing a filter value.
There are two options. System default keeps the message maintained as the tools evolve and is the right choice for most sites. Custom lets you write your own, useful if you run a specialised server and want to steer clients toward a particular group or workflow. A custom message replaces only this message, never your server description, and clearing the field returns to the default.
The new MCP discovery flow, step by step
- Connect: the client reads the server message and learns to call the guide first.
- Map:
server-guidereturns the site’s categories, namespaces and groups with counts. - Narrow:
discover-abilitiesis called with a real filter value and returns one small page. - Run:
get-ability-infofetches the schema, thenexecute-abilitydoes the work.
Before and after
| Stock MCP Adapter | With the fix | |
|---|---|---|
| Discovery input | None | search, category, namespace, tab_group, page |
| Abilities per response | Every ability on the site | Up to 60, with has_more |
| Fields per ability | Name, label, description | Adds category and tab_group |
| Finding valid filters | Guess, or read everything | One call to server-guide |
| Where to start | Left to the client | Set by the connect-time message |
| Memory and token use | Grows with the registry | Capped by page size |
What changes for existing integrations
One behaviour change is worth knowing. A discover-abilities call with no parameters used to return every ability. It now returns only the first page. If you maintain a custom integration that assumes the discovery response is complete, update it to check has_more and request the next page until it is false, or better, pass a filter. As always, test changes like this on a local copy first; here is how I set up local WordPress environments with LocalWP and WordPress Studio.
AI clients such as Claude, ChatGPT, Cursor and local models running on llama.cpp need no changes. They read the updated tool description and server message like any other MCP metadata, and capable models start narrowing on their own. get-ability-info and execute-ability behave exactly as before, and the Abilities API in WordPress core is untouched. All of these changes live in the adapter layer, where discovery happens.
If you are building AI features of your own and planning to ship them on WordPress.org, my notes on getting an AI plugin through the WordPress.org plugin review may save you a round or two of back-and-forth.
How to get the fix
These changes apply to the adapter’s standard default server at /wp-json/mcp/mcp-adapter-default-server, the endpoint most MCP clients connect to. They ship in MCP Manager, a free plugin on WordPress.org, which also adds an admin interface to the adapter, since the adapter has no screens of its own. It lets you create multiple MCP servers, choose which abilities each exposes, generate Application Passwords, copy client configs, and control who can connect.
Frequently asked questions
Why does the WordPress MCP Adapter run out of memory?
In the stock adapter, discover-abilities loads every registered ability, builds an entry for each and JSON-encodes the whole list in one request. On sites with hundreds of abilities and a modest memory_limit, that single request can exhaust PHP memory.
Can I just increase the PHP memory limit?
You can on some hosts, but it only delays the failure until more plugins are installed, and it does nothing for the AI client’s context window. Paged, filtered discovery fixes both.
Does this change the WordPress Abilities API?
No. The Abilities API in core is untouched. The changes are in the MCP Adapter layer that turns abilities into MCP tools.
Why is tab_group the recommended filter?
It is the axis abilities are organised on, so one group maps closely to one kind of job, such as content, blocks, SEO or cache. A single tab_group value usually narrows the list more than any other filter.
Is calling server-guide safe?
Yes. It takes no input and is read-only. It only reports how the server works and what the site contains.
Do AI clients like Claude or ChatGPT need updating?
No. They read the new tool description and server message as normal MCP metadata. Only custom integrations that assume discovery returns everything need to handle has_more.
The takeaway
The MCP Adapter’s three-tool design is sound, but its original discovery step assumed small sites. As more plugins register abilities, “return everything” stops scaling on both the server and the AI side. The durable fix is not more memory. It is giving the AI client a map first, and a way to ask for only what the task needs.
Need help with an MCP or Abilities API setup, or a custom integration for your site? Take a look at our custom WordPress plugin development services.
Leave a Reply