How to Use yCrash MCP with Cursor for Java Troubleshooting 

In many organisations, a production issue starts in a familiar way. A critical service starts slowing down. A few pods stop responding. An SRE collects the GC logs, thread dumps, or heap dumps and shares them with the team. The team now has the data, but still needs to figure out what is going wrong. 

Someone from the team downloads the dump, opens a diagnostics tool, uploads it, waits for the analysis to finish, and then shares the report with the team. It works, but getting from the diagnostic file to the actual root cause still takes several steps. 

We wanted to make that process simpler. That’s where yCrash MCP Server comes in.

You can connect yCrash MCP Server to an AI client such as Cursor, Claude, or VS Code and ask it to analyze a thread dump, GC log, or other diagnostic data. The AI client sends the request to yCrash MCP Server, which then uses yCrash to analyze the data. The result comes back to the chat with a summary and a link to the yCrash report. 

The important thing to remember is that yCrash still does the actual analysis. The yCrash MCP simply acts as the bridge between the AI assistant and yCrash.

In this blog, we’ll show how we connected yCrash MCP to Cursor and how the setup works in two different ways:

1. stdio: Run the MCP server locally on a developer’s machine.
2. HTTP: Run a shared MCP endpoint that can be used by a team.

How yCrash MCP Connects Cursor to Java Troubleshooting

Fig: Traditional Java Troubleshooting Workflow Before Using yCrash MCP  

MCP stands for Model Context Protocol. It provides a standard way for an AI client to discover tools provided by another server and call those tools with structured inputs.

In our case, the yCrash MCP Server is a single JAR file: ycrash-mcp-server.jar. The AI client, such as Cursor, communicates with this JAR, and the JAR communicates with the yCrash application through its REST APIs. 

Fig: How yCrash MCP Connects Cursor to yCrash for Java Troubleshooting 

The yCrash MCP Server currently exposes four tools:

For the analysis tools, you can provide the diagnostic data in one of three ways: 

1. An absolute `filePath` to a file on the machine where the MCP server is running. 
2. The diagnostic data as `textContent`. 
3. A public URL that yCrash can use to download the file. 

You can also provide optional information such as `appName`, `host`, and `tags`. These details are included with the analysis and make the resulting reports easier to identify later. 

There are two ways to connect Cursor to the yCrash MCP server:

• stdio – With stdio, Cursor starts the JAR itself using `java -jar …` and communicates with it through standard input and output. This is useful when the MCP server runs locally on a developer’s machine.
  
• HTTP – With HTTP, you start the JAR separately as a long-running process. Cursor then connects to the MCP server through its HTTP URL. This setup works well when the MCP server is hosted centrally and shared by a team.
  

In the next section, we will see how to connect to the yCrash MCP server using both of the above methods and analyze diagnostic data.

Set Up yCrash MCP with Cursor Using stdio

If you want to run yCrash MCP on your own machine, stdio is the simplest setup. You don’t start the MCP JAR manually. Instead, Cursor starts it for you when it needs to use one of the yCrash tools. You just need to configure the JAR location and the yCrash connection details in `mcp.json`.  

Prerequisites for Cursor and yCrash MCP

You need the following on the machine where Cursor is running: 

1. JDK 17 or newer 
2. A reachable yCrash application
3. A yCrash API key or LDAP credentials 
4. The ready-to-run `ycrash-mcp-server.jar` 

You can get the `ycrash-mcp-server.jar` from the yCrash distribution. In the enterprise package, it is usually available under the `tools/mcp/` directory. 

Keep the JAR in a stable location. For example, on Windows, we used:

C:/ycrash/tools/mcp/ycrash-mcp-server.jar

On macOS or Linux, you could use something like:

/opt/ycrash/tools/mcp/ycrash-mcp-server.jar

Use an absolute path here to avoid problems later if Cursor starts the process with a different working directory.

Configure Cursor to Start the yCrash MCP Server 

Cursor uses an `mcp.json` file to configure MCP servers. You can configure the server for all your projects or only for a specific project:

