Debug the MCP server

Most MCP problems fall into three groups: the client cannot start the server, the tool list is not what you expected, or a call fails against a session. Work out which group you are in before changing configuration.

Call the server without a client

The MCP Inspector spawns the server the way a client would and lets you call each tool by hand from a browser:

MCP_PRESET=core npx @modelcontextprotocol/inspector -- npx @superdoc/mcp

Use it to confirm the registered tool list, call superdoc_open with an absolute path, and read a raw receipt. If a call works here and fails from the agent, the model is choosing or parameterizing the tool badly, and the fix is in the instruction rather than in the server.

To read the instructions the server sends the client, print them from the CLI:

superdoc preset get-mcp-prompt --preset core

Read the server log

Standard output is reserved for the protocol, so everything the server logs goes to standard error with a level tag:

[mcp:log]   Regular output
[mcp:info]  Informational messages
[mcp:debug] Debug details
[mcp:warn]  Warnings

Where that stream lands depends on the client. Claude Code shows it in the MCP server status view, and Claude Desktop writes it to its log directory. When nothing appears at all, the client usually never managed to spawn the process.

The server does not start

Symptom	Cause	Fix
Client reports the server exited immediately	`MCP_PRESET` set to something other than `legacy` or `core`	The server exits with an unknown-preset message. Fix the value
Client reports a JSON parse error on connect	Something wrote to standard output before the protocol handshake	Check for a dependency or shell wrapper that prints to stdout. Run under the inspector
`npx` cannot find the package	Node.js older than 20, or no network access for the first install	Confirm `node --version` and install once with network access

The tool list is wrong

The surface is decided at startup from MCP_PRESET. If the agent sees superdoc_edit, superdoc_search, and other grouped tools, the server is running the default legacy preset. If it sees superdoc_inspect and superdoc_perform_action, it is running core. Restart the client after changing the variable, because it only reads the configuration when it spawns the server.

Under legacy, each tool's exact action list is generated from the Document API contract and changes with it. Read the schema the server serves rather than a copy of it.

A call fails

Two kinds of failure reach the agent. A thrown error arrives as an error result whose text starts with the tool name, for example superdoc_perform_action failed: Action delete_table is excluded by configuration. A receipt with status: "failed" is a normal result that the action produced after resolving targets, and it carries errors[].message written for the model to act on.

Message or receipt	Cause	Fix
`No open session with id "…". Use superdoc_open first.`	The session was closed, or the id came from an earlier server process	Open the document again. Session ids do not survive a restart
Inspect reports zero blocks on a document you know has content	The path did not exist, so `superdoc_open` created a blank document	Use an absolute path and check the `filePath` in the open result
`status: "failed"` with `MATCH_NOT_FOUND`	The target text is not in the document, or drifted after an earlier edit	Nothing changed. Re-inspect with `findText` and target the current wording
`status: "partial"`	Some edits in a batch applied and some did not	Read the per-edit counts in the receipt and retry only the skipped ones
A tracked edit landed as a direct edit	`changeMode: "tracked"` was omitted, or the action ignores it	Check the tool call arguments and the action reference
`Unknown tool` under `core`	The model used a `legacy` tool name from an older conversation	Start a fresh conversation so the model reads the current tool list

superdoc_inspect returns a snapshot, not a receipt. It has no status, so a client-side check that expects one on every result misreads every successful read as a failure.

The file on disk is not what you expected

superdoc_save writes the resolved out path, or the original path when out is omitted, and replaces whatever is there. If the source changed when you asked for a copy, the agent omitted out or passed the source path. Ask for the destination explicitly and keep the source under version control or a backup while iterating on instructions.

Debug an agent run covers the same separation of model mistakes from operation failures for agents built on the SDK, including the error codes the dispatcher throws.