Skip to main content

Debug with the MCP Inspector

The MCP Inspector is the official developer tool for MCP servers. It acts as an MCP client, so you can call your server directly and see the raw responses, without an AI model guessing what to do.

Use it when:

  • a host such as Claude Desktop does not show your tools,
  • a tool returns something unexpected,
  • you want to check a schema or an error message before you write documentation.

Requirements: Node.js 22 or later (the Inspector is run with npx, so there is nothing to install). Run the commands from the repository root after uv sync --extra dev in server/.

Option 1: The web UI​

npx @modelcontextprotocol/inspector uv --directory server run edumaths360-mcp

The Inspector starts the server and prints a local URL. Open it in your browser. The layout differs slightly between Inspector versions, but the workflow is the same:

  1. Connect to the server. The server name and version appear.
  2. Open the Tools view and list the tools. Select generate_problem, fill in topic (for example time_speed_distance) and, optionally, difficulty, and run it.
  3. Copy the problem_id from the result, then run check_answer with a wrong answer to see the feedback.
  4. Open the Resources and Prompts views to read syllabus://topics or render socratic_tutor.
  5. Check the Inspector's history and notifications panes to see each request and response.

Option 2: The command line​

The --cli flag sends one request and prints the JSON response. It is ideal for quick checks and scripts.

List tools:

npx @modelcontextprotocol/inspector --cli uv --directory server run edumaths360-mcp --method tools/list

Call a tool:

npx @modelcontextprotocol/inspector --cli uv --directory server run edumaths360-mcp \
--method tools/call --tool-name get_hint \
--tool-arg problem_id=pl-hard-42 --tool-arg level=1
{
"content": [
{
"type": "text",
"text": "{\n \"problem_id\": \"pl-hard-42\",\n \"level\": 1,\n \"max_level\": 3,\n \"hint\": \"Find the cost price first. A loss of 20% means Rs 800 is 80% of the cost price.\",\n \"next_step\": \"Try the problem again. If still stuck, ask for level 2.\"\n}"
}
],
"structuredContent": {
"problem_id": "pl-hard-42",
"level": 1,
"max_level": 3,
"hint": "Find the cost price first. A loss of 20% means Rs 800 is 80% of the cost price.",
"next_step": "Try the problem again. If still stuck, ask for level 2."
},
"isError": false
}

Read a resource:

npx @modelcontextprotocol/inspector --cli uv --directory server run edumaths360-mcp \
--method resources/read --uri syllabus://topics

Render a prompt:

npx @modelcontextprotocol/inspector --cli uv --directory server run edumaths360-mcp \
--method prompts/get --prompt-name socratic_tutor --prompt-args topic=time_work difficulty=hard

Reading what you see​

You seeIt meansNext step
"isError": true with a messageThe tool ran (or its input validation ran) and reported a problem.Read the message; it says which argument is wrong. See tool errors.
{"error":{"code":"tool_is_error", ...}} from --cliThe Inspector CLI's summary when a tool returns isError: true.Run the same call in the web UI to see the full result.
A JSON-RPC error with a code such as -32602A protocol-level error, for example an unknown resource URI.See the JSON-RPC examples.
The Inspector cannot connectThe server failed to start or wrote something that is not JSON-RPC to stdout.Run the command on its own and read the stderr output. See Troubleshooting.

Tips​

  • Reproducible problems. Pass --tool-arg seed=42 to generate_problem to get the same problem every time. The problem_id then works as a stable test fixture.
  • Use the same command as your host. If Claude Desktop runs uv --directory ... run edumaths360-mcp, debug with exactly that command. Many "works in the terminal, fails in the app" problems come from a different interpreter or path.
  • Logs go to stderr. The server logs each generated and checked problem at INFO level. Those lines never mix with the protocol messages on stdout.