• User configuration: ~/.cursor/mcp.json on macOS/Linux, or %USERPROFILE%\.cursor\mcp.json on Windows
• Project configuration: <project>/.cursor/mcp.json

For example, this is the configuration we used on Windows with a yCrash API key:

{
  "mcpServers": {
    "ycrash": {
      "command": "java",
      "args": ["-Xmx128m", "-Xms32m", "-jar", "C:/ycrash/tools/mcp/ycrash-mcp-server.jar"],
      "env": {
        "YCRASH_BASE_URL": "https://your-ycrash-host",
        "YCRASH_API_KEY": "your-api-key",
        "YCRASH_FILEPATH_ALLOWLIST": "C:/dumps,D:/temp"
      }
    }
  }
}

On macOS or Linux, change the JAR path and allowlisted directories to the appropriate Unix paths. 

For Windows paths, we recommend using forward slashes such as `C:/ycrash/…` in the JSON. It is simpler than dealing with escaped backslashes.

There is one setting in this configuration that is worth understanding: `YCRASH_FILEPATH_ALLOWLIST`.

When the AI client asks yCrash MCP to analyze a file using `filePath`, the MCP server will only read files from the directories listed in this setting. This prevents the MCP server from reading arbitrary files from the machine.

The allowlist is required. If it is missing, the MCP server will not start. If your diagnostic file is somewhere else, either move it into an allowed directory or add that directory to the allowlist. 

Fig: stdio mcp.json configuration in Cursor

Once `mcp.json` is saved, reload the MCP servers in Cursor. If Cursor doesn’t pick up the change, use Developer: Reload Window or restart Cursor. 

Verify the yCrash MCP Connection in Cursor 

Before using a production diagnostic file, it is worth checking that the MCP server is actually connected. Open Customize → MCPs in Cursor. The yCrash MCP server should show as connected, and the four yCrash tools should be available.

Fig: stdio smoke test – ycrash connected with four tools

If the server is connected and the tools are listed, the MCP setup is ready. From this point, you can use the tools directly from Cursor’s Agent chat. 

Analyze Java Diagnostic Files from Cursor Chat 

We started by testing the setup with a GC log.

First, we placed the log file in one of the allowlisted directories. Then we opened Cursor’s Agent chat and asked it to analyze the file using the yCrash GC analysis tool.

For example:

```
Use yCrash analyzeGcLog on C:/dumps/prod-gc.log with graphs enabled.
Summarize long pauses, throughput, and whether heap sizing looks reasonable.
Return the web report URL first.
```

Cursor may ask you to approve the tool call. Once approved, it starts the MCP server if it isn’t already running and sends the request to the appropriate tool.

Fig: stdio – Cursor calling analyzeGcLog

In our test, the response came back in the same chat with the yCrash report URL along with a summary of GC pauses, throughput, and heap sizing.

That was useful because we could get an initial understanding of the problem without opening the yCrash UI first. 

Fig: stdio – GC analysis summary and web report URL in chat

We then opened the report URL and got the usual yCrash GC Intelligence Report. In this sample, the report showed consecutive Full GCs, long pauses, and poor throughput, along with the interactive analysis available in yCrash.

Fig: stdio – yCrash GC Intelligence Report in the browser

For day-to-day troubleshooting on a developer’s machine, the workflow was simple:

Cursor → yCrash MCP → yCrash → report back in Cursor

Cursor started the JAR for us, the JAR called the yCrash APIs, and we stayed in the same chat while the analysis was running.

Connect Cursor to yCrash MCP Using HTTP 

The stdio setup works well when each developer runs yCrash MCP on their own machine. But that is not always what you want.

A team may prefer to run the MCP server on a shared machine instead. This gives you one place to manage the yCrash connection, file access, and MCP authentication, rather than configuring all of that on every developer’s laptop. 

That is where HTTP mode comes in. The same `ycrash-mcp-server.jar` can run as a long-lived HTTP process. Cursor then connects to that process instead of starting the JAR itself.

