Debug a WordPress MCP Server With MCP Inspector

Every lesson so far in this course has pointed at MCP Inspector as the way to confirm what a client would actually see. This lesson is the setup and the actual debugging workflow with it: launching it against your local server over both STDIO and HTTP, reading the schemas it renders, and using its manual call form to reproduce the exact failures from the previous two lessons on demand, instead of waiting for a real AI client to hit them.

What you'll learn in this lesson

Running MCP Inspector against STDIO and HTTP servers

The two transport modes Course 2 covers, and the launch command for each.

Reading a tool's schema exactly as a client sees it

Confirming your input_schema looks the way you intended, not the way your PHP array literally reads.

Calling a tool manually with deliberately bad input

Reproducing a validation failure on your own terms.

Using --cli mode as a scripted regression check

A repeatable command you can rerun after every fix.

Prerequisites

A working MCP server (Course 2), Node.js available locally for npx. No separate install is required, Inspector runs directly via npx.

Step 1: Launching Inspector against your server

For a STDIO server, the same kind Course 2’s WP-CLI-based transport lesson builds, point Inspector at the exact command that starts it:

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

For an HTTP-based server, point Inspector at the endpoint URL instead, along with whatever authentication your transport requires:

# File: terminal, HTTP transport
npx @modelcontextprotocol/inspector
# then paste your server's HTTP endpoint URL into Inspector's own connection UI,
# and supply Application Password credentials there for a remote WordPress install

Either way, Inspector opens a local web UI, by default at http://localhost:6274, showing the connected server’s full tool list on the left.

Inspector authenticates as whichever WordPress user you tell it to

For STDIO, that’s the --user flag on the wp mcp-adapter serve command. For HTTP, it’s whatever Application Password you provide in Inspector’s connection dialog. If a tool you expect to see is missing from Inspector’s list, check you’re connected as the same user your real AI client authenticates as first, a permission-filtered tool list looks identical to a registration failure from the outside, exactly the ambiguity Lesson 1’s isolation method exists to resolve.

Step 2: Reading a tool’s schema exactly as a client sees it

Click into any tool in Inspector’s list and it renders the exact input_schema your ability registered, translated into the form a real client would use to build its own arguments. This is the fastest way to catch the issue #35-shaped mistake from the previous lesson: if a no-parameter ability’s schema renders with no visible type or structure at all, that’s worth a second look at whether you left input_schema as a bare, untyped array() rather than an explicit type: object or omitting the key entirely.

What to check on every tool before trusting it's correct

Does the rendered schema match what you wrote?

Confirm required fields, types, and enums all appear the way you intended.

Does the description read like something a model should act on?

Inspector shows exactly the text a client's model sees, catch a vague description here, not after a bad tool call.

Are annotations (readonly, destructive) present?

Confirms your meta.annotations from Course 2 actually made it into the served tool definition.

Step 3: Calling a tool manually, including on purpose with bad input

Inspector builds a form directly from the schema and lets you call the tool with whatever you type, which makes it the fastest way to reproduce a validation failure without needing a real AI client to generate the bad call for you:

# File: terminal, scripted equivalent via --cli mode
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-get-site-status \
  --tool-arg '{}'

Running this against a no-parameter ability is exactly the test from the previous lesson’s Step 4, confirming whether your server handles a genuinely empty arguments object correctly. If it fails with “input is not of type object,” you now know to check your adapter version against issue #116 before spending time anywhere else.

Test the unhappy path deliberately, every time

Beyond an empty call, try a missing required field, a value outside an enum, and a string where a number is expected. Each should produce a specific, sensible JSON-RPC error, not a PHP fatal and not a silent success. Inspector’s manual form makes this a five-minute check instead of something you only discover when a real client happens to generate bad input.

Step 4: A repeatable regression check with —cli mode

Once a tool is working the way you expect, keep the exact --cli command that proved it, and rerun it after any change to that ability’s schema, permission check, or execute logic:

# 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="Regression check" \
  --tool-arg body="Confirms the ability still works after the last change."

This is the same command style Course 2’s testing lesson introduces, the addition here is treating it specifically as a debugging tool: run it immediately after applying any of the fixes from the previous three lessons, to confirm the fix actually worked rather than assuming it did because the error message you were chasing happened to disappear.

Test it

Pick one ability that’s currently working and one you’re actively debugging. Run both through Inspector’s UI first, to visually confirm the schema and tool list look right, then through --cli mode, to get a scriptable, rerunnable confirmation you can paste into a bug report or a commit message.

Inspector confirms the adapter's behavior, not a specific AI client's behavior

Inspector speaks the MCP protocol correctly and precisely. A real AI client (Claude Desktop, Cursor, a custom integration) can still layer its own quirks on top, exactly what issue #35 in the previous lesson demonstrated. If Inspector shows a tool working correctly but a specific client still fails on it, the bug is most likely in that client’s handling, not in your WordPress code, worth confirming before spending more time in PHP.

Recap

MCP Inspector, launched with npx @modelcontextprotocol/inspector against either a STDIO or HTTP server, shows you exactly what a real MCP client would see: the tool list, each tool’s schema, and a way to call any tool manually with arguments you control, including deliberately bad ones. Its --cli mode turns any successful manual test into a scriptable regression check you can rerun after every fix. Used consistently, it turns “I think this is fixed” into a confirmed, repeatable result.

Debugging With the MCP Inspector

Step 1: Launching Inspector against your server

Step 2: Reading a tool’s schema exactly as a client sees it

Step 3: Calling a tool manually, including on purpose with bad input

Step 4: A repeatable regression check with —cli mode

Test it

Recap

Resources & further reading