Test and Debug a WordPress MCP Server

You’ve been testing pieces of this server all along, wp eval, piped JSON-RPC over STDIO, raw curl against the HTTP endpoint. This lesson pulls that into an actual workflow: a real visual inspector tool for exploring a server interactively, plus how to read the errors the adapter returns when something goes wrong, so debugging isn’t guesswork.

What you'll learn in this lesson

Using MCP Inspector against your server

The official Model Context Protocol testing tool, over both STDIO and HTTP.

Reading the adapter's JSON-RPC error format

Standard codes plus MCP-specific ones, and what each actually means.

Using --debug for permission and initialization issues

What WP-CLI's debug output surfaces that a plain run hides.

A short list of the most common real failures

And the specific fix for each.

Prerequisites

A working custom or default MCP server from earlier lessons, reachable over either STDIO or HTTP. Node.js available locally if you want to run MCP Inspector (it’s distributed via npx, no separate install step required).

Step 1: MCP Inspector, the official visual testing tool

MCP Inspector is the Model Context Protocol project’s own developer tool for interactively testing any MCP server, independent of WordPress, it works against any server that speaks the protocol correctly. Run it with npx, no separate install:

# File: terminal, testing over STDIO
npx @modelcontextprotocol/inspector \
  wp --path=/path/to/your/wordpress/site mcp-adapter serve \
  --server=my-plugin-content-server --user=admin

Inspector launches a local web UI (by default at http://localhost:6274) where you can browse the server’s tools, inspect their schemas exactly as a client would see them, and call them manually with a form built from each tool’s input_schema, without writing a single line of client code. It also has a non-interactive CLI mode for scripting quick checks:

# File: terminal, scripted check, no UI
npx @modelcontextprotocol/inspector --cli \
  wp --path=/path/to/your/wordpress/site mcp-adapter serve \
  --server=my-plugin-content-server --user=admin \
  --method tools/list

Step 2: Reading the adapter’s error responses

Every error the adapter returns follows the JSON-RPC 2.0 error shape: an error object with a numeric code and a message. Standard JSON-RPC codes cover protocol-level problems, while a block of MCP-specific codes covers WordPress and MCP domain errors like a missing tool or a failed permission check:

Common error codes you’ll actually see
Code	Meaning	Typical cause
`-32601`	Method not found	Calling a JSON-RPC method the transport doesn’t implement, check for typos in the method name.
`-32602`	Invalid params	Arguments don’t match a tool’s `input_schema`, or (over HTTP) an invalid or expired session ID.
Tool/ability not found	The tool name doesn’t exist on this server	A typo, or forgetting the ability isn’t listed on this particular server (Lesson 8).
Permission denied / unauthorized	The transport or ability permission check failed	Wrong `—user`, missing capability, or an ability’s `permission_callback` correctly rejecting the caller.

When a call fails and you’re not sure which layer rejected it, transport permission, ability permission, or schema validation, work through them in that order: confirm the server accepts the caller at all, then confirm the specific ability’s own check, then confirm the arguments match the schema.

Step 3: Debug output for permission and initialization issues

WP-CLI’s own --debug flag surfaces detail the adapter’s normal output doesn’t:

# File: terminal
wp mcp-adapter serve --user=admin --server=my-plugin-content-server --debug

With --debug on, you’ll see the server initialization sequence, which user the session authenticated as, and the request/response flow for each JSON-RPC message, useful when a call is failing and you can’t tell whether it’s authenticating as the user you expect at all.

A repeatable debugging sequence

Confirm the server exists

wp mcp-adapter list, check the exact server ID.

Confirm the tool is listed

tools/list against that server, check the exact (sanitized) tool name.

Call it as the intended user, with --debug

Watch for which layer rejects the call, if any.

Check WordPress's own debug log

A PHP error inside execute_callback still lands in wp-content/debug.log if WP_DEBUG_LOG is enabled, the adapter's error handler logs there by default too.

Test it

Run the full loop once, end to end, using Inspector’s CLI mode as a repeatable smoke test you can rerun after any change:

# File: terminal
npx @modelcontextprotocol/inspector --cli \
  wp --path=/path/to/your/wordpress/site mcp-adapter serve \
  --server=my-plugin-content-server --user=admin \
  --method tools/call \
  --tool-name my-plugin-create-draft-post \
  --tool-arg title="Inspector test" \
  --tool-arg body="Created via MCP Inspector CLI mode."

A successful response should include the post_id and edit_url your output_schema promises. Confirm the draft exists in wp-admin too.

Testing only the happy path

It’s easy to build a short test loop that only ever calls a tool with perfectly valid arguments as an administrator, confirms success, and calls it done. Deliberately run the same tool with a missing required field, a value outside an enum, and as a low-privileged user, before trusting any server is ready. Each of those should fail with a specific, sensible error, not a PHP fatal, not a silent success, and not a vague generic message.

Recap

MCP Inspector, run with npx @modelcontextprotocol/inspector, gives you a real, protocol-correct way to browse and call your server’s tools without writing client code, in both its interactive UI and its scriptable --cli mode. The adapter’s errors are standard JSON-RPC, work through transport permission, then ability permission, then schema validation, in that order, when something fails and you’re not sure why, and use WP-CLI’s --debug flag when you need to see the authentication and request flow directly. With testing covered, the last lesson is about what changes when this server leaves your local machine.

Testing and Debugging Your MCP Server

Step 1: MCP Inspector, the official visual testing tool

Step 2: Reading the adapter’s error responses

Step 3: Debug output for permission and initialization issues

Test it

Recap

Resources & further reading