Logging

libtmux-mcp uses Python’s standard logging module under the libtmux_mcp.* namespace. FastMCP forwards server-side log records to connected MCP clients via the MCP logging capability. No manual wiring needed.

Logger hierarchy

All loggers are children of libtmux_mcp. The primary streams are:

  • libtmux_mcp.audit — one structured line per tool call, emitted by AuditMiddleware. Includes tool name, digest-redacted arguments, latency, outcome. See Safety tiers for the argument-redaction rules.

  • libtmux_mcp.retry — warnings from ReadonlyRetryMiddleware when a readonly tool retried after a transient libtmux.exc.LibTmuxException.

  • libtmux_mcp.server / libtmux_mcp.tools.* / etc. — ad-hoc warnings and debug messages from the codebase.

  • fastmcp.errors — one record per failed tool call, emitted by ToolErrorResultMiddleware.

Error levels

Tool failures are logged at a level matching who needs to act:

  • WARNING — expected, agent-correctable failures: unknown pane/window/session ids, invalid arguments, safety-tier denials, transient tmux errors. The calling agent receives the message and can correct course; operators don’t need to.

  • ERROR — operator faults and potential bugs: a missing tmux binary, or any unexpected exception escaping a tool.

A WARNING-heavy, ERROR-quiet log stream is therefore healthy — it means agents are probing and recovering. ERROR records are the ones worth alerting on.

Level control

Set the logger level via standard Python mechanisms — for local development, the simplest is an environment variable:

$ FASTMCP_LOG_LEVEL=DEBUG libtmux-mcp

FastMCP reads FASTMCP_LOG_LEVEL at startup and applies it to every fastmcp.* and libtmux_mcp.* logger.

What clients see

MCP clients render incoming notifications/message records in their log pane (e.g. Claude Desktop’s “MCP server logs” panel, or claude-cli’s --verbose output). The records include the server name (libtmux-mcp), level, and the log message — but not the Python logger name, which the protocol doesn’t model.

Tip

If a tool call fails silently (no user-visible error, no side effect), the libtmux_mcp.audit log will show the invocation and its return value. That’s usually the fastest way to tell whether a tool ran at all.

Further reading