> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flamedeck.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Enable AI assistants to analyze performance traces and generate flamegraph visualizations

The Flamechart MCP (Model Context Protocol) server enables AI assistants to analyze performance traces and generate flamegraph visualizations. It works with both local trace files and remote traces stored on FlameDeck, across all major trace formats. Here's a quick demo of the MCP server in action:

<div style={{ position: 'relative', paddingBottom: '62.56%', height: 0, overflow: 'hidden', maxWidth: '100%', marginBottom: '2rem', borderRadius: '12px', border: '1px solid #e5e7eb' }}>
  <iframe src="https://www.youtube.com/embed/wNoL82YvuAA" style={{ position: 'absolute', top: 0, left: 0, width: '100%', height: '100%' }} frameBorder="0" allowFullScreen title="Flamechart MCP Server Demo" />
</div>

<Tip>
  **Best Model Performance** - For optimal flamegraph analysis, we recommend using AI models with strong image understanding capabilities such as OpenAI's o3. These models can better interpret the visual flamegraph outputs and provide more detailed insights about performance bottlenecks.
</Tip>

## Quick Start

### 1. Install the MCP server

<Tabs>
  <Tab title="Cursor">
    Click the button below to add the MCP server to Cursor (requires v1.0+):

    <a href="https://cursor.com/install-mcp?name=flamedeck&config=eyJjb21tYW5kIjoibnB4IC15IEBmbGFtZWRlY2svZmxhbWVjaGFydC1tY3AifQ%3D%3D" className="hidden dark:inline-block border-none">
      <img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Add flamedeck MCP server to Cursor" className="m-0" height="32" />
    </a>

    <a href="https://cursor.com/install-mcp?name=flamedeck&config=eyJjb21tYW5kIjoibnB4IC15IEBmbGFtZWRlY2svZmxhbWVjaGFydC1tY3AifQ%3D%3D" className="inline-block dark:hidden border-none">
      <img src="https://cursor.com/deeplink/mcp-install-light.svg" alt="Add flamedeck MCP server to Cursor" className="m-0" height="32" />
    </a>

    Or manually add the following to your `~/.cursor/mcp.json` file:

    ```json theme={null}
    {
      "mcpServers": {
        "flamechart-debug": {
          "command": "npx",
          "args": ["-y", "@flamedeck/flamechart-mcp"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Desktop">
    Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

    ```json theme={null}
    {
      "mcpServers": {
        "flamechart-debug": {
          "command": "npx",
          "args": ["-y", "@flamedeck/flamechart-mcp"]
        }
      }
    }
    ```
  </Tab>
</Tabs>

### 2. Start Analyzing

Try this prompt in your AI assistant (use the absolute local file path to your trace file):

```
Root cause the slowness in this trace: 
/path/to/your/profile.json
```

## Working with Remote Traces

### Setting Up FlameDeck Integration

<Steps>
  <Step title="Create an API Key">
    * Go to [FlameDeck Settings](https://flamedeck.com/settings/api-keys)
    * Create a new key with `trace:download` permissions
    * Copy the generated key
  </Step>

  <Step title="Configure the MCP Server">
    Click the button below to add the MCP configuration to Cursor (requires v1.0+):

    <a href="https://cursor.com/install-mcp?name=flamedeck&config=eyJjb21tYW5kIjoibnB4IC15IEBmbGFtZWRlY2svZmxhbWVjaGFydC1tY3AiLCJlbnYiOnsiRkxBTUVERUNLX0FQSV9LRVkiOiJ5b3VyX2FwaV9rZXlfaGVyZSJ9fQ%3D%3D" className="hidden dark:inline-block border-none">
      <img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Add flamedeck MCP server to Cursor" className="m-0" height="32" />
    </a>

    <a href="https://cursor.com/install-mcp?name=flamedeck&config=eyJjb21tYW5kIjoibnB4IC15IEBmbGFtZWRlY2svZmxhbWVjaGFydC1tY3AiLCJlbnYiOnsiRkxBTUVERUNLX0FQSV9LRVkiOiJ5b3VyX2FwaV9rZXlfaGVyZSJ9fQ%3D%3D" className="inline-block dark:hidden border-none">
      <img src="https://cursor.com/deeplink/mcp-install-light.svg" alt="Add flamedeck MCP server to Cursor" className="m-0" height="32" />
    </a>

    Or manually add the following to your MCP server configuration:

    ```json theme={null}
    {
      "mcpServers": {
        "flamechart-debug": {
          "command": "npx",
          "args": ["-y", "@flamedeck/flamechart-mcp"],
          "env": {
            "FLAMEDECK_API_KEY": "your_api_key_here"
          }
        }
      }
    }
    ```
  </Step>
</Steps>

### Using Remote Traces

Once configured, you can analyze traces directly from FlameDeck URLs:

```
Analyze this production trace and find performance bottlenecks:
https://www.flamedeck.com/traces/98508d02-1f2a-4885-9607-ecadceb3d734

