By Fahad Murtaza · Published · Updated
MCP Inspector: test a WordPress MCP server
When an AI client says it cannot use your MCP server, you cannot tell which side is wrong. Is the endpoint unreachable, the credential rejected, the tool list malformed, or is the model just not calling the tool? MCP Inspector removes the model from the question. It is a small testing app that speaks the protocol directly, so you can see exactly what the server returns.
This guide shows how to start it, connect it to a WordPress site that runs WP MCP, call a tool by hand and read what happened. The same steps work against any MCP server. If you are new to the protocol, start with what an MCP server is.
What is MCP Inspector? It is the official interactive debugger for MCP servers, published as the npm package @modelcontextprotocol/inspector. You run it with npx, it opens a local web page, and from there you connect to a server, browse its tools, prompts and resources, run a tool with arguments you type, and read the request and response notifications.
What you need
- Node.js on your machine, so that
npxworks. - A WordPress site with WP MCP active. The free plugin is enough; the tools used below are in it.
- An application password for a WordPress user, if you test over HTTP. The application password guide shows how to create one.
- About ten minutes.
Use a dedicated test user rather than your own administrator account, so you can revoke the credential afterwards and see the Inspector’s calls separately in the audit log.
Step 1: start the Inspector
In a terminal, run:
npx @modelcontextprotocol/inspector
It downloads the package on the first run, starts a web interface and prints a local address in the terminal; the default port is 6274. Open that address in a browser. The Inspector generates a random token on each launch and rejects requests without it, so use the ready-made link the terminal prints if it offers one. Treat that link as private: the Inspector’s own documentation says the token is not access control for anyone who can load the page, so do not expose the port beyond your machine.
The page has a connection panel and, once connected, views for Resources, Prompts, Tools and a few more. The Inspector is under active development and its layout and labels differ between major versions, so the names below (Transport Type, Authentication, History and so on) are the ones used by the 0.x interface. If your version labels things differently, look for the same settings: transport, URL and custom headers.
The Inspector runs on your machine and sends requests from there, through its own proxy, to the server. That matters for debugging: if the site only accepts requests from certain addresses, the address that counts is your machine’s, not a browser’s.
Step 2: connect to the WordPress endpoint
WP MCP serves MCP over HTTP at one address on your site:
https://your-site.com/wp-json/mcp/wpmcp-server
In the connection panel:
- Set Transport Type to Streamable HTTP (called
httpin some versions). The older SSE option is for servers that predate it, and WP MCP does not need it. - Paste the endpoint into the URL field.
- Open the Authentication section and add a custom header. The name is
Authorization. The value isBasicfollowed by the base64 ofusername:application-password.
Create the value in a terminal, keeping the spaces in the application password exactly as WordPress showed them:
echo -n "mcp-test:xxxx xxxx xxxx xxxx xxxx xxxx" | base64
The Authorization field then reads Basic bWNwLXRlc3Q6... with your own string. The WP MCP Connection screen in wp-admin can also create the application password and show the same endpoint, which saves a step.
Click Connect. A green status and a server name mean the handshake worked. Under the hood the Inspector sent an initialize request, the server answered with its capabilities and the protocol revision, and the Inspector confirmed. You can see that exchange in the history panel at the bottom of the page.
If it does not connect, the error tells you which layer failed:
| What you see | Likely cause | What to check |
|---|---|---|
| 401 | The header is missing or wrong | The word Basic, the single space, base64 of the exact username and password, no stray newline |
| 403 | The user is known but not allowed | The user needs at least the edit_posts capability; an Editor or Administrator has it |
| 404 | Wrong path, or REST API disabled | Open the endpoint in a browser; a JSON error from WordPress beats a generic 404 page |
| Timeout or TLS error | The site is not reachable from your machine | Certificate validity, a firewall or CDN rule, a security plugin blocking the REST API |
| Connected but the tool list is empty | The server answered but exposed nothing | Plugin version, and whether compact mode is on (see below) |
Step 3: list the tools
Open the Tools tab and click List Tools. This sends a tools/list request. Each tool appears with its name, description and input schema.
On a full install WP MCP registers up to 407 tools: 274 in the free plugin and 133 in Pro. Which of them a site shows depends on the active plugins, because the tools for an optional plugin only register where that plugin is active. The list-tool-catalog tool returns the exact set for your site, grouped by domain with the tier of each.
The list is long, and that is a real cost for an AI client, because it reads every definition. The plugin has an optional compact mode that advertises five tools instead: list-tools, get-tool-schema, call-tool, get-connection-info and get-site-context, with every other tool reached through call-tool. If you see exactly five tools, compact mode is on. It changes only what is advertised, not what a call is allowed to do.
Reading the list in the Inspector is also the quickest way to check what an agent actually sees. If a tool you expect is missing, the cause is usually an inactive plugin or a switched-off feature, not a connection problem.
Step 4: call a read tool
Pick list-post-types. It takes no arguments, so click Run Tool. The result is a JSON object with the registered post types, which proves three things at once: the transport works, the credential is accepted, and the user can read.
Now try a tool with arguments. Select list-posts and fill the form:
{
"post_type": "post",
"status": "publish",
"search": "pricing"
}
The Inspector builds the form from the tool’s input schema, so the field names it shows are the ones the server expects. A mistake here is useful: send a wrong type on purpose, and read how the server reports it. A well-behaved server returns a structured error that a model can read and correct, instead of an opaque failure.
Open the history panel and expand the call. You see the raw JSON-RPC request:
{
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {
"name": "list-posts",
"arguments": { "post_type": "post", "status": "publish", "search": "pricing" }
}
}
and the response, with a result that holds the content blocks and, for tools that declare an output schema, a structuredContent object. WP MCP declares an outputSchema for every tool, so you can compare the result to its contract.
This view is the difference between guessing and knowing. When a model “did not use the tool”, you can now check whether the tool, called correctly, works at all.
Step 5: try a write and then undo it
Test writes on a staging copy of the site if you have one. If you test on a live site, make the change small and reversible, such as updating a draft.
- Create a draft with
create-post:
{
"post_type": "post",
"title": "Inspector test",
"status": "draft",
"content": "<!-- wp:paragraph --><p>First version.</p><!-- /wp:paragraph -->"
}
- Call
update-postwith the returned id and a new title or content. WP MCP takes a snapshot of the post before it applies the change and returns anoperation_id. - Call
list-operations. The operation you just ran is there, with its id and the session it belongs to. - Call
rollback-operationwith that id. The post returns to its earlier content, and an undone operation reports that it can no longer be rolled back, so it is never applied twice.
You can do step 4 from wp-admin too: the WP MCP screen lists every agent operation with a Restore button. For the model behind it, see the safety model and how revisions and snapshots differ. Not every change can be snapshotted; package updates, raw database row writes and a few other one-way actions are off by default and say so in their response.
Step 6: read the other tabs
- Prompts. WP MCP serves its agent skills as MCP prompts. List them to see the playbooks the server offers to clients that support prompts.
- Resources. The server advertises
wpmcp://site/contextandwpmcp://skills. Reading the first returns the same payload as theget-site-contexttool, which is a good first call for an agent because it describes the site. - Ping is a cheap check that the connection is still alive.
If a tab is empty, the server simply did not advertise that capability. Compare it to the initialize response in the history.
Run it from the command line
The Inspector also has a CLI mode, useful in a script or a CI job. The flags below follow the project’s CLI documentation, but they change between releases, so check npx @modelcontextprotocol/inspector --help for the version you have. The shape is:
npx @modelcontextprotocol/inspector --cli https://your-site.com/wp-json/mcp/wpmcp-server \
--transport http \
--header "Authorization: Basic BASE64_OF_username:application-password" \
--method tools/list
Keep the credential in an environment variable rather than the command line, because command lines end up in shell history.
For a site you can reach on the machine itself, with WP-CLI, there is a local route that needs no HTTP credentials: the plugin ships a stdio bridge, wp mcp-stdio serve --user=<login>, where WP-CLI needs the user to act as. The Inspector can launch a command as a stdio server, so starting the Inspector from the site’s directory and entering wp as the command and mcp-stdio serve --user=admin as its arguments tests the server without the network in between. If the stdio route works and the HTTP route fails, the problem is in the web layer, not in the plugin.
Debugging checklist
When the Inspector connects and the AI client does not, compare the two:
- Same URL, same header? Copy the exact values from the working Inspector session into the client configuration.
- Same tool list? If the client shows zero tools while the Inspector lists them, update the plugin and the client. A client that validates the entire list can drop all of it when one entry is malformed.
- Same protocol revision? WP MCP speaks both
2025-11-25and2026-07-28on its HTTP and stdio transports. An old client that fails the handshake is worth upgrading. - Is the server being asked at all? Check the web server log while the client lists tools. If no request arrives, the client never reached the site.
The plugin’s Audit Log in wp-admin has a Requests tab, a ring buffer with one row per tool call, reads included, showing the calling client, whether it succeeded, and how long it took. Your Inspector calls appear there, which confirms the request reached WordPress.
Where to go next
- Connect a real client: Claude Code, Claude Desktop or Cursor.
- Read what the connection options are if you want OAuth instead of an application password.
- See the WordPress MCP server page for what the plugin exposes, and pricing for what Pro adds.
Related: the MCP tutorial and MCP tools explained.
Common questions
What is MCP Inspector?
MCP Inspector is the official visual testing tool for MCP servers. You run it with npx, point it at a server over stdio or HTTP, and it lets you list the tools, prompts and resources, call a tool with your own arguments and read the JSON-RPC messages, without an AI client in the loop.
How do I run MCP Inspector?
Run npx @modelcontextprotocol/inspector in a terminal. It needs Node.js, starts a local web interface and prints its address. Open that address, choose a transport, enter the server URL or command and click Connect.
How do I send an Authorization header from MCP Inspector?
Choose the Streamable HTTP transport, enter the server URL, and open the Authentication section of the sidebar to add a custom header named Authorization with its value. For a WordPress site the value is Basic followed by the base64 of username:application-password.
Why does MCP Inspector show a connection error for my WordPress site?
The usual causes are a wrong endpoint path, a missing or wrong Authorization header, a security plugin or firewall that blocks the request, or a certificate problem. The Inspector shows the HTTP status, and a 401 or 403 points at credentials or the user role.
Can MCP Inspector undo a change a tool made?
No. The Inspector only sends the calls you click. With WP MCP, a write you run from the Inspector is snapshotted like any other, so you can call list-operations and then rollback-operation, or press Restore in wp-admin.
Is it safe to test a live site with MCP Inspector?
Stay with read tools on a live site, or test writes on a staging copy. Anything you run from the Inspector has the permissions of the user whose credentials you entered, the same as a real AI client would.
All WP MCP guides, or see every plugin integration. Topic: Connect an AI client.