From Cursor’s point of view, the experience is almost the same. You still ask it to analyze a GC log, thread dump, or heap dump. The main difference is where the MCP server is running and, importantly, where the diagnostic file must be accessible.

Configure and Start the yCrash MCP HTTP Server 

There are two credentials involved in this setup, and they serve different purposes. 

The first is the yCrash API key (or LDAP configuration). The yCrash MCP server uses this credential when it calls your yCrash application. 

The second is the yCrash MCP HTTP API key. This is a separate secret used only to protect the HTTP endpoint that Cursor connects to. It is generated and managed by you; it is not a yCrash API key.

The yCrash MCP HTTP API key needs to match on both sides: 

1. The environment in which the yCrash MCP HTTP server is running. 
2. The HTTP headers configured in Cursor. 

We generate the key when starting the yCrash MCP server and copy it into Cursor’s `mcp.json`. 

Configure the HTTP Server on Linux / macOS

On Linux or macOS, you can configure the required environment variables and start the yCrash MCP server from a terminal.

export YCRASH_BASE_URL=https://your-ycrash-host
export YCRASH_API_KEY=your-api-key
export YCRASH_FILEPATH_ALLOWLIST=/var/ycrash/uploads,/tmp
export YCRASH_MCP_HTTP_HOST=127.0.0.1
export YCRASH_MCP_HTTP_PORT=8081
export YCRASH_MCP_HTTP_PATH=/mcp
 
# Generate the key, show it, then keep it in the environment
export YCRASH_MCP_HTTP_API_KEY="$(openssl rand -hex 32)"
echo "Copy this MCP HTTP API key into Cursor mcp.json:"
echo "$YCRASH_MCP_HTTP_API_KEY"
 
java -cp /opt/ycrash/ycrash-mcp-server.jar com.tier1app.ycrash.mcp.YCrashMcpHttpServerMain

The important part here is that the yCrash MCP server is now a separate process. Cursor will connect to it over HTTP instead of starting the JAR itself. 

Configure the yCrash MCP HTTP Server on Windows (PowerShell) 

The same setup works on Windows. Here is the PowerShell version:

$env:YCRASH_BASE_URL = "https://your-ycrash-host"
$env:YCRASH_API_KEY = "your-api-key"
$env:YCRASH_FILEPATH_ALLOWLIST = "C:/dumps,D:/temp"
$env:YCRASH_MCP_HTTP_HOST = "127.0.0.1"
$env:YCRASH_MCP_HTTP_PORT = "8081"
$env:YCRASH_MCP_HTTP_PATH = "/mcp"
 
# Generate the key, show it, then keep it in the environment
$env:YCRASH_MCP_HTTP_API_KEY = -join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Maximum 256) })
Write-Host "Copy this MCP HTTP API key into Cursor mcp.json:"
Write-Host $env:YCRASH_MCP_HTTP_API_KEY
 
