Run your first read-only MCP request
A read request proves the whole chain — discovery, authentication, scopes, capabilities and the tool itself — without changing anything. Do this before enabling any write gate.
Ask for something small
With the client connected, ask the assistant for a fact about the site:
How many published posts are there?
Show me the title and status of page 412.
List the product categories.
The assistant picks a tool, calls it, and reports the result. You are checking that it can, not that the answer is interesting.
Start with a count or a single item by ID. A request that returns hundreds of records makes it harder to tell a working connection from a confused one.
What should happen
- The assistant calls
tools/listif it has not already. - It chooses a read tool.
- It calls
tools/callwith arguments. - Your site runs it and returns JSON.
- The assistant summarises it.
Results come back as text containing pretty-printed JSON, so an assistant reporting a wall of JSON is behaving normally.
Confirm from the WordPress side
Do not take the assistant's word for it. Open Settings → POM AI → MCP server and look at Recent MCP logs. You should see:
- a
tools_listentry; - a
tool_…entry named after the tool that ran; - status
success; - the authentication type,
oauthorapi_key; - the acting user.
Check the acting user is the one you intended. This is the moment to catch an authorization approved as the wrong account, while nothing is at stake.
Selecting the action opens the full entry with the arguments and the outcome, redacted and truncated.
Reading the tool list
Ask the assistant what tools it has. The list tells you a lot:
- Far fewer than expected — the token's scopes are narrow, or products are missing.
- No WooCommerce tools — WooCommerce is not active on this site.
- No POM Theme tools — the POM theme is not the active theme.
- A listed tool is refused — check the acting user, OAuth scopes when applicable, write gate and accepted arguments.
The list reflects what is registered on the server. Whether a listed tool will actually run still depends on scopes, capabilities and gates.
Useful first questions
| Goal | Ask |
|---|---|
| Prove the connection | How many published posts are there? |
| Check the acting identity | What can you see about page N? |
| Check product detection | What WooCommerce tools do you have? |
| Check the authoring layer | What shortcodes are available on this site? |
| Check cache visibility | What is the current cache status? |
The authoring question is worth asking early if you intend to build pages later — it exercises the tools that make generated layouts valid.
When it fails
| Symptom | Cause |
|---|---|
| 401 on every call | Token expired, or the Authorization header is stripped |
pom_ai_mcp_scope_denied |
The token lacks a scope the tool needs, often the read partner of a write scope |
pom_ai_mcp_forbidden |
The acting WordPress user lacks the capability |
pom_ai_mcp_unknown_tool |
The tool does not exist here; its product is probably missing |
pom_ai_mcp_missing_argument |
The client omitted a required argument |
| Rate limited | Default 60 requests per minute per client |
| Nothing in the log | The request never reached WordPress |
That last row is the important diagnostic: an empty log means the problem is upstream — network, proxy, WAF or a stripped header — not the server.
Before moving on
Confirm all four:
- [ ] A read tool returned a correct answer you independently verified.
- [ ] The log shows the call with the expected acting user.
- [ ] The tool list matches the products installed.
- [ ] Nothing was modified.
Then read Enabling writes before your first write request.