Use Royal MCP with Relevanssi
Relevanssi replaces WordPress’s basic search with relevance-ranked results, synonyms and stopwords. From Royal MCP 1.5.15, an AI agent such as Claude or ChatGPT can work on that search with you: run searches the way visitors see them, check that every post is in the index, look at what people search for and what finds nothing, and then fix the gaps with synonyms, stopwords or a re-index of one post. Every change can be previewed first and undone afterwards. This guide explains the seven tools and a simple routine for improving your search.
The seven Relevanssi tools
The tools appear when Relevanssi (free or Premium) is active. Four read and three make changes.
| Tool | What it does | Changes the site? |
|---|---|---|
relevanssi_search | Searches the site with Relevanssi exactly as a visitor would, with relevance order, synonyms and stopwords applied. Each result has its title, post type, address, relevance score and a short excerpt. Queries can be up to 200 characters, and results come 10 at a time by default (up to 50). | No |
relevanssi_get_index_status | Index health: how many posts are indexed, how many should be, how many are missing (with up to 20 of their IDs), which post types are indexed, whether the last full build finished, whether search logging is on, and how many synonyms and stopwords are set. | No |
relevanssi_list_top_searches | The most frequent searches over the last 30 days, or any period up to 365 days, with how often each was searched and the average number of results. | No |
relevanssi_list_zero_hit_searches | Searches that found nothing over the same kind of period, with how often each was tried. | No |
relevanssi_reindex_post | Rebuilds the index entry of one post, for example after its content was changed outside WordPress. | Yes, with undo |
relevanssi_update_synonyms | Adds, removes or replaces synonym pairs for the site’s language. | Yes, with undo |
relevanssi_add_stopword | Adds words that searches should ignore. | Yes, with undo |
Search statistics are totals only
Relevanssi’s search log can record who searched, from which IP address and when. Royal MCP never passes those details on. The two statistics tools return each search term with its count and average results, nothing more, and email addresses that visitors typed into the search box are hidden. The statistics tools need search logging to be switched on in Relevanssi’s settings; if it is off, they say so.
Searches the AI client runs with relevanssi_search are never written to your search log, so testing does not distort your statistics. Results only include posts the signed-in user is allowed to read.
A routine for better search results
Check the index
Ask: “Is my Relevanssi index complete?” If posts are missing, the client can re-index a few individually. For many missing posts, or after changing which post types are indexed, rebuild the index from Relevanssi’s settings page.
Find searches that fail
Ask: “What did visitors search for in the last 90 days that found nothing?” These are your gaps: missing content, different words for the same thing, or misspellings.
Test a fix with a dry run
If visitors search for “sofa” but your products say “couch”, ask the client to do a dry run adding the synonym. It shows the synonym list before and after without saving.
Apply, then search again
Apply the change, then ask the client to run the same search with relevanssi_search to confirm it now finds the right posts.
Synonyms
A synonym pair makes a search for one word also find another. Synonyms apply to the site’s language, and the tool has three modes:
- Append (the default) adds the pairs you give to the existing list.
- Remove deletes the pairs you give.
- Replace sets the whole list to exactly the pairs you give. Use it with a dry run first, because it removes every pair not in your request.
Up to 500 pairs can be sent at once. Each word can be up to 100 characters and cannot contain ; or =, which Relevanssi uses to separate synonyms.
Stopwords
Stopwords are words that searches ignore, such as very common words that would otherwise match almost every post. The tool adds up to 50 words at a time, each up to 50 characters and without commas.
Relevanssi removes a new stopword from the index straight away, so posts stop matching it at once. That makes stopwords the most far-reaching change these tools can make. Ask for a dry run first: it tells you how many posts contain the new words, without saving anything.
Words are stored in lower case, the way Relevanssi keeps them. The reply lists the words that were added, any that were already_present, and, if Relevanssi declined some of them, those under not_kept. Only the words that were actually added are covered by the undo token. Royal MCP can add stopwords but has no tool to remove one; to take a stopword back, undo the change or remove it in Relevanssi’s settings and re-index.
Re-indexing one post
Relevanssi normally indexes a post whenever it is saved. A post can fall out of step when its content is changed by an import, a custom script or a direct database edit. Ask the client to re-index that post; a dry run first shows whether the post type is indexed and how many index entries the post has now.
The account needs permission both to edit the post and to manage Relevanssi. Royal MCP has no tool for a full index rebuild, because that can take a long time and load the server on a large site; use Relevanssi’s own settings page for it.
Undo and other safety controls
All three write tools return an undo token that works once and lasts 72 hours by default. Ask the AI client to undo the change.
- Re-index undo puts the earlier index entry back. For a very large post, with more than 2,000 index entries, no undo token is issued; re-index it again instead if needed.
- Synonym undo restores the earlier synonym list.
- Stopword undo restores the earlier stopword list and puts the words back into the index, so posts match them again. When the words had more than 2,000 index entries, Royal MCP re-indexes the posts that contained them instead, up to 200; if even more posts are affected, the list is still restored and the reply tells you to rebuild the index from Relevanssi’s settings.
If the same thing changed again after your change, for example someone edited the synonyms in Relevanssi’s settings, undo stops and explains why instead of overwriting that edit. You can then ask the client to undo anyway, which restores the earlier state and removes the later edit, or leave it. Changes are listed under Royal MCP > Recent Changes.
Read-only mode and Drafts only refuse all three write tools, as do Read-only and Drafts only access levels for a connection. The four read tools keep working.
Who can use the tools
| Tools | Permission needed |
|---|---|
| Search | Any user who can edit posts. Results include only posts that user can read. |
| Top and zero-result searches | The permission Relevanssi itself requires to view search statistics. |
| Index status, re-index, synonyms and stopwords | The permission Relevanssi requires for its settings, which is administrator access unless your site changes it. Re-indexing also needs permission to edit the post. |
Troubleshooting
“Relevanssi is not active”
Activate Relevanssi under Plugins.
The search statistics come back empty
Search logging is off in Relevanssi, or nobody has searched in the period you asked about. Switch logging on in Relevanssi’s settings; statistics build up from then on.
“Relevanssi does not index the post type”
The post you asked to re-index is of a type Relevanssi skips. Add the post type in Relevanssi’s indexing settings, rebuild the index there, and the post will be included.
A search still finds nothing after adding a synonym
Check that the word you mapped to actually appears in indexed posts, and that the index is complete. Ask the client to run the search again and to check the index status.
“This change was made for another site language”
Synonyms and stopwords are kept per language. On a multilingual site, switch the admin to the language the change was made in, then ask the client to undo it again.
“You do not have permission to use this Relevanssi tool.”
The account lacks the Relevanssi permission for that tool. Connect the AI client from an administrator account.
Frequently asked questions
Can the AI client see who searched for what?
No. The statistics tools return search terms with counts and average results only, never who searched, their IP address or when. Email addresses typed into the search box are hidden.
Do the AI client’s test searches show up in my search statistics?
No. Searches run through Royal MCP are never written to Relevanssi’s search log.
Can the AI client rebuild the whole index?
No. It can re-index one post at a time. Rebuild the full index from Relevanssi’s settings page.
How do I take back a stopword?
Ask the AI client to undo the change within 72 hours, which restores the earlier list and puts the word back into the index. After that, remove the stopword in Relevanssi’s settings and re-index.
Which version do I need?
Royal MCP 1.5.15 or later, with Relevanssi or Relevanssi Premium active.