java -cp C:\tools\ycrash\ycrash-mcp-server.jar `
  com.tier1app.ycrash.mcp.YCrashMcpHttpServerMain

The yCrash MCP HTTP API key only exists in that PowerShell session. If you close the window and lose the key, generate a new one, restart the MCP server with the new key, and update Cursor’s `mcp.json` accordingly. 

Connect Cursor to the MCP HTTP Endpoint 

Once the yCrash MCP HTTP server is running, configure Cursor for the MCP HTTP endpoint. The Cursor configuration is slightly different from the stdio setup.

Instead of telling Cursor how to start the Java process, you give it the MCP HTTP endpoint and the API key.

For example:

{
  "mcpServers": {
    "ycrash-http": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:8081/mcp",
      "headers": {
        "X-Mcp-Api-Key": "paste-the-printed-mcp-http-api-key-here"
      }
    }
  }
}

You can also use:

Authorization: Bearer <same-key>

instead of the `X-Mcp-Api-Key` header.

Save the configuration and reload Cursor.

Fig: http mcp.json – Cursor pointed at streamable-http URL

If everything is configured correctly, the `ycrash-http` server should appear as connected, and the same four yCrash tools should be available. 

Fig: http smoke test – ycrash-http connected with four tools

Troubleshoot Java Applications Through Cursor Chat 

The chat prompts are the same in both modes, but `filePath` works differently.

With stdio, the MCP server is running on your machine, so a path such as:

C:/dumps/prod-gc.log

This path refers to a file on your machine.

With HTTP, `filePath` refers to the machine where the yCrash MCP HTTP server is running.

This is an important distinction when you move from a local setup to a shared MCP server. 

If the diagnostic file is on your laptop but the MCP server is running somewhere else, you have a few options: 

1. Copy the file to a directory allowed by `YCRASH_FILEPATH_ALLOWLIST` on the yCrash MCP server. 
2. Provide the file through a public URL that yCrash can download. 
3. Paste the diagnostic data if it is small enough. 

For large diagnostic files, copying the file to the MCP server or providing a URL is generally more practical than pasting the contents into chat. 

For our HTTP test, we used a thread dump containing a classic dining-philosophers deadlock. We asked Cursor to analyze it through the `ycrash-http` server:

Use yCrash analyzeThreadDump on C:/dumps/dinning-philosophers-circular-deadlock.txt.
Summarize the root cause and return the yCrash web report URL first.

Fig: HTTP – Cursor calling analyzeThreadDump via ycrash-http

Cursor sent the request to `analyzeThreadDump` through the yCrash HTTP MCP server. The response came back in the same chat with the yCrash report URL and a short explanation of the circular lock. 

Fig: http – deadlock summary and web report URL in chat

Opening the report took us to the FastThread intelligence view, where we could see the fatal multi-level deadlock and the thread information for the sample.

Fig: http – yCrash FastThread report for the deadlock dump

Example Cursor Prompts for Java Troubleshooting 

Once the yCrash MCP server is connected, the quality of the results depends on how clearly you ask for what you need. 

To Analyze a GC Log

Use yCrash analyzeGcLog on C:/dumps/prod-gc.log with graphs enabled.
Summarize long pauses, throughput, and heap sizing.
Return the web report URL first.

To Analyze a Thread Dump 

Use yCrash analyzeThreadDump on C:/dumps/checkout-td.txt for appName=checkout.
Summarize deadlocks and BLOCKED threads.
Return the web report URL first.

To Analyze a Heap Dump 

Use yCrash analyzeHeapDump on C:/dumps/oom.hprof for appName=payments.
What are the largest retained sets?
Link the web and troubleshoot reports.

To Analyze Pasted Diagnostic Data 

Analyze this thread dump with yCrash and tell me if we are stuck on a lock or on I/O:
"""
<main dump text>
"""

To Add a Reusable Instruction for Longer Chats 

For longer troubleshooting sessions, we also found it useful to give the assistant a simple standing instruction:
Only summarize what the yCrash tool response contains.
Always return the webReport URL first.
If the tool fails, show the error. Do not invent findings.

This keeps the conversation grounded in the actual yCrash analysis instead of letting the assistant fill in gaps when a tool call fails or returns incomplete information. 

Common yCrash MCP and Cursor Setup Issues 

These are the issues we ran into, or came close to running into, while setting up the two modes.

Troubleshoot Java Applications Without Leaving Cursor 

The yCrash MCP server does not replace yCrash. yCrash still performs the actual analysis and generates the reports. What changed for us was the starting point of the investigation. 

Instead of collecting a diagnostic file, opening another tool, uploading the file, and then switching back to the code or incident discussion, we could start the analysis from the same Cursor conversation where we were already investigating the application. 

For an individual developer, stdio is the simplest setup. Cursor starts the JAR locally, and everything stays on the developer’s machine.

For a team, HTTP mode gives you a shared MCP endpoint. You can run the same JAR centrally and control the yCrash connection, file access, and MCP authentication in one place.

That is really what the MCP integration changes. It doesn’t change how yCrash analyzes the data. It changes how you get to that analysis.