Supported Lightrun MCP tools🔗

Lightrun MCP exposes a set of MCP tools that AI assistants can invoke to inspect and reason about live application behavior. Each tool represents a specific, production-safe debugging capability provided by Lightrun and can be accessed programmatically through the Model Context Protocol.

For an overview of Lightrun MCP concepts and architecture, see the Lightrun MCP Overview.

The following sections describe the MCP tools currently exposed by Lightrun MCP. These tools are supported starting with Lightrun version 1.75 and enable AI assistants to perform production-safe runtime inspection and debugging operations.

Synchronous vs. asynchronous tools🔗

Lightrun MCP supports two execution models for runtime tools:

• Synchronous tools: a single tool call creates the action, waits for hits, and returns results in one response. This model is used by tools available in earlier Lightrun versions.
• Asynchronous tools: multiple tool calls manage one action lifecycle:
  • Create the action (x_create).
  • Poll status (x_status).
  • Cancel if needed (x_cancel).
  • Retrieve captured results (x_get_* or x_samples).

For each capability, Lightrun exposes only one model at a time to avoid ambiguity for AI assistants.

• When an async tool set is released for a capability, the corresponding sync tool is hidden.
• For snapshot runtime inspection, async tools are available starting with Lightrun version 1.85.
• For execution duration, async tools are available starting with Lightrun version 1.87.
• For execution count and custom metrics, async tools are available starting with Lightrun version 1.89.

Discover available runtime sources🔗

Tool name: get_runtime_sources

This tool allows you to discover which applications, services, or runtime environments are currently available for live debugging with Lightrun.

Before inspecting runtime data or capturing snapshots, you must first select the runtime source where the inspection will occur. Lightrun exposes the available runtime sources based on your permissions, such as:

• Running applications or services also referred to Lightrun Agents.
• Groups of instances by agent pools or by tags.
• Custom-defined source groupings.

This step helps you identify the correct runtime target before performing live inspection or debugging actions.

Example prompts

• "What runtimes or agents can I debug with Lightrun right now?"
• "List the applications and services available for live inspection."
• "Show me the agent pools or tagged runtime sources I have access to."

Inspect runtime expression values (synchronous flow)🔗

Tool name: get_runtime_expression_values

This tool allows you to inspect variable values and expressions as they exist during live application execution, without stopping the application or redeploying code.

Using this tool, Lightrun captures the state of your application when execution reaches a specific line of code. This makes it possible to understand how data flows through your system in real time.

Use this capability to:

• Investigate unexpected behavior in production or staging environments.
• Understand variable values and function arguments at specific code locations.
• Debug issues that are difficult or impossible to reproduce locally.
• Inspect request/response data and application state during execution.
• Troubleshoot performance or logic issues by examining runtime values.

The values are captured non-intrusively and only when the specified code path is executed, minimizing overhead while providing precise insights.

This approach enables live debugging without code changes, redeployment, or application interruption.

Example prompts

• "Get the runtime values of userId and orderTotal at this line."
• "Inspect the arguments passed to this function during execution."
• "Retrieve the value of transaction.amount when the transaction.approved==false is met."

Retrieve runtime call stack (synchronous flow)🔗

Tool name: get_runtime_callstack

This tool allows you to capture the call stack when execution reaches a specific line of code during live application execution, without stopping the application or redeploying code.

Using this tool, Lightrun observes when the specified code path is reached and captures the call stack at that moment, up to the top 20 stack frames. Each frame includes the code file, line number, and method name when available. This makes it possible to understand the execution path that led to a given line.

Use this capability to:

• Investigate how execution reaches a specific code location in production or staging.
• Understand the sequence of calls leading to an error or unexpected behavior.
• Debug issues that depend on call path and are difficult to reproduce locally.
• Analyze invocation patterns across different agents or runtime sources.

The call stacks are captured non-intrusively and only when the specified line is executed, within a configurable wait window and up to a maximum number of hits across agents.

This approach enables live call-stack inspection without code changes, redeployment, or application interruption.

Example prompts

• "Capture the call stack when this line is executed."
• "Show me the execution path that reaches this method at runtime."

Inspect runtime snapshots (asynchronous flow)🔗

Use the following tools together to inspect runtime expression values and call stacks asynchronously:

