Configure MCP

Prerequisites

Before you begin, ensure you have:

• zymtrace backend running (version 25.11.0 or higher)
• MCP-compatible AI assistant (Claude Desktop/Code, Cursor, Cody, etc.)
• Authentication credentials (if auth is enabled on your deployment)

Find Your MCP Endpoint

Your MCP server endpoint is your zymtrace gateway URL + /mcp:

https://zymtrace.company.com/mcp

Replace zymtrace.company.com with your actual zymtrace deployment URL.

Get Authentication Credentials

If your zymtrace deployment has authentication enabled, you need a bearer token. See the MCP Token guide for detailed instructions on obtaining an MCP token.

If authentication is disabled, you can skip this step.

Configure Your AI Assistant

Claude Desktop/Code

With Authentication:

claude mcp add zymtrace \
  --transport http \
  https://your-zymtrace-instance.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN_HERE"

Without Authentication:

claude mcp add zymtrace \
  --transport http \
  https://your-zymtrace-instance.com/mcp

Verify connectivity:

claude mcp list

For more details, see the Claude MCP documentation.

Cursor IDE

With Authentication:

{
  "mcpServers": {
    "zymtrace": {
      "url": "https://your-zymtrace-instance.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:ZYMTRACE_MCP_TOKEN}"
      }
    }
  }
}

Without Authentication:

{
  "mcpServers": {
    "zymtrace": {
      "url": "https://your-zymtrace-instance.com/mcp"
    }
  }
}

For more details, see the Cursor MCP documentation.

Query Your Performance Data

Query Structure

For best results, structure your prompts with these components:

Component	Description	Examples
zymtrace	Always mention zymtrace	"in zymtrace", "using zymtrace"
Profile type	Specify CPU or GPU	"CPU flamegraphs", "GPU metrics"
Analysis type	What you want to see	flamegraphs, top functions, top entities
Entity scope	Where to look	container, namespace, pod, script name
Time range	When to analyze	last hour, 24 hours, since yesterday

Template:

"Analyze [PROFILE_TYPE] [ANALYSIS_TYPE] for [ENTITY] in zymtrace over [TIME_RANGE]"

Example Queries

Optimization and Tuning:

"Analyze the thermal-diffusion simulation performance using GPU flamegraphs. 
What optimizations would you recommend based on the last 6 hours of data?"

"Identify the most expensive CUDA kernels in our vllm inference pipeline 
running in the vllm namespace and suggest improvements."

Performance Investigation:

"What are the top 5 CPU-intensive functions in the mortgage-api container 
over the last 24 hours?"

"Show me GPU utilization patterns for the ml-training pod since yesterday. 
What is the least optimal function and how do I fix it?"

"Which functions in the payment-service pod are consuming the most CPU 
over the last 1 hour?"

Troubleshooting

Connection Issues

MCP Server Connection Failed

Verify that:

• Your zymtrace backend is running and accessible
• The MCP endpoint URL is correct (should end with /mcp)
• Your authentication token is valid (if using authentication)
• Network connectivity to the zymtrace instance

Token Limit Exceeded

If you encounter token limit errors:

• Claude Desktop/Code: Increase token limit in conversation settings
• Environment variable: Set MAX_MCP_OUTPUT_TOKENS=500000
• Query optimization: Use more specific filters to reduce response size

No Data Returned

If queries return empty results:

• Verify the entity names (container, pod, namespace) are correct
• Check the time range - ensure data exists for that period
• Confirm the profiler is running and sending data to zymtrace