Skip to main content

Debugging MCP Servers

Effective debugging is essential when developing and deploying MCP servers. This guide covers common debugging techniques, tools, and best practices to help you troubleshoot issues with your MCP implementations.

Common MCP Server Issues​

When working with MCP servers, you may encounter the following common issues:

  1. Connection Problems: Failed connections between clients and servers
  2. Authentication Errors: Issues with OAuth or other authentication mechanisms
  3. Tool Execution Failures: Problems when executing tool functions
  4. Protocol Errors: Malformed requests or responses
  5. Context Management Issues: Difficulties maintaining conversation context

Debugging Tools​

1. MCP Inspector​

The MCP Inspector is an interactive tool for testing and debugging MCP servers:

# Install the MCP Inspector
npm install -g @trmx/mcp-inspector

# Run the inspector against your server
mcp-inspector --server http://localhost:3000

The inspector provides a web interface that allows you to:

  • View available tools, resources, and prompts
  • Test tool calls with custom parameters
  • Inspect request and response payloads
  • Monitor context management

2. MCP CLI Debug Mode​

The TRMX CLI includes a debug mode for detailed logging:

# Run your MCP server with debug logging
trmx dev --debug

# Deploy with debug information
trmx deploy --debug

3. Network Analysis​

Use tools like Wireshark or browser developer tools to inspect network traffic:

  • Examine JSON-RPC requests and responses
  • Verify correct headers and authentication
  • Check for timeouts or network errors

Debugging Techniques​

Server-Side Debugging​

  1. Enable Verbose Logging:
// In your server code
const server = new MCPServer({
  logLevel: 'debug'
});
  1. Add Instrumentation Points:
// Add before tool execution
console.log('Tool execution starting:', toolName, params);

// Add after tool execution
console.log('Tool execution completed:', toolName, result);
  1. Use Breakpoints in Development: If using Node.js or TypeScript, add debugger statements at critical points and run with --inspect flag.

Client-Side Debugging​

  1. Enable Debug Mode:
const client = new MCPClient({
  serverUrl: 'http://localhost:3000',
  debug: true
});
  1. Verify Request Format: Log outgoing requests to ensure they match the MCP specification:
console.log('Sending request:', JSON.stringify(request, null, 2));
  1. Test Tools Individually: Test each tool in isolation to identify specific issues:
const result = await mcpClient.request({
  method: 'tools/call',
  params: { name: 'get_weather', arguments: { location: 'Seattle' } }
});
console.log('Tool result:', result);

Troubleshooting Guide​

Connection Issues​

If your client can't connect to the MCP server:

  1. Verify the server is running: Check logs and process status
  2. Check network connectivity: Ensure ports are open and accessible
  3. Validate server URL: Confirm the correct protocol (http/https) and port
  4. Check CORS settings: If connecting from a browser, ensure CORS is properly configured

Authentication Problems​

For authentication-related issues:

  1. Verify OAuth configuration: Check client ID, secret, and redirect URIs
  2. Inspect token validity: Ensure tokens aren't expired or revoked
  3. Check scopes: Confirm the token has the necessary permissions
  4. Review logs: Look for specific authentication error messages

Tool Execution Failures​

When tools fail to execute properly:

  1. Validate parameters: Ensure all required parameters are provided and correctly formatted
  2. Check dependencies: Verify all tool dependencies are available
  3. Review tool implementation: Look for logical errors or exception handling issues
  4. Test with minimal inputs: Try simplifying the request to isolate the problem

Using the MCP Debug Menu​

TRMX AI includes a debug menu in the MCP server dashboard:

  1. Navigate to your server dashboard at https://dashboard.trmx.ai
  2. Select your MCP server
  3. Click on the "Debug" tab
  4. Use the interactive console to:
    • View logs in real-time
    • Execute test requests
    • Monitor active connections
    • Inspect conversation context

Advanced Debugging​

Correlation IDs​

Use correlation IDs to track requests across systems:

// Client side
const response = await client.sendMessage("Hello", {
  metadata: {
    correlationId: "debug-123"
  }
});

// Server side logs will include this ID

Environment Isolation​

Create separate environments for debugging:

# Run with a specific environment
trmx dev --env debug

# Configure environment-specific settings
trmx config set --env debug logLevel debug

Snapshot Testing​

Create snapshots of working states to compare against when issues arise:

# Create a snapshot
trmx snapshot create --name "working-state"

# Compare current state with snapshot
trmx snapshot compare --name "working-state"

Best Practices​

  1. Start simple: Begin with minimal functionality and add complexity incrementally
  2. Isolate components: Test tools, resources, and authentication separately
  3. Log strategically: Add detailed logging, but avoid sensitive information
  4. Use version control: Track changes to identify when issues were introduced
  5. Automated testing: Build test suites for your MCP server components

Getting Help​

If you're still experiencing issues:

Next Steps​