1. Tool name: snapshot_create Create the snapshot action
2. Tool name: snapshot_status Poll action status
3. Tool name: snapshot_cancel Cancel if no longer needed
4. Tool name: snapshot_get_values Retrieve captured expression values
5. Tool name: snapshot_get_call_stack Retrieve captured call stacks

This model supports long-running and externally triggered investigations because action creation and data retrieval are decoupled. AI assistants can wait for runtime conditions to occur, poll for progress, and fetch partial or final results without blocking a single tool call.

Example prompts

• "Create a runtime snapshot for this line and return userId and orderTotal values when it hits."
• "Check the status of this snapshot action and tell me whether it is still running."
• "Fetch captured values for this snapshot action ID."
• "Fetch call stacks for this snapshot action ID."
• "Cancel this snapshot action."

Retrieve runtime execution duration🔗

Measure execution duration (synchronous flow)🔗

Tool name: get_runtime_execution_duration

This tool allows you to measure the execution duration of a specific section of code during live application execution, without stopping the application or redeploying code.

Using this tool, Lightrun observes executions when the specified code path is reached and captures execution duration measurements over a defined sampling window. The tool returns aggregated statistics per agent, making it possible to understand how long code actually takes to run under real runtime conditions.

Use this capability to:

• Investigate performance behavior in production or staging environments.
• Measure execution duration of critical code paths.
• Identify slow or inconsistent executions that are difficult to reproduce locally.
• Compare execution duration across agents or runtime sources.
• Troubleshoot performance issues using real execution data.

The measurements are captured non-intrusively and only when the specified code section is executed, minimizing overhead while providing precise insights.

This approach enables live performance inspection without code changes, redeployment, or application interruption.

Example prompts

• "Measure the execution duration of this code section."
• "Get the distribution of execution times of this method."
• "Observe how long this logic takes to run at runtime."

Retrieve execution duration samples (synchronous flow)🔗

Tool name: get_runtime_execution_duration_samples

This tool retrieves the detailed execution duration samples for a specific agent collected by a prior invocation of get_runtime_execution_duration.

It returns the individual execution measurements underlying the aggregated statistics and does not trigger a new sampling process.

Use this tool to:

• Inspect individual execution duration measurements for a specific agent.
• Analyze execution variability and identify outliers after reviewing aggregated results.
• Perform deeper investigation into slow or inconsistent executions.
• Generate a report or a dashboard based on detailed execution duration measurements.

The samples are retrieved non-intrusively and without impacting application execution.

Measure execution duration (asynchronous flow)🔗

Starting with Lightrun version 1.87, AI assistants can measure execution duration over an observation window without waiting for the measurement to complete in a single request. This is useful when the code path runs intermittently, depends on live traffic, or must be triggered by a user action.

The assistant starts the measurement for the selected code section and collects duration samples as the code runs. The measurement can remain active until the required samples are captured or the observation window ends, without changing the application code or redeploying it.

Capture snapshots for slow executions🔗

Execution duration measurements show when a code section is slow, but timing data alone does not explain why it is slow. Starting with Lightrun version 1.89, you can ask your AI assistant to capture a snapshot automatically when a measured execution exceeds a duration threshold.

The snapshot captures the runtime values you request at the end of the measured code section. This allows you to correlate a slow execution with application context such as request data, user details, order values, or collection sizes, without creating a separate snapshot action.

Use this capability when:

• Only some executions are unexpectedly slow.
• You need runtime context to understand what distinguishes slow executions from normal ones.
• The performance issue is difficult to reproduce outside production or staging.

To trigger a snapshot, include the following information in your request to the AI assistant:

• The code section to measure.
• The duration threshold in milliseconds.
• The runtime values to capture when the threshold is exceeded.
• Optionally, the maximum number of snapshots to capture. The default is 1 and the maximum is 50.

Each time the code section runs, Lightrun records its execution duration. If the duration exceeds the threshold, Lightrun also captures the requested values at the end of the section. Executions that do not exceed the threshold produce timing measurements without snapshots.

Example prompt

"Measure the execution duration of this checkout code. If an execution takes longer than 500 milliseconds, capture the request ID, user ID, order total, and number of items. Capture up to five slow executions."

Count runtime executions🔗

Count runtime executions (synchronous flow)🔗

Tool name: get_runtime_execution_count

This tool allows you to count how many times a specific line of code is executed during live application execution, without stopping the application or redeploying code.

