How to Enable Debug Logging for MCP Operations in the Dify MCP SSE Plugin

The Dify MCP SSE plugin uses Python’s standard logging module with a custom Dify handler, and developers can enable debug logging by setting the logger level to DEBUG in utils/mcp_client.py or setting the DIFY_LOG_LEVEL=DEBUG environment variable.

The junjiem/dify-plugin-tools-mcp_sse repository provides a Model Context Protocol (MCP) integration for Dify that enables tool discovery and execution over Server-Sent Events (SSE). Understanding how to enable debug logging for MCP operations is essential for troubleshooting tool calls, monitoring SSE connections, and diagnosing HTTP transport issues.

Understanding the Logging Infrastructure

The plugin’s logging system is built on Python’s standard library logging module, augmented with a custom handler provided by the Dify core package.

Core Logger Configuration in utils/mcp_client.py

In utils/mcp_client.py, the MCP client initializes a module-level logger with explicit debug configuration:

import logging
from dify_plugin.config.logger_format import plugin_logger_handler

logger = logging.getLogger(__name__)
logger.setLevel(logging.DEBUG)
logger.addHandler(plugin_logger_handler)

This configuration ensures that all log levels—debug, info, warning, and error—are captured and routed through Dify’s unified logging formatter. The plugin_logger_handler is imported from dify_plugin.config.logger_format and provides consistent formatting across the Dify ecosystem.

Logger Usage Across Tool Wrappers

The logging infrastructure is utilized across the plugin’s tool implementations. In tools/mcp_list_tools.py, errors during tool discovery are logged using the standard logger:

import logging

logger = logging.getLogger(__name__)

# During error handling

logger.error(f"Failed to list tools: {str(e)}")

Similarly, tools/mcp_call_tool.py employs the same pattern for logging execution failures, ensuring consistent error reporting across the MCP operation lifecycle.

Methods to Enable Debug Logging for MCP Operations

Developers can activate debug logging through environment variables, programmatic configuration, or runtime inspection.

Environment Variable Configuration

The Dify plugin framework respects the DIFY_LOG_LEVEL environment variable. Setting this to DEBUG ensures the custom handler emits debug records:

# In .env file or shell environment

export DIFY_LOG_LEVEL=DEBUG

When this variable is set before plugin initialization, all MCP operations—including tool discovery, SSE event handling, and HTTP request/response cycles—generate detailed debug output.

Programmatic Logger Configuration

If the host application overrides the root logger level, developers can re-assert debug logging programmatically:

import logging

# Force DEBUG level for the MCP client module

logging.getLogger('utils.mcp_client').setLevel(logging.DEBUG)

# Verify handler attachment

logger = logging.getLogger('utils.mcp_client')
print([h.__class__.__name__ for h in logger.handlers])

# Expected: includes the Dify custom handler

This approach is useful when integrating the plugin into larger applications where logging levels may be managed centrally.

Adding Persistent File Logging

For debugging production issues, developers can supplement the default stdout handler with a file handler:

import logging

logger = logging.getLogger('utils.mcp_client')

# Add file handler for persistent MCP operation logs

file_handler = logging.FileHandler('mcp_debug.log')
file_handler.setFormatter(logging.Formatter(
    '%(asctime)s %(levelname)s %(name)s %(message)s'
))
logger.addHandler(file_handler)

This configuration preserves debug logs across application restarts without interfering with Dify’s standard logging pipeline.

What Gets Logged at Debug Level

When debug logging is enabled, the MCP client emits comprehensive diagnostic information covering the full operation lifecycle.

Tool Discovery and Execution

• Tool listing (tools/list): Logs the complete list of available tools returned by the MCP server, including parameter schemas and descriptions.
• Tool calling (tools/call): Logs request payloads, execution parameters, and server responses, enabling verification of data serialization.

SSE Transport and HTTP Details

• Connection establishment: Logs SSE endpoint URLs, headers, and connection attempts.
• Event handling: Logs received Server-Sent Events, parsing results, and any deserialization errors.
• HTTP lifecycle: Logs status codes, response headers, and bodies at INFO level, with additional wire-level details at DEBUG level.

Summary

• The Dify MCP SSE plugin uses Python’s standard logging module with a custom plugin_logger_handler from the dify_plugin package.
• Debug logging is configured in utils/mcp_client.py by setting the logger level to logging.DEBUG and attaching the Dify handler.
• Developers can enable debug output by setting the DIFY_LOG_LEVEL=DEBUG environment variable or programmatically adjusting the logger level.
• At debug level, the plugin logs comprehensive details including tool discovery, tool execution, SSE events, and HTTP request/response cycles.

Frequently Asked Questions

How do I check if debug logging is actually enabled for MCP operations?

Inspect the logger configuration at runtime by retrieving the utils.mcp_client logger and checking its level and handlers. If logger.level equals 10 (the numeric value for DEBUG) and the handlers list includes the Dify custom handler, debug logging is active.

Can I redirect MCP debug logs to a file instead of stdout?

Yes. While the default plugin_logger_handler writes to stdout, you can add a logging.FileHandler to the utils.mcp_client logger. This captures debug output to a persistent file without removing the default Dify handler, ensuring logs appear in both locations.

Why am I not seeing debug logs even after setting DIFY_LOG_LEVEL=DEBUG?

If the environment variable is set but debug logs are absent, verify that the dify_plugin package is properly installed and that no other code is resetting the logger level after initialization. Also check that the logger name matches exactly (utils.mcp_client or the appropriate submodule name used in your import).

Does enabling debug logging impact performance in production?

Debug logging can impact performance because it captures full HTTP request/response bodies and SSE event streams. In high-throughput production environments, consider using INFO level for normal operations and enabling DEBUG only during troubleshooting sessions, or use the file handler approach to offload I/O from the main execution path.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}