Every AI client that connects to a site through the WordPress MCP Adapter starts the same way. It calls mcp-adapter/discover-abilities to find out what the site can do. On a fresh install with a handful of abilities, that call is instant and nobody thinks about it.
Then the site grows. You install Abilities Manager, an SEO plugin that registers its own abilities, an email plugin, a cache plugin. Our own production site, acrossai.co, currently registers roughly 660 abilities across 17 groups. At that size, the first call every client makes became the one most likely to fail, with PHP memory limit errors on the server and flooded context windows on the client.
This post covers what was going wrong in the MCP Adapter, and the three changes we made to fix it: searchable and paged ability discovery, a new mcp-adapter/server-guide tool, and a connect-time server message that tells the client which tool to call first. If you manage your MCP servers through MCP Manager, there is a section at the end on how it fits in.
The short version
- The problem:
discover-abilitiestook no input and returned every ability on the site in one response. Large sites could exhaust the PHP memory limit, and even when they did not, the response flooded the AI client’s context window. - Fix one: discovery now accepts
search,category,namespaceandtab_groupfilters, and returns at most 60 abilities per call withhas_moreandpagefor paging. - Fix two: a new read-only tool,
mcp-adapter/server-guide, reports every category, namespace and group on the site with a count for each, so the client can pick the right filter on the first attempt. - Fix three: a default server message, sent when the client connects, tells it to call the server guide first. Site owners can keep the system default or write their own.
Table of Contents
The problem: one WordPress MCP Adapter call that returns everything
The MCP Adapter is the official WordPress package that turns abilities registered through the WordPress Abilities API into Model Context Protocol tools. The WordPress Developer Blog has a good introduction to the MCP Adapter if you are new to it.
Its default server exposes abilities to AI clients through three tools. discover-abilities lists them, get-ability-info returns one ability’s input schema, and execute-ability runs it. It is a clean design, and it keeps the MCP tool list short no matter how many abilities a site registers.
The weak point was discovery. In the stock adapter, discover-abilities has no input schema at all. Its execute callback calls wp_get_abilities(), walks every registered ability, keeps the ones exposed to MCP, and builds a name, label and description entry for each. The whole list goes back in a single response. Its own description promises exactly that: all registered abilities, with their basic information.
That behaviour has two costs, and both grow with the number of abilities on the site.
Cost on the server
PHP memory limit
Every ability object is loaded, every entry is built into an array, and then the whole array is encoded to JSON on top of it. On shared hosting with a 128 MB or 256 MB memory_limit, and with other plugins already loaded into the same request, a large registry can push the request into a fatal Allowed memory size exhausted error. The client sees a failed connection, not a helpful message.
Cost on the client
The context window
When the request does survive, hundreds of descriptions land in the AI client’s context before it has done any real work. That is tokens spent on abilities the task will never touch, less room left for the actual job, and a model that now has to pick the right tool out of a very long list. Rate limits and lost context on long tasks follow from there.
Raising the memory limit only moves the ceiling. Install a few more plugins and you hit it again, and the context window problem does not change at all. The real fix was to stop asking for everything at once.
Fix one: search, filter and page discover-abilities
mcp-adapter/discover-abilities now takes parameters. Instead of returning the full registry, it returns up to 60 abilities per call, and each entry now carries its category and tab_group alongside the name, label and description. The client narrows the list with any of four filters:
| Parameter | What it narrows by |
|---|---|
search | Free text against the abilities on the site, for when the client knows roughly what it wants |
category | The ability’s registered category |
namespace | The prefix before the slash, for example content, blocks or rank-math |
tab_group | The group the ability library is organised on. Usually the sharpest single cut |
page | The next page of results, used only when the response reports has_more: true |
The tool description was rewritten to match, because the description is the only documentation an AI client reads. It now tells the model to narrow rather than page through everything, names tab_group as the best axis, explains has_more, points to get-ability-info for the full schema once a name is found, and sends the model to the server guide when it is unsure what the site contains.
A narrowed call looks like this. The response is illustrative and trimmed:
// Request
{
"ability": "mcp-adapter/discover-abilities",
"input": { "namespace": "content", "search": "update" }
}
// Response (trimmed)
{
"abilities": [
{
"name": "content/update-post",
"label": "...",
"description": "...",
"category": "...",
"tab_group": "..."
}
],
"has_more": false
}The important property is that the response is now bounded. Whether a site has 40 abilities or 4,000, a single discovery call never builds and encodes more than one page. Memory use stops scaling with the size of the registry, and so does the token bill. It is the same thinking behind the Abilities Manager token efficiency work: an AI client should only pay for what the task actually needs.
Fix two: an MCP server guide, so filters are not guesses
Filters create a new problem. A filter is only useful if you know what values exist. An AI client connecting to a site for the first time has no idea whether this site uses a rank-math namespace, what the groups are called, or how many abilities sit in each one. Left alone, it guesses a filter value, gets an empty list, and tries again. That is wasted calls and wasted context, which is the thing we were trying to fix.
So we added a fourth tool, mcp-adapter/server-guide. It does two things:
- Explains the server. How the three tools work, every filter they accept, and their real limits, including the 60 per call page size.
- Reports what this site actually contains. Every category, namespace and group present, with an ability count for each. That inventory is not obtainable any other way without paging through every ability.
It takes no input and changes nothing, so it is safe to call on every connection. One call returns a compact map of the site, and the client can go straight to the right tab_group on its first discovery request instead of feeling around for it.
Fix three: tell the AI client where to start
A server guide only helps if the client calls it first. Tool descriptions help, but a model reads the tool list and can still dive straight into discovery. The reliable place to set the order is the message the server sends when the client connects, which the client reads before it calls any tool at all.
There is now a Default server message setting for this. It is sent after the server’s own description and tells the client what kind of server this is and which tool to call first. The system default 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.
Site owners get two options. System default is kept up to date by the plugin and is what we recommend, because the message will change as the tools do. Custom lets you write your own. It replaces this message only, never your server description, and leaving the field empty falls back to the system default.
The new discovery flow, end to end
1
Connect
The client receives the server message and learns to call the server guide first.
2
Map the site
server-guide returns the categories, namespaces and groups, with counts.
3
Narrow
discover-abilities with a real filter value returns one small page.
4
Run
get-ability-info for the schema, then execute-ability.
| Before | After | |
|---|---|---|
| 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 | Plus category and tab_group |
| Knowing what filters exist | Guess, or page through everything | One call to server-guide |
| Where to start | Up to the client | Stated in the connect-time server message |
| Memory and tokens | Grow with the registry | Bounded by the page size |
What changes for existing clients
One behaviour change is worth stating plainly. A discover-abilities call with no parameters used to return the full list. It now returns the first page. If you have your own integration that reads the discovery response and assumes it saw everything, check has_more and request the next page until it is false, or better, pass a filter.
AI clients such as Claude, ChatGPT, Cursor and local models need no changes. They read the new tool description and the server message like any other MCP metadata, and a capable client starts narrowing on its own. get-ability-info and execute-ability behave exactly as before, and nothing about the WordPress Abilities API itself changes.
Where MCP Manager fits
On its own, the MCP Adapter is a developer library with no screens. MCP Manager is our free plugin that adds them: create and route multiple MCP servers, choose which abilities each one exposes, generate Application Passwords, copy a ready-made config for each AI client, and decide which users are allowed to connect, with every request checked. It all runs on your own server, with no relay in the middle.
The discovery fixes in this post apply to the standard MCP Adapter default server, the endpoint at /wp-json/mcp/mcp-adapter-default-server that MCP Manager’s client configs point to. That is the server any MCP client reaches through the three adapter tools, so it is the one that needed bounded, filterable discovery.
MCP Manager also ships a ready-made AcrossAI server at /acrossai/mcp, which takes the same idea further. Instead of one discovery tool over the whole registry, it exposes a small set of grouped toolsets, such as Content, Blocks, Appearance and Diagnostics, each with its own discover, info and execute actions and its own server guide. Both servers now share the same principle: give the client a map first, then let it ask for only what it needs.
New to MCP Manager?
- Read the MCP Manager overview for supported clients, transports and access control.
- Follow MCP Manager Quick Setup to connect Claude, ChatGPT, Gemini, Grok or Cursor in about a minute.
- See User Facing for MCP Adapter for why the adapter needs a UI layer at all.
- Want one-click connectors instead of config files? That is AcrossAI Pro.
Running a large ability registry?
If discovery is failing or eating your context window, book a free consultation. We will look at your setup with you, with no sales script attached.
Frequently asked questions
Why does the WordPress MCP Adapter hit the PHP memory limit?
In the stock adapter, discover-abilities loads every registered ability, builds an entry for each and encodes the whole list to JSON in a single request. On sites with hundreds of abilities and a modest memory_limit, that one request can run out of memory. Paged, filtered discovery keeps each response to one bounded page.
Can I just raise the PHP memory limit instead?
You can, and on some hosts you cannot. Either way it only postpones the failure until the next few plugins are installed, and it does nothing for the AI client’s context window. Bounded, filtered discovery fixes both.
Is this a change to the WordPress Abilities API?
No. The Abilities API is WordPress core and is untouched. The changes are in the MCP Adapter layer that turns abilities into MCP tools, which is where discovery lives.
Why is tab_group the recommended filter?
It is the axis the ability library is organised on, so one group maps closely to one kind of job: content, blocks, SEO, cache and so on. A single tab_group value usually cuts the list down further than any other one filter.
Should I write a custom server message?
Most sites should keep the system default, which the plugin updates as the tools evolve. Write a custom one if you run a specialised server and want to steer clients toward a particular group or workflow. Leaving the field empty always returns you to the default.
Does calling server-guide change anything on my site?
No. It takes no input and is read only. It reports how the server works and what the site contains, nothing more.
Do I need MCP Manager to use the MCP Adapter?
No. The MCP Adapter works on its own if you are comfortable configuring it in code. MCP Manager adds the admin screens, client configs and access control on top, for free. Our MCP Adapter vs MCP Manager comparison covers the differences.
Where to go next
- MCP Manager, the free admin interface for the WordPress MCP Adapter, also on WordPress.org
- Abilities Manager, the ready-made ability library, also on WordPress.org
- MCP Manager Quick Setup, if you are connecting an AI client for the first time
- WordPress AI Plugin Showdown, where Jonathan Bossenger tested MCP Manager live
- MCP Adapter vs MCP Manager
- The MCP Adapter and Abilities API repositories on GitHub
The broader lesson is one we keep relearning. An AI client does not read documentation, it reads tool descriptions and whatever each call returns. A discovery step that returns everything works in a demo and breaks in production. Giving the client a map first, and a way to ask for only what it needs, is what makes a WordPress site with hundreds of abilities usable by AI at all.