Using this tool, Lightrun observes executions when the specified code path is reached over a defined sampling window and returns the execution count per agent. This makes it possible to understand how often code actually runs under real runtime conditions.

Use this capability to:

• Investigate how frequently a code path is hit in production or staging.
• Compare execution counts across agents or runtime sources.
• Validate that critical code paths are invoked as expected.
• Troubleshoot logic or flow issues using real execution counts.

The counts are captured non-intrusively and only when the specified line is executed, minimizing overhead while providing precise insights.

This approach enables live execution counting without code changes, redeployment, or application interruption.

Example prompts

• "Count how many times this line is executed."
• "Check if this line is executed more than 10 times in a minute."
• "Compare how often this code runs on each service."

Count runtime executions (asynchronous flow)🔗

Use the following tools together to count how often a live code line executes asynchronously:

1. Tool name: execution_count_create — Create an execution count action.
2. Tool name: execution_count_status — Poll the action status and review hit counts.
3. Tool name: execution_count_samples — Retrieve captured count samples.
4. Tool name: execution_count_cancel — Stop future count collection when the action is no longer needed.

execution_count_create returns an actionId immediately. This model allows the action to remain active while the target code executes later or intermittently, without blocking a single MCP tool call.

Example prompts

• "Count how many times this line runs in production over the next hour and report the results by agent."
• "Track how often this code path runs when order.isPriority() is true."
• "Check the latest results for this execution count action."
• "Stop this execution count action."

Capture custom numeric metrics🔗

Capture numeric metric (synchronous flow)🔗

Tool name: get_runtime_numeric_metric

This tool allows you to capture the value of an integer expression each time a specific line of code is executed during live application execution, without stopping the application or redeploying code. The metric expression must evaluate to an integer so that statistics can be computed.

Using this tool, Lightrun evaluates the metric expression every time the specified code path is reached over a sampling window. The tool returns aggregated statistics per agent (count, min, max, average, and standard deviation) and a result set identifier you can use to retrieve the individual samples later.

Use this capability to:

• Investigate the distribution of an integer value (e.g., request size, latency, count) at a code location.
• Measure custom metrics in production or staging without redeploying.
• Compare metric statistics across agents or runtime sources.
• Troubleshoot issues using real distribution data.

The metrics are captured non-intrusively and only when the specified line is executed, minimizing overhead while providing precise insights.

This approach enables live custom metric inspection without code changes, redeployment, or application interruption.

Example prompts

• "Capture the distribution of response.getSize() at this line."
• "Get min, max, and average of order.getTotal() when this method runs."
• "Measure the value of this expression each time the code runs."

Retrieve numeric metric samples🔗

Tool name: get_runtime_numeric_metric_samples

This tool retrieves the detailed metric samples for a specific agent collected by a prior invocation of get_runtime_numeric_metric.

It returns the individual measurements underlying the aggregated statistics and does not trigger a new sampling process. You can filter by value range or time and paginate through results.

Use this tool to:

• Inspect individual metric values for a specific agent.
• Analyze distribution and outliers after reviewing aggregated results.
• Filter samples by value or timestamp for deeper investigation.
• Generate reports or dashboards from detailed metric samples.

The samples are retrieved non-intrusively and without impacting application execution.

Capture numeric metrics (asynchronous flow)🔗

Use the following tools together to capture custom numeric metrics asynchronously:

1. Tool name: custom_metric_create — Create a custom metric action.
2. Tool name: custom_metric_status — Poll the action status and review hit counts.
3. Tool name: custom_metric_samples — Retrieve captured numeric samples.
4. Tool name: custom_metric_cancel — Stop future metric collection when the action is no longer needed.

custom_metric_create evaluates an int or double expression whenever execution reaches the selected line and returns an actionId immediately. This model allows the action to collect values when the code executes later or intermittently, without blocking a single MCP tool call.

Example prompts

• "Track the value of order.getTotal() at this line over the next hour."
• "Collect response.getSize() values when this code path runs and report the results by agent."
• "Show the latest samples for this custom metric action."
• "Stop this custom metric action."

Next steps🔗

• Get hands-on: Follow the Lightrun MCP quickstart to try these tools with an AI assistant.
• Learn the concepts: Read the Lightrun MCP overview to understand the architecture and execution model behind these tools.