Supported Lightrun MCP tools🔗

Lightrun MCP enables AI assistants to investigate live application behavior safely, without code changes, rebuilds, or redeployments. You describe what you want to learn in natural language, and the assistant uses the appropriate Lightrun tools to collect and analyze runtime data.

The tools work in two stages:

1. Discover where the application is running. Find the agent pool, agents, and tags that identify the runtime environment you want to inspect.
2. Collect runtime data. Start a snapshot, duration measurement, execution count, or custom metric and retrieve the results.

If you have not connected an AI assistant yet, follow the Lightrun MCP quickstart. For an introduction to the feature and its architecture, see the Lightrun MCP overview.

Discover runtime sources🔗

Source discovery uses two tools. These tools are available starting with Lightrun version 1.86.

A Lightrun agent runs alongside each application instance and enables Lightrun to collect runtime data. An agent pool securely isolates a group of agents. Within a pool, agent names identify individual application instances, while tags identify related groups, such as all instances of a service in production.

Discover agent pools🔗

Tool name: get_runtime_sources_agent_pools

Lists the Lightrun agent pools available to the current user. Each result includes the pool name and ID, agent count, and tag count.

The tool supports:

• Filtering agent pool names with * wildcards.
• Pagination with page and size.

Use this tool first to select the environment, service, or deployment to inspect.

Lightrun returns only the pools the caller is permitted to access:

• OAuth clients see the agent pools available through the signed-in user's RBAC permissions.
• Starting with Lightrun version 1.90, API-key clients see only the pools permitted by the key's Agent Pool Access configuration. All Agent Pools includes current and future pools, while Specific Agent Pools limits both discovery and actions to the selected allowlist.

Example prompts

• "List the runtime environments available to Lightrun."
• "Find agent pools matching prod-*."

Discover agents and tags🔗

Tool name: get_runtime_sources_agents

Lists agents and tags in one agent pool. Pass an agentPoolName returned by get_runtime_sources_agent_pools.

The tool supports:

• Filtering agent names with one or more * wildcard patterns. An agent matches if any name pattern matches.
• Filtering tags with one or more * wildcard patterns. An agent must match all tag patterns.
• Pagination with page and size.

Use a shared tag to target a related group of agents, or use agent names to target specific instances.

Example prompts

• "Show the agents and tags in the production agent pool."
• "Find agents matching checkout-* with the us-east tag."

Select a runtime target🔗

Every create tool requires agentPoolName. Also provide exactly one of:

• agentNames: One or more specific agent instances.
• tagNames: Agents that have all specified tags.
• customSourceName: A user-defined group of agents and tags.

An action that targets an agent pool outside a restricted API key's allowlist is rejected.

Understand the asynchronous tool flow🔗

A runtime action is a temporary instruction to collect specific data from the running application. The data may not be available immediately. For example, a snapshot cannot capture values until live application traffic reaches its selected line.

Lightrun starts each runtime action in the background and immediately returns an actionId. This allows the assistant to continue the conversation while the action waits for the relevant code to execute.

Use that ID to follow the action through four steps:

1. Start data collection. Choose the tool for the data you need, such as snapshot_create, execution_duration_create, execution_count_create, or custom_metric_create.
2. Check progress. Pass the returned actionId to the corresponding status tool, such as snapshot_status.
3. Retrieve results. When the status response reports captured hits or samples, pass the same actionId to the appropriate results tool.
4. Stop collection when necessary. An action ends automatically when it expires or reaches its configured limit. To stop it earlier, use its cancel tool.

For example, a snapshot investigation follows this sequence:

1. Call snapshot_create and save the returned actionId.
2. Call snapshot_status with that ID.
3. When the hit count is greater than zero, call snapshot_get_values or snapshot_get_call_stack.
4. If you no longer need additional captures, call snapshot_cancel.

The same sequence applies to duration, count, and custom metric actions. Each capability section below lists its start, status, results, and cancel tools.

Action states🔗

Status tools report hit or sample counts, per-agent statistics, errors, and one of the following states:

• PENDING: No agent has accepted the action yet.
• RUNNING: At least one agent accepted the action. Data collection may still be in progress.
• FINISHED: The action has stopped because it completed, expired, was cancelled, or all targeted agents failed.

A hit means that an action captured data. Measurement tools return their captured data as samples. Use the status tool before requesting results. A PENDING or RUNNING action can remain active while waiting for the relevant code path to execute. Request results only after the reported hit or sample count is greater than zero.

When an action reaches FINISHED, the status response also explains the result:

• outcome reports whether the action captured data, finished without hits, or encountered errors.
• terminationCause reports why collection stopped, such as expiration, cancellation, reaching the maximum hit count, or failure on all targeted agents.

Choose the runtime data to collect🔗

Select a capability based on the question you want to answer:

• Snapshot: What values are in scope, and how did execution reach this line?
• Execution duration: How long does this code section take to run?
• Execution count: How often does this line execute?
• Custom metric: What numeric values does this expression produce over time?

Inspect runtime snapshots🔗

Available starting with Lightrun version 1.85.

Lightrun Snapshots are virtual breakpoints that capture expression values and call stacks without pausing the application. A snapshot captures data when execution reaches a selected line.

With snapshot_create, specify the runtime target, file, executable line, and up to 10 expressions. You can also set a condition, maximum hit count, wait time, and correlation key.

Example prompts

• "Capture userId and orderTotal at this line when order.isPriority() is true."
• "Show the call stack for the captured snapshot."
• "Cancel this snapshot action."

Measure execution duration🔗

Available for Java/JVM applications starting with Lightrun version 1.87.

Execution duration measures the wall-clock time between a start line and an end line in live application code. The measurement includes execution of the end line.

Samples can be filtered by agent, time range, and duration range, with pagination.

Example prompts

• "Measure this checkout section for the next hour."
• "Show duration samples above 500 milliseconds for this agent."

Capture snapshots for slow executions🔗

Available starting with Lightrun version 1.89.

execution_duration_create can capture expression values when a measured execution exceeds snapshotThresholdMs. Provide:

• snapshotThresholdMs: Duration threshold in milliseconds.
• snapshotExpressions: Values to capture at the end line.
• snapshotMaxHits: Optional maximum number of slow-execution snapshots.

Use the execution-duration actionId with:

• execution_duration_status and execution_duration_samples for timing data.
• snapshot_status and snapshot_get_values for slow-execution snapshots.

Example prompt

"Measure this checkout section. When it takes longer than 500 milliseconds, capture the request ID, order total, and item count."

Count runtime executions🔗

Available for Java/JVM applications starting with Lightrun version 1.89.

An execution count tracks how often a selected executable line runs. This helps identify unexpectedly hot, cold, or unused code paths.

Samples can be filtered by agent, time range, and count range, with pagination.

Example prompts

• "Count how often this line runs in production over the next hour."
• "Track executions when order.isPriority() is true."

Capture custom numeric metrics🔗

Available for Java/JVM applications starting with Lightrun version 1.89.

Custom metrics evaluate an int or double expression whenever execution reaches a selected line. They reveal how application-specific numeric values change over time without requiring additional instrumentation.

Samples can be filtered by agent, time range, and value range, with pagination.

Example prompts

• "Track order.getTotal() at this line for the next hour."
• "Show metric samples above 1,000 for this agent."

Find MCP-created actions🔗

Tool name: get_actions

Available starting with Lightrun version 1.88.

Lists actions created through Lightrun MCP, newest first. Use it to resume an investigation or find related actions before calling their status and result tools.

A correlationKey groups actions that belong to the same investigation, such as a Jira ticket, incident, or support case. Each action still has its own actionId for status, result, and cancellation requests.

Optional filters include:

• correlationKey
• Agent pool
• Creation time range
• File path, with * wildcard support
• Line number
• Whether the action has captured hits

Results include the actionId, action state, target, creation time, hit count, and error count. The tool supports pagination.

Example prompts

• "Find MCP actions for correlation key INC-1042."
• "List actions with hits for this file and line."

Next steps🔗

• Follow the Lightrun MCP quickstart to connect an AI assistant.
• Read the Lightrun MCP overview for architecture and security details.