Supported Lightrun MCP tools🔗
Lightrun MCP enables AI agents to investigate application behavior safely, without code changes, rebuilds, or redeployments. You describe what you want to learn in natural language, and the AI agent uses the appropriate Lightrun tools to search retained data or collect and analyze fresh runtime data.
The tools support three investigation stages:
- Discover where the application is running. Find the agent pool, agents, tags, and agent metadata that identify the runtime environment you want to inspect.
- Search captured Runtime History. Reuse relevant snapshot hits that Lightrun already captured.
- Collect fresh runtime data. Start a snapshot, duration measurement, execution count, or custom metric and retrieve the results.
If you have not connected an AI agent 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 these tools:
get_runtime_sources_agent_poolsandget_runtime_sources_agents, available starting with Lightrun version 1.86.get_runtime_sources_agents_metadata, and metadata filtering onget_runtime_sources_agents, available in Lightrun SaaS starting with version 1.97.
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.
Starting with version 1.95, the Java and Node.js agents also report runtime metadata: selected environment variables, and Kubernetes Downward API labels and annotations when those files are mounted. Java and Node.js agents older than 1.95 do not report this metadata, and neither do the Python or .NET agents. For those agents, the metadata tools return no metadata values. This reported metadata is separate from the display name and tags set during agent registration.
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
pageandsize.
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.
- Personal-access-token clients see the agent pools available through the token owner's current 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 patterns that use
*to match any sequence of characters and?to match exactly one character. An agent must match all tag patterns. - Filtering by reported runtime metadata with
metadataFilter. Available in Lightrun SaaS starting with version 1.97. See Discover agent metadata. - Pagination with
pageandsize.
Literal characters in tag patterns are normalized using the same rules as agent registration: characters outside A-Z, a-z, 0-9, _, ., and - become dots. The * and ? wildcards are preserved. For example, region:* matches the registered tag region.us.
Use a shared tag to target a related group of agents, use agent names to target specific instances, or use metadataFilter to select agents by the metadata they report.
Example prompts
- "Show the agents and tags in the production agent pool."
- "Find agents matching
checkout-*with theus-easttag." - "In the production pool, show agents whose
APPLICATION_NAMEstarts withpayments."
Discover agent metadata🔗
Available in Lightrun SaaS starting with version 1.97.
Tool name: get_runtime_sources_agents_metadata
Summarizes the runtime metadata reported by active agents in the pools the caller can access. The tool takes no parameters.
The result is a summary map. Each key is a metadata name, and each value is the set of distinct values reported for that key. Metadata from removed agents is omitted. Access follows the same rules as agent-pool discovery: OAuth and personal access tokens follow the signed-in user's permissions, and API keys follow Agent Pool Access.
Use the returned keys and values as metadataFilter on get_runtime_sources_agents to select agents in one pool.
What agents report🔗
Java and Node.js agents version 1.95 and later report:
- Environment variables commonly used to identify a service, version, environment, region, or Kubernetes workload. Examples include
APPLICATION_NAME,SERVICE_NAME,OTEL_SERVICE_NAME,DD_SERVICE,ENVIRONMENT,AWS_REGION, andPOD_NAME. The agent reports a variable only when that variable is set in the process environment. - Kubernetes Downward API label and annotation files, when they are mounted at one of these paths: -
/etc/podinfo/labels-/podinfo/labels-/etc/pod-info/labels-/etc/podinfo/annotations-/podinfo/annotations-/etc/pod-info/annotationsEach matching entry is reported with the key
<file path>:<label or annotation name>. For example,/etc/podinfo/labels:version.
Call get_runtime_sources_agents_metadata to see the keys your active agents reported. Agents that do not report metadata add nothing to the summary.
Filter agents with metadataFilter🔗
On get_runtime_sources_agents, metadataFilter is a map from a metadata key to a list of value patterns.
- An agent is returned only when it has every listed key.
- For each key, the agent's value matches when it matches any one of that key's patterns.
- Use
*as a wildcard anywhere in a pattern.payments-*matches values that start withpayments-. A pattern of*matches any value for that key. - Use each key exactly as
get_runtime_sources_agents_metadatareturned it. - Keys and patterns must contain a non-blank value.
Name filters, tag filters, and metadataFilter apply together. An agent older than 1.95, or an agent that did not report the requested key, does not match that filter.
{
"agentPoolName": "Production",
"metadataFilter": {
"APPLICATION_NAME": ["payments-*"],
"ENVIRONMENT": ["prod", "production"]
}
}
Example prompts
- "Which service names are running in Lightrun?"
- "List the metadata keys reported by active agents."
- "In the production pool, show agents whose
APPLICATION_NAMEispayments-service."
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.
Tag names are normalized using the agent-registration rules. For example, region:us targets the registered tag region.us.
An action that targets an agent pool outside a restricted API key's allowlist is rejected.
Query Runtime History🔗
Available starting with Lightrun version 1.97.
Runtime History preserves captured snapshot hits for the configured retention period. An AI agent uses it when existing captures may support an accurate answer and uses on-demand tools when fresh data is required or historical evidence is insufficient.
Runtime History provides three read-only tools:
| Tool | Purpose |
|---|---|
query_runtime_history_coverage | Discover files or functions with matching captured history. |
query_runtime_history_hits | Search individual captured hits and optionally return selected values or stack traces. |
get_runtime_history_hit | Retrieve one known historical hit by ID. |
Runtime History results are limited to agent pools the caller is permitted to access. An empty result does not prove that the code did not execute; it means no stored hit matched the query within the caller's authorized scope.
Runtime History investigation workflow🔗
The AI agent should:
- Use Runtime History when existing captures may support an accurate answer.
- Use
query_runtime_history_coverageto discover relevant files or functions. - Use
query_runtime_history_hitsto inspect matching hits. - Use
get_runtime_history_hitwhen it needs to retrieve a known hit again. - Use on-demand tools when fresh evidence is required or history is insufficient.
- Reuse the same
correlationKeyacross Runtime History calls and live actions in the same investigation.
Filter Runtime History🔗
The two query tools accept optional filters:
| Filter | Description |
|---|---|
repo | Repository associated with the captured source. |
commit | Source commit associated with the hit. |
agentPoolName | Agent pool name. This filter can narrow access but cannot expand the caller's authorized scope. |
agentNames | Matches a hit when the reporting agent's name at capture time matches any supplied name. The agent does not need to remain active. |
tagNames | Matches a hit when the reporting agent had all supplied tags at capture time. Tag names are normalized using the agent-registration rules. |
customSourceName | Matches hits from actions originally placed on that custom source. Current agent membership does not affect matching. |
file | Exact, case-sensitive captured filename or path. |
functionName | Exact, case-sensitive fully qualified or short captured function name. |
from / to | Capture-time range in ISO-8601 format. |
where | Captured-value comparisons combined with AND. |
Supply at most one of agentNames, tagNames, or customSourceName in a query.
For file, supply a basename such as Foo.java to search across recorded directories, or supply the exact recorded path to target one location. Some action creators store only the basename, so prefer a basename when the recorded path is unknown. A directory-qualified filter does not match an action that stored only the basename. Wildcards, substrings, and partial paths are not supported. A basename can match files in multiple directories; coverage results keep those original paths in separate groups.
For functionName, supply either the fully qualified name, such as com.example.Service.run, or the short name, such as run. Java and .NET names typically include the package or namespace and class. Python and Node.js names may be class-qualified or unqualified. A short name can match functions in multiple classes, so use repository, file, or runtime-source filters to narrow the results when necessary.
The where filter compares captured values without type conversion. Each comparison specifies:
- A canonical variable
path. - An operator.
- A text operand.
- An optional zero-based
frameIndex. - An optional
variableKind:ARGUMENT,LOCAL, orEXPRESSION.
The following operators are supported:
| Operator | Match behavior |
|---|---|
TEXT_EQUALS | Matches a complete string case-sensitively. Supply the string content without surrounding quotes. |
TEXT_EQUALS_IGNORE_CASE | Matches a complete string without regard to case. Supply the string content without surrounding quotes. |
VALUE_EQUALS | Matches a complete value exactly and case-sensitively, without type coercion. |
TEXT_CONTAINS | Matches string content containing the operand, without regard to case. Supply the string content without surrounding quotes. |
TEXT_STARTS_WITH | Matches string content beginning with the operand, without regard to case. Supply the string content without surrounding quotes. |
For VALUE_EQUALS, use the value's exact normalized representation. For example, {"text": "42"} matches the number 42, {"text": "true"} matches the boolean true, and {"text": "\"hello\""} matches the string hello.
TEXT_CONTAINS and TEXT_STARTS_WITH can match a truncated string when its captured portion establishes the match. Equality operators require a complete captured value. Missing values do not match.
Filtering by a captured value does not automatically include that value in the response. Request it through include.frames.selectedValues when you also need to inspect the value.
Discover Runtime History coverage🔗
Tool name: query_runtime_history_coverage
Returns grouped coverage records without returning individual hits or captured values. Set granularity to:
FILEto group by repository and file.FUNCTIONto group by repository, file, and function.
The granularity parameter is required. Each result includes its grouping fields, matching hitCount, and the earliest and latest matching capture times. Optional filters, including where, shape these counts and time ranges.
Coverage summarizes where matching history exists; it is not commit-level evidence for an individual hit. Use query_runtime_history_hits when the investigation requires commit and source attribution.
Optional parameters include:
filterscursorlimitcorrelationKey
The default limit is 100 records and the maximum is 1,000. When nextCursor is returned, pass it as cursor and keep every query-shaping parameter unchanged.
Example prompts
- "Show which files have captured Runtime History for the checkout repository in the last 24 hours."
- "Group Runtime History by function for the production agent pool."
Search Runtime History hits🔗
Tool name: query_runtime_history_hits
Returns individual hits with their source, runtime, and capture metadata. Optional parameters include:
filtersincludedistinctsort:ASCorDESC; the default isDESCcursorlimitcorrelationKey
This tool does not accept a hitId. Use get_runtime_history_hit to retrieve one known hit.
Use include to request only the additional data needed:
frames: Up to 20 frame selections. Each selection identifies a zero-basedframeIndexand can request:capturedVariables: Variable names, kinds, and types captured in that frame.selectedValues: Specific canonical paths and variable kinds.
stackTrace: The bounded captured stack trace. Arguments and local values are returned throughframes, not through the stack trace.
Set distinct to true to remove duplicate results based on the requested included data. At least one included data field is required when using distinct.
Every selected value has an outcome:
| Outcome | Meaning |
|---|---|
found | The complete normalized value text is returned. |
truncated | Only part of the normalized value text may be returned. |
redacted | Lightrun intentionally withheld the value text. |
notFound | The selected path was not present in the capture. |
error | Lightrun could not return the captured value. |
unknown | The value outcome is not recognized by the current client. |
A missing or notFound value is not the same as a captured null.
Returned values use a normalized representation across supported runtimes so that an AI agent can compare data captured from different application languages consistently.
Example prompts
- "Find Runtime History hits for
processOrderon this commit and include the first frame's captured variables." - "Find hits where the local variable
order.statusequalsFAILED, then return that value and the stack trace." - "Show distinct captured values for this expression during the incident window."
Retrieve one Runtime History hit🔗
Tool name: get_runtime_history_hit
Retrieves a known hit by hitId. It accepts the same include structure as query_runtime_history_hits and does not paginate.
Unknown and unauthorized hit IDs return the same not-found response.
Example prompts
- "Retrieve Runtime History hit
<hit-id>and include its stack trace." - "Get this hit again and return
request.idfrom frame 0."
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 AI agent to continue the investigation while the action waits for the relevant code to execute.
Use that ID to follow the action through four steps:
- Start data collection. Choose the tool for the data you need, such as
snapshot_create,execution_duration_create,execution_count_create, orcustom_metric_create. - Check progress. Pass the returned
actionIdto the corresponding status tool, such assnapshot_status. - Retrieve results. When the status response reports captured hits or samples, pass the same
actionIdto the appropriate results tool. - 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:
- Call
snapshot_createand save the returnedactionId. - Call
snapshot_statuswith that ID. - When the hit count is greater than zero, call
snapshot_get_valuesorsnapshot_get_call_stack. - 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:
outcomereports whether the action captured data, finished without hits, or encountered errors.terminationCausereports 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 or method 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.
| Tool | Purpose |
|---|---|
snapshot_create | Create a snapshot at a live code location. |
snapshot_status | Check lifecycle state, hit counts, and errors. |
snapshot_get_values | Retrieve captured expression values. |
snapshot_get_call_stack | Retrieve captured call stacks. The response supports up to 20 frames per hit. |
snapshot_cancel | Stop future captures. |
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, correlation key, and optional Git repository and commit metadata.
When the source checkout is known, the AI agent should provide repo as an owner/repository identifier and commit as the full Git commit SHA. Lightrun stores these caller-supplied values with the snapshot, which allows future Runtime History queries to filter its hits by repository and commit. The values do not verify which repository or revision is deployed, so omit them when they cannot be determined reliably.
Snapshots created through MCP capture up to three stack frames and explore objects up to five nesting levels. snapshot_get_call_stack can return up to 20 frames for compatible actions, but it cannot return frames that were not captured.
Example prompts
- "Capture
userIdandorderTotalat this line whenorder.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 one or more end lines in live application code. The measurement includes execution of the end line that completes the timed path.
| Tool | Purpose |
|---|---|
execution_duration_create | Start measuring a live code section. |
execution_duration_status | Check lifecycle state, sample counts, and errors. |
execution_duration_samples | Retrieve duration samples in milliseconds for one agent. |
execution_duration_cancel | Stop future measurements. |
With execution_duration_create, specify the runtime target, file, start line, and end line (or end lines). You can also set a condition, sampling window, and correlation key.
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."
Measure method duration with multiple end lines🔗
Available starting with Lightrun version 1.91.
Starting with version 1.91, execution_duration_create can measure method duration style timing: the time from a method entry (start line) through any of several exit points.
Provide:
- A single
endLinefor classic Tic & Toc timing between two lines, or - Multiple end lines for all relevant method exits in that method, such as return statements and explicit throw paths
This matches the JetBrains Method Duration model: the AI agent (or other MCP caller) supplies the exit lines. Lightrun MCP does not infer method exits from the method name alone.
Use multiple end lines when a method has more than one return or throw path and you want duration samples for every completed exit. Single-endLine behavior remains unchanged.
Example prompts
- "Measure how long
processOrdertakes, including every return and throw exit." - "Time this method from entry through all of its exit lines."
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_statusandexecution_duration_samplesfor timing data.snapshot_statusandsnapshot_get_valuesfor 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."
For a structured performance investigation that uses this capability, see the Slow Execution Diagnosis Skill.
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.
| Tool | Purpose |
|---|---|
execution_count_create | Start counting executions at a live code location. |
execution_count_status | Check lifecycle state, sample counts, and errors. |
execution_count_samples | Retrieve count samples for one agent. |
execution_count_cancel | Stop future counting. |
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.
| Tool | Purpose |
|---|---|
custom_metric_create | Start collecting a numeric expression. |
custom_metric_status | Check lifecycle state, sample counts, and errors. |
custom_metric_samples | Retrieve metric samples for one agent. |
custom_metric_cancel | Stop future collection. |
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 agent or coding assistant.
- Read the Lightrun MCP overview for architecture and security details.
- Learn how to configure retention and On-Premises deployment in Runtime History.
- Use the Slow Execution Diagnosis Skill for a structured performance investigation with slow-execution snapshots.