Focus on database operations and API endpoints.
```

## Example Workflows

### Debugging Slow React Rendering

```
I have a React app that's rendering slowly. Analyze this Chrome DevTools profile:
/Users/dev/profiles/react-slow-render.json

Please:
1. Show me the top functions taking the most time
2. Generate a flamegraph to visualize the call stack
3. Look for any React-specific bottlenecks like expensive re-renders
4. Focus on functions in my application code vs React internals
```

### API Performance Investigation

```
Our API endpoints are slow. Help me analyze this production trace:
https://www.flamedeck.com/traces/5e538693-a0b6-40a0-a932-8a6b48c2f269

Investigation goals:
1. Identify the slowest endpoints
2. Find database vs application time breakdown
3. Look for N+1 query patterns
4. Generate a visual report I can share with the team
```

## Supported Trace Formats

The MCP server supports a wide range of profiling formats, including pprof, chrome, pyinstrument, etc.

<Check>
  **Automatic Format Detection** - The server automatically detects trace formats and handles gzipped files transparently.
</Check>

## Available Tools

### get\_top\_functions

Identifies the slowest functions in your trace, helping you find performance bottlenecks.

<ParamField path="trace" type="string" required>
  File path or FlameDeck URL
</ParamField>

<ParamField path="sortBy" type="string" default="total">
  Sort by `'self'` or `'total'` time
</ParamField>

<ParamField path="offset" type="number" default="0">
  Starting position for pagination
</ParamField>

<ParamField path="limit" type="number" default="15">
  Number of functions to return
</ParamField>

**Example Usage:**

```
Show me the top 20 functions consuming the most total time in this trace:
/Users/dev/profiles/api-slow.cpuprofile
```

### generate\_flamegraph\_screenshot

Creates a visual flamegraph showing the timeline of function execution.

<ParamField path="trace" type="string" required>
  File path or FlameDeck URL
</ParamField>

<ParamField path="width" type="number" default="1200">
  Image width in pixels
</ParamField>

<ParamField path="height" type="number" default="800">
  Image height in pixels
</ParamField>

<ParamField path="mode" type="string" default="light">
  Theme: `'light'` or `'dark'`
</ParamField>

<ParamField path="startTimeMs" type="number">
  Start time for zoomed view
</ParamField>

<ParamField path="endTimeMs" type="number">
  End time for zoomed view
</ParamField>

<ParamField path="startDepth" type="number">
  Stack depth to start visualization
</ParamField>

**Example Usage:**

```
Generate a dark mode flamegraph of this trace for my presentation:
/path/to/production-profile.json
```

### generate\_sandwich\_flamegraph\_screenshot

Creates a "sandwich view" focusing on a specific function, showing both its callers and callees.

<ParamField path="trace" type="string" required>
  File path or FlameDeck URL
</ParamField>

<ParamField path="frameName" type="string" required>
  Exact function name to focus on
</ParamField>

**Example Usage:**

```
Create a sandwich view for the "processData" function to understand what's calling it:
/path/to/trace.json
```

## Performance Features

### Smart Caching

The MCP server includes intelligent caching to improve performance:

* **Remote URLs**: Cached for 5 minutes to avoid repeated API calls
* **Local Files**: Cached until file modification detected
* **Memory Management**: Automatic cleanup with 50 profile limit
* **Cache Invalidation**: Smart invalidation based on file changes

<Tip>
  **Performance Boost** - Subsequent tool calls on the same trace are nearly instant thanks to smart caching.
</Tip>

## Troubleshooting

### Common Issues

<AccordionGroup>
  <Accordion title="MCP Server Not Starting">
    * Ensure Node.js is installed (version 16+ recommended)
    * Try running with `npx -y @flamedeck/flamechart-mcp` to force latest version
  </Accordion>

  <Accordion title="API Key Authentication Errors">
    * Verify your API key has `trace:download` permissions
    * Check that the key is correctly set in environment variables
    * Ensure the FlameDeck URL format is correct: `https://www.flamedeck.com/traces/{id}`
  </Accordion>

  <Accordion title="Trace File Not Found">
    * Use absolute file paths for local traces
    * Verify file exists and is readable
    * Check that the trace format is supported
  </Accordion>

  <Accordion title="Performance Issues">
    * Large traces (>100MB) may take longer to process
    * Consider using time-based zooming for very long traces
    * Clear cache if memory usage becomes excessive
  </Accordion>
</AccordionGroup>

### Getting Help

For technical support or to report issues, please submit a ticket through our [GitHub issue tracker](https://github.com/flamedeck-org/flamedeck/issues).

## Advanced Usage

### Custom Flamegraph Views

Create focused visualizations by specifying time ranges:

```
Generate a flamegraph focusing on the 500ms-1500ms time range of this trace:
/path/to/long-running-profile.json

I want to see what happened during that specific slow period.
```

### Integration with Code Analysis

Combine trace analysis with code review:

```
Analyze this performance trace and then look through my codebase to understand the bottlenecks:
/path/to/slow-api.cpuprofile

Focus on the slowest functions and help me understand:
1. What those functions actually do in the code
2. Why they might be slow
3. Potential optimization strategies
```