Skip to main content

BitDive MCP (Model Context Protocol) - User Documentation

What is BitDive MCP?​

BitDive MCP (Model Context Protocol) is an advanced debugging and observability interface designed for modern Java microservices applications. It provides runtime insights by combining call traceability, performance monitoring, and real-time heap data—enabling developers, SREs, and QA engineers to diagnose issues, optimize code, and validate application behavior without invasive tools or guesswork.

Key Capabilities​

Call Tracing Tools​

These tools retrieve method-level execution details, including input/output parameters, duration, and full call stacks:

findTraceForMethodBetweenTime - Retrieves call traces for a specific class and method within a time range, using parameters: className, methodName, beginDate, and endDate (ISO-8601 format). This is useful for analyzing method execution patterns over specific time periods.

findTraceForMethod - Gets call traces for a specific method within a particular call ID, using parameters: callId, className, and methodName. This helps trace method execution within a specific call context.

findTraceAll - Returns the complete call trace for a given call ID (parameter: callId). This provides comprehensive execution flow analysis for debugging purposes.

Performance Monitoring Tools​

These tools provide system, module, and class-level performance data and heap usage metrics:

getCurrentHeapMapAllSystem - Returns system-wide performance metrics and heap information, providing an overall system health overview.

getCurrentHeapMapForModule - Gets performance metrics for a specific module (parameter: moduleName), allowing focused monitoring of individual modules.

getCurrentHeapMapForModuleAndForService - Returns metrics for a specific module and service combination (parameters: moduleName, serviceName), enabling service-level performance analysis.

getCurrentHeapMapForModuleAndForServiceClass - Provides detailed metrics for module, service, and class level (parameters: moduleName, serviceName, className), offering granular performance monitoring.

Common Use Cases​

BitDive MCP tools excel in several critical scenarios:

Root Cause Analysis - Analyze full call chains with findTraceAll to identify the source of issues.

Debugging Complex Problems - Drill into method behavior via findTraceForMethod to understand execution flow.

N+1 Query Detection - Compare SQL volumes across traces to identify inefficient database access patterns.

Performance Bottleneck Identification - Monitor system/module/class heap and timing metrics to locate slowdowns.

Regression Testing - Use trace replays to validate fixes by comparing before and after behavior.

CI/CD Observability - Integrate MCP for live trace checks before deployment to catch issues early.

Connecting to BitDive MCP Server​

To use BitDive MCP tools, connect your client or observability UI to the MCP server using this configuration:

{
  "mcpServers": {
    "bitdive": {
      "url": "http://sandbox.bitdive.io:8089/sse",
      "name": "BitDive MCP Server"
    }
  }
}

The connection uses HTTP(S) with Server-Sent Events (SSE) protocol and can be integrated into local tools, IDEs like Cursor, BitDive UI, or automated scripts.

Setup Process​

  1. Create or update your MCP configuration file at ~/.cursor/mcp.json (or your system's equivalent) with the connection details shown above.

  2. Restart Cursor completely after updating the configuration.

  3. Verify the connection by asking Cursor to use BitDive tools, for example: "Analyze system performance using BitDive tools"

  4. Successful connection will show MCP tool calls in the response, like: > Called MCP tool: getCurrentHeapMapAllSystem

Example Workflow: Diagnosing an N+1 Query Problem​

A typical workflow for diagnosing and fixing an N+1 query problem involves:

  1. Using findTraceAll to explore the full call context of a slow endpoint
  2. Identifying excessive SQL volume by examining the trace details
  3. Implementing a fix in code (for example, using @EntityGraph in JPA)
  4. Replaying with the same conditions to confirm query reduction
  5. Comparing before/after traces to quantify performance improvements

Case Study: Performance Optimization​

In a real-world application, BitDive MCP helped identify and fix an N+1 query problem with impressive results:

Before optimization: 243 SQL queries in a single endpoint call (typical N+1 pattern) After optimization: 1 optimized query using EntityGraph Improvement: 99.6% reduction in queries, 86% faster response time

The complete traces were compared using:

  • deb61f9e-3f2f-11f0-bda4-4f2e85a73b5e (before optimization)
  • d2e4f42a-3f30-11f0-98c8-b9eeeeb12adb (after optimization)

Integration with Development Workflow​

BitDive MCP integrates seamlessly into development workflows:

Code Review Process - Use BitDive MCP during reviews to analyze performance impacts of changes and provide data-driven feedback on optimization opportunities.

CI/CD Pipeline - Monitor deployment performance in real-time, detect performance regressions automatically, and validate optimization improvements with concrete metrics.

Bug Investigation - Trace issue reproduction with complete call flows, analyze historical data to identify patterns, and provide actionable insights for fixes.

Security Considerations​

BitDive MCP is designed with security in mind. It uses secure communication protocols with server-side authentication. The MCP server handles all authentication, and there is no direct database access from AI. All tool usage is logged for audit purposes.

Performance Best Practices​

When using BitDive MCP, consider these performance optimization strategies:

  • Start with broad system analysis before narrowing to specific components
  • Use time-based analysis for behavioral patterns during specific windows
  • Combine monitoring and tracing tools for complete understanding
  • Schedule periodic system-wide performance analysis for baseline comparisons
  • Use selective monitoring with granular tools to focus on specific areas
  • Consider batching operations by combining related queries when possible

BitDive MCP transforms application monitoring from a reactive, manual process into a proactive, data-driven experience. By providing comprehensive runtime insights with minimal configuration, it enables developers to identify, diagnose, and fix issues with unprecedented precision and efficiency.