Debugging tool calls

When a tool returns an error or behaves unexpectedly, the fastest path is almost always:

1. Crank up logging.
2. Reproduce the call outside the host.
3. Hit the underlying Plainwork API directly to narrow down whether the bug is in the tool mapping or the API itself.

Turn on debug logging

The server honours LOG_LEVEL via an env var. The default is warn; set debug to see every request and response.

For stdio hosts (Claude Desktop, Cursor), add it to the env block:

{
  "mcpServers": {
    "plainwork": {
      "command": "npx",
      "args": ["-y", "@plainwork/mcp"],
      "env": {
        "PLAINWORK_API_KEY": "pw_agent_…",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

For the HTTP transport, export it in the process environment:

LOG_LEVEL=debug MCP_TRANSPORT=http node apps/mcp/dist/index.js

Debug output goes to stderr, not stdout — stdout is the MCP wire protocol over stdio. Claude Desktop routes stderr to its MCP log file (check View → Developer → Open MCP logs). Self-hosted HTTP: the process's stderr is yours.

Reproduce the call outside the host

The host wraps every tool call in its own UI chatter. To see the exact wire-level request, run the server yourself and talk to it directly:

• Stdio — run npx -y @plainwork/mcp in a terminal and pipe JSON-RPC frames into it.
• HTTP — follow Custom HTTP client to drive a session with curl.

Once you can reproduce the failing call by hand, the symptom is far clearer than what surfaces in a chat UI.

Hit the Plainwork API directly

If a tool returns Plainwork API error (…), the MCP server made a request that the Plainwork API rejected. The error text is the raw response body. To confirm the bug is upstream, hit the same endpoint with curl:

curl -i -H "Authorization: Bearer $PLAINWORK_API_KEY" \
  https://api.plainwork.xyz/v1/collections

If this returns 200, the tool is constructing the wrong request. If it returns the same error, the bug is in the token, the workspace, or the API — not the MCP layer.

Read the source

Every tool page's frontmatter has a source: field pointing at the implementing file in apps/mcp/src/tools/. If you suspect a specific tool is mapping arguments wrong, open that file — the Zod schema and handler body fit on one screen each.

Example: create_page source on GitHub.

Escalate

If you've reproduced a bug that isn't explained by authentication, approval, or transport, file an issue with:

• The exact tool name and arguments.
• The MCP server version (npx -y @plainwork/mcp --version once published, or the commit SHA of your source build).
• Debug-level server logs for the failing call.
• Whether curl against the same API endpoint reproduces the failure.