@last9/mcp-server 0.1.15 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +212 -185
  2. package/package.json +1 -1
  3. package/dist/LICENSE +0 -201
  4. package/dist/README.md +0 -604
  5. package/dist/last9-mcp-server +0 -0
package/README.md CHANGED
@@ -1,7 +1,6 @@
1
1
  # Last9 MCP Server
2
2
 
3
3
  ![last9 mcp demo](mcp-demo.gif)
4
-
5
4
  A [Model Context Protocol](https://modelcontextprotocol.io/) server
6
5
  implementation for [Last9](https://last9.io/mcp/) that enables AI agents to
7
6
  seamlessly bring real-time production context — logs, metrics, and traces — into
@@ -11,12 +10,74 @@ your local environment to auto-fix code faster.
11
10
  - Read our
12
11
  [announcement blog post](https://last9.io/blog/launching-last9-mcp-server/)
13
12
 
13
+ ## Quick Links
14
+
15
+ - [Status](#status)
16
+ - [Installation](#installation)
17
+ - [Configuration](#configuration)
18
+ - [Usage](#usage)
19
+ - [Tools Documentation](#tools-documentation)
20
+ - [Development](#development)
21
+ - [Testing](#testing)
22
+ - [Badges](#badges)
23
+
24
+ ## Installation
25
+
26
+ You can connect to Last9 MCP in two ways:
27
+
28
+ ### Recommended: Managed MCP over HTTP
29
+
30
+ This is the easiest and cleanest setup. You do not need to run a local binary.
31
+ Use an API token from [Last9 API Access](https://app.last9.io/settings/api-access).
32
+
33
+ ```bash
34
+ claude mcp add --transport http last9 https://app.last9.io/api/v4/organizations/<organization_slug>/mcp \
35
+ --header "X-LAST9-API-TOKEN: Bearer <last9_api_token>"
36
+ ```
37
+
38
+ Or add it directly to your MCP client config:
39
+
40
+ ```json
41
+ {
42
+ "mcpServers": {
43
+ "last9": {
44
+ "type": "http",
45
+ "url": "https://app.last9.io/api/v4/organizations/<organization_slug>/mcp",
46
+ "headers": {
47
+ "X-LAST9-API-TOKEN": "Bearer <last9_api_token>"
48
+ }
49
+ }
50
+ }
51
+ }
52
+ ```
53
+
54
+ ### Local Installation (STDIO fallback)
55
+
56
+ Use this only if your client needs a local STDIO server process.
57
+
58
+ #### Homebrew
59
+
60
+ ```bash
61
+ brew update
62
+ brew install last9/tap/last9-mcp
63
+ brew upgrade last9/tap/last9-mcp
64
+ last9-mcp --version
65
+ ```
66
+
67
+ #### NPM
68
+
69
+ ```bash
70
+ # Install globally
71
+ npm install -g @last9/mcp-server@latest
72
+ # Or run directly with npx
73
+ npx -y @last9/mcp-server@latest
74
+ ```
75
+
14
76
  ## Status
15
77
 
16
78
  Works with Claude desktop app, or Cursor, Windsurf, and VSCode (Github Copilot)
17
79
  IDEs. Implements the following MCP
18
80
  [tools](https://modelcontextprotocol.io/docs/concepts/tools):
19
-
20
81
  **Observability & APM Tools:**
21
82
 
22
83
  - `get_exceptions`: Get the list of exceptions.
@@ -25,16 +86,12 @@ IDEs. Implements the following MCP
25
86
  - `get_service_performance_details`: Get detailed performance metrics for a service.
26
87
  - `get_service_operations_summary`: Get operations summary for a service.
27
88
  - `get_service_dependency_graph`: Get service dependency graph showing incoming/outgoing dependencies.
28
-
29
- **Prometheus/PromQL Tools:**
30
-
89
+ **Prometheus/PromQL Tools:**
31
90
  - `prometheus_range_query`: Execute PromQL range queries for metrics data.
32
91
  - `prometheus_instant_query`: Execute PromQL instant queries for metrics data.
33
92
  - `prometheus_label_values`: Get label values for PromQL queries.
34
93
  - `prometheus_labels`: Get available labels for PromQL queries.
35
-
36
- **Logs Management:**
37
-
94
+ **Logs Management:**
38
95
  - `get_logs`: Get logs filtered by service name and/or severity level.
39
96
  - `get_drop_rules`: Get drop rules for logs that determine what logs get
40
97
  filtered out at [Last9 Control Plane](https://last9.io/control-plane)
@@ -42,146 +99,135 @@ IDEs. Implements the following MCP
42
99
  [Last9 Control Plane](https://last9.io/control-plane)
43
100
  - `get_service_logs`: Get raw log entries for a specific service over a time range. Can apply filters on severity and body.
44
101
  - `get_log_attributes`: Get available log attributes (labels) for a specified time window.
45
-
46
- **Traces Management:**
47
-
48
- - `get_service_traces`: Query traces for a specific service with filtering options for span kinds, status codes, and other trace attributes.
102
+ **Traces Management:**
103
+ - `get_traces`: Retrieve traces using JSON pipeline queries for advanced filtering.
104
+ - `get_service_traces`: Retrieve traces by trace ID or service name with time range filtering.
49
105
  - `get_trace_attributes`: Get available trace attributes (series) for a specified time window.
50
-
51
- **Change Events:**
52
-
106
+ **Change Events:**
53
107
  - `get_change_events`: Get change events from the last9_change_events prometheus metric over a given time range.
54
-
55
- **Alert Management:**
56
-
108
+ **Alert Management:**
57
109
  - `get_alert_config`: Get alert configurations (alert rules) from Last9.
58
110
  - `get_alerts`: Get currently active alerts from Last9 monitoring system.
59
111
 
60
112
  ## Tools Documentation
61
113
 
114
+ ### Time Input Standard
115
+
116
+ - For relative windows, prefer `lookback_minutes`.
117
+ - For absolute windows, use `start_time_iso`, `end_time_iso`, or `time_iso` in RFC3339/ISO8601 (for example, `2026-02-09T15:04:05Z`).
118
+ - If both relative and absolute inputs are provided, absolute time inputs take precedence.
119
+ - Legacy `YYYY-MM-DD HH:MM:SS` is accepted only for compatibility.
120
+
62
121
  ### get_exceptions
63
122
 
64
123
  Retrieves server-side exceptions over a specified time range.
65
-
66
124
  Parameters:
67
125
 
68
126
  - `limit` (integer, optional): Maximum number of exceptions to return.
69
127
  Default: 20.
70
128
  - `lookback_minutes` (integer, recommended): Number of minutes to look back from
71
129
  now. Default: 60. Examples: 60, 30, 15.
72
- - `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD
73
- HH:MM:SS). Leave empty to use lookback_minutes.
74
- - `end_time_iso` (string, optional): End time in ISO format (YYYY-MM-DD
75
- HH:MM:SS). Leave empty to default to current time.
130
+ - `start_time_iso` (string, optional): Start time in RFC3339/ISO8601 format (e.g. 2026-02-09T15:04:05Z). Leave empty to use lookback_minutes.
131
+ - `end_time_iso` (string, optional): End time in RFC3339/ISO8601 format (e.g. 2026-02-09T16:04:05Z). Leave empty to default to current time.
132
+ - `service_name` (string, optional): Filter exceptions by service name (e.g., api-service).
76
133
  - `span_name` (string, optional): Name of the span to filter by.
134
+ - `deployment_environment` (string, optional): Filter exceptions by deployment environment from resource attributes (e.g., production, staging).
77
135
 
78
136
  ### get_service_summary
79
137
 
80
138
  Get service summary over a given time range. Includes service name, environment, throughput, error rate, and response time. All values are p95 quantiles over the time range.
81
-
82
139
  Parameters:
83
140
 
84
- - `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to end_time_iso - 1 hour.
85
- - `end_time_iso` (string, optional): End time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to current time.
141
+ - `start_time_iso` (string, optional): Start time in RFC3339/ISO8601 format (e.g. 2026-02-09T15:04:05Z). Leave empty to default to end_time_iso - 1 hour.
142
+ - `end_time_iso` (string, optional): End time in RFC3339/ISO8601 format (e.g. 2026-02-09T16:04:05Z). Leave empty to default to current time.
86
143
  - `env` (string, optional): Environment to filter by. Defaults to 'prod'.
87
144
 
88
145
  ### get_service_environments
89
146
 
90
147
  Get available environments for services. Returns an array of environments that can be used with other APM tools.
91
-
92
148
  Parameters:
93
149
 
94
- - `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to end_time_iso - 1 hour.
95
- - `end_time_iso` (string, optional): End time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to current time.
96
-
97
- Note: All other APM tools that retrieve service information (like `get_service_performance_details`, `get_service_dependency_graph`, `get_service_operations_summary`, `get_service_summary`) require an `env` parameter. This parameter must be one of the environments returned by this tool. If this tool returns an empty array, use an empty string `""` for the env parameter.
150
+ - `start_time_iso` (string, optional): Start time in RFC3339/ISO8601 format (e.g. 2026-02-09T15:04:05Z). Leave empty to default to end_time_iso - 1 hour.
151
+ - `end_time_iso` (string, optional): End time in RFC3339/ISO8601 format (e.g. 2026-02-09T16:04:05Z). Leave empty to default to current time.
152
+ Note: All other APM tools that retrieve service information (like `get_service_performance_details`, `get_service_dependency_graph`, `get_service_operations_summary`, `get_service_summary`) require an `env` parameter. This parameter must be one of the environments returned by this tool. If this tool returns an empty array, use an empty string `""` for the env parameter.
98
153
 
99
154
  ### get_service_performance_details
100
155
 
101
156
  Get detailed performance metrics for a specific service over a given time range.
102
-
103
157
  Parameters:
104
158
 
105
159
  - `service_name` (string, required): Name of the service to get performance details for.
106
- - `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to now - 60 minutes.
107
- - `end_time_iso` (string, optional): End time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to current time.
160
+ - `start_time_iso` (string, optional): Start time in RFC3339/ISO8601 format (e.g. 2026-02-09T15:04:05Z). Leave empty to default to now - 60 minutes.
161
+ - `end_time_iso` (string, optional): End time in RFC3339/ISO8601 format (e.g. 2026-02-09T16:04:05Z). Leave empty to default to current time.
108
162
  - `env` (string, optional): Environment to filter by. Defaults to 'prod'.
109
163
 
110
164
  ### get_service_operations_summary
111
165
 
112
166
  Get a summary of operations inside a service over a given time range. Returns operations like HTTP endpoints, database queries, messaging producer and HTTP client calls.
113
-
114
167
  Parameters:
115
168
 
116
169
  - `service_name` (string, required): Name of the service to get operations summary for.
117
- - `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to now - 60 minutes.
118
- - `end_time_iso` (string, optional): End time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to current time.
170
+ - `start_time_iso` (string, optional): Start time in RFC3339/ISO8601 format (e.g. 2026-02-09T15:04:05Z). Leave empty to default to now - 60 minutes.
171
+ - `end_time_iso` (string, optional): End time in RFC3339/ISO8601 format (e.g. 2026-02-09T16:04:05Z). Leave empty to default to current time.
119
172
  - `env` (string, optional): Environment to filter by. Defaults to 'prod'.
120
173
 
121
174
  ### get_service_dependency_graph
122
175
 
123
176
  Get details of the throughput, response times and error rates of incoming, outgoing and infrastructure components of a service. Useful for analyzing cascading effects of errors and performance issues.
124
-
125
177
  Parameters:
126
178
 
127
179
  - `service_name` (string, optional): Name of the service to get the dependency graph for.
128
- - `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to now - 60 minutes.
129
- - `end_time_iso` (string, optional): End time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to current time.
180
+ - `start_time_iso` (string, optional): Start time in RFC3339/ISO8601 format (e.g. 2026-02-09T15:04:05Z). Leave empty to default to now - 60 minutes.
181
+ - `end_time_iso` (string, optional): End time in RFC3339/ISO8601 format (e.g. 2026-02-09T16:04:05Z). Leave empty to default to current time.
130
182
  - `env` (string, optional): Environment to filter by. Defaults to 'prod'.
131
183
 
132
184
  ### prometheus_range_query
133
185
 
134
186
  Perform a Prometheus range query to get metrics data over a specified time range. Recommended to check available labels first using `prometheus_labels` tool.
135
-
136
187
  Parameters:
137
188
 
138
189
  - `query` (string, required): The range query to execute.
139
- - `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to now - 60 minutes.
140
- - `end_time_iso` (string, optional): End time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to current time.
190
+ - `start_time_iso` (string, optional): Start time in RFC3339/ISO8601 format (e.g. 2026-02-09T15:04:05Z). Leave empty to default to now - 60 minutes.
191
+ - `end_time_iso` (string, optional): End time in RFC3339/ISO8601 format (e.g. 2026-02-09T16:04:05Z). Leave empty to default to current time.
141
192
 
142
193
  ### prometheus_instant_query
143
194
 
144
- Perform a Prometheus instant query to get metrics data at a specific point in time. Typically should use rollup functions like sum_over_time, avg_over_time, quantile_over_time over a time window.
145
-
195
+ Perform a Prometheus instant query to get metrics data at a specific time. Typically should use rollup functions like sum_over_time, avg_over_time, quantile_over_time over a time window.
146
196
  Parameters:
147
197
 
148
198
  - `query` (string, required): The instant query to execute.
149
- - `time_iso` (string, optional): Time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to current time.
199
+ - `time_iso` (string, optional): Time in RFC3339/ISO8601 format (e.g. 2026-02-09T15:04:05Z). Leave empty to default to current time.
150
200
 
151
201
  ### prometheus_label_values
152
202
 
153
203
  Return the label values for a particular label and PromQL filter query. Similar to Prometheus /label_values call.
154
-
155
204
  Parameters:
156
205
 
157
206
  - `match_query` (string, required): A valid PromQL filter query.
158
207
  - `label` (string, required): The label to get values for.
159
- - `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to now - 60 minutes.
160
- - `end_time_iso` (string, optional): End time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to current time.
208
+ - `start_time_iso` (string, optional): Start time in RFC3339/ISO8601 format (e.g. 2026-02-09T15:04:05Z). Leave empty to default to now - 60 minutes.
209
+ - `end_time_iso` (string, optional): End time in RFC3339/ISO8601 format (e.g. 2026-02-09T16:04:05Z). Leave empty to default to current time.
161
210
 
162
211
  ### prometheus_labels
163
212
 
164
213
  Return the labels for a given PromQL match query. Similar to Prometheus /labels call.
165
-
166
214
  Parameters:
167
215
 
168
216
  - `match_query` (string, required): A valid PromQL filter query.
169
- - `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to now - 60 minutes.
170
- - `end_time_iso` (string, optional): End time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to current time.
217
+ - `start_time_iso` (string, optional): Start time in RFC3339/ISO8601 format (e.g. 2026-02-09T15:04:05Z). Leave empty to default to now - 60 minutes.
218
+ - `end_time_iso` (string, optional): End time in RFC3339/ISO8601 format (e.g. 2026-02-09T16:04:05Z). Leave empty to default to current time.
171
219
 
172
220
  ### get_logs
173
221
 
174
222
  Gets logs filtered by service name and/or severity level within a specified time range. This tool now uses the advanced v2 logs API with physical index optimization for better performance.
175
-
176
223
  **Note**: This tool now requires a `service_name` parameter and internally uses the same advanced infrastructure as `get_service_logs`.
177
-
178
224
  Parameters:
179
225
 
180
226
  - `service_name` (string, required): Name of the service to get logs for.
181
227
  - `severity` (string, optional): Severity of the logs to get (automatically converted to severity_filters format).
182
228
  - `lookback_minutes` (integer, recommended): Number of minutes to look back from now. Default: 60. Examples: 60, 30, 15.
183
- - `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to use lookback_minutes.
184
- - `end_time_iso` (string, optional): End time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to current time.
229
+ - `start_time_iso` (string, optional): Start time in RFC3339/ISO8601 format (e.g. 2026-02-09T15:04:05Z). Leave empty to use lookback_minutes.
230
+ - `end_time_iso` (string, optional): End time in RFC3339/ISO8601 format (e.g. 2026-02-09T16:04:05Z). Leave empty to default to current time.
185
231
  - `limit` (integer, optional): Maximum number of logs to return. Default: 20.
186
232
  - `env` (string, optional): Environment to filter by. Use "get_service_environments" tool to get available environments.
187
233
 
@@ -194,7 +240,6 @@ reaching Last9.
194
240
 
195
241
  Adds a new drop rule to filter out specific logs at
196
242
  [Last9 Control Plane](https://last9.io/control-plane)
197
-
198
243
  Parameters:
199
244
 
200
245
  - `name` (string, required): Name of the drop rule.
@@ -216,11 +261,8 @@ Parameters:
216
261
  ### get_alert_config
217
262
 
218
263
  Get alert configurations (alert rules) from Last9. Returns all configured alert rules including their conditions, labels, and annotations.
219
-
220
264
  Parameters:
221
-
222
265
  None - This tool retrieves all available alert configurations.
223
-
224
266
  Returns information about:
225
267
 
226
268
  - Alert rule ID and name
@@ -235,14 +277,12 @@ Returns information about:
235
277
  ### get_alerts
236
278
 
237
279
  Get currently active alerts from Last9 monitoring system. Returns all alerts that are currently firing or have fired recently within the specified time window.
238
-
239
280
  Parameters:
240
281
 
241
- - `timestamp` (integer, optional): Unix timestamp for the query time. Leave empty to default to current time.
282
+ - `time_iso` (string, optional): Evaluation time in RFC3339/ISO8601 format (e.g. 2026-02-09T15:04:05Z). Preferred.
283
+ - `timestamp` (integer, optional): Unix timestamp for the query time. Deprecated alias.
242
284
  - `window` (integer, optional): Time window in seconds to look back for alerts. Defaults to 900 seconds (15 minutes). Range: 60-86400 seconds.
243
-
244
- Returns information about:
245
-
285
+ Returns information about:
246
286
  - Alert rule details (ID, name, group, type)
247
287
  - Current state and severity
248
288
  - Last fired timestamp and duration
@@ -254,7 +294,6 @@ Returns information about:
254
294
  ### get_service_logs
255
295
 
256
296
  Get raw log entries for a specific service over a time range. This tool retrieves actual log entries including log messages, timestamps, severity levels, and other metadata. Useful for debugging issues, monitoring service behavior, and analyzing specific log patterns.
257
-
258
297
  Parameters:
259
298
 
260
299
  - `service_name` (string, required): Name of the service to get logs for.
@@ -263,147 +302,127 @@ Parameters:
263
302
  - `env` (string, optional): Environment to filter by. Use "get_service_environments" tool to get available environments.
264
303
  - `severity_filters` (array, optional): Array of severity patterns to filter logs (e.g., ["error", "warn"]). Uses OR logic.
265
304
  - `body_filters` (array, optional): Array of message content patterns to filter logs (e.g., ["timeout", "failed"]). Uses OR logic.
266
- - `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to now - lookback_minutes.
267
- - `end_time_iso` (string, optional): End time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to current time.
268
-
269
- Filtering behavior:
305
+ - `start_time_iso` (string, optional): Start time in RFC3339/ISO8601 format (e.g. 2026-02-09T15:04:05Z). Leave empty to default to now - lookback_minutes.
306
+ - `end_time_iso` (string, optional): End time in RFC3339/ISO8601 format (e.g. 2026-02-09T16:04:05Z). Leave empty to default to current time.
307
+ Filtering behavior:
270
308
  - Multiple filter types are combined with AND logic (service AND severity AND body)
271
309
  - Each filter array uses OR logic (matches any pattern in the array)
272
-
273
- Examples:
310
+ Examples:
274
311
  - service_name="api" + severity_filters=["error"] + body_filters=["timeout"] → finds error logs containing "timeout"
275
312
  - service_name="web" + body_filters=["timeout", "failed", "error 500"] → finds logs containing any of these patterns
276
313
 
277
314
  ### get_log_attributes
278
315
 
279
316
  Get available log attributes (labels) for a specified time window. This tool retrieves all attribute names that exist in logs during the specified time range, which can be used for filtering and querying logs.
280
-
281
317
  Parameters:
282
318
 
283
319
  - `lookback_minutes` (integer, optional): Number of minutes to look back from now for the time window. Default: 15. Examples: 15, 30, 60.
284
- - `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to use lookback_minutes.
285
- - `end_time_iso` (string, optional): End time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to current time.
320
+ - `start_time_iso` (string, optional): Start time in RFC3339/ISO8601 format (e.g. 2026-02-09T15:04:05Z). Leave empty to use lookback_minutes.
321
+ - `end_time_iso` (string, optional): End time in RFC3339/ISO8601 format (e.g. 2026-02-09T16:04:05Z). Leave empty to default to current time.
286
322
  - `region` (string, optional): AWS region to query. Leave empty to use default from configuration. Examples: ap-south-1, us-east-1, eu-west-1.
287
-
288
- Returns:
323
+ Returns:
289
324
  - List of log attributes grouped into two categories:
290
325
  - Log Attributes: Standard log fields like service, severity, body, level, etc.
291
- - Resource Attributes: Resource-related fields prefixed with "resource_" like resource_k8s.pod.name, resource_service.name, etc.
326
+ - Resource Attributes: Resource-related fields prefixed with "resource\_" like resource_k8s.pod.name, resource_service.name, etc.
292
327
 
293
- ### get_service_traces
328
+ ### get_traces
329
+
330
+ Execute advanced trace queries using JSON pipeline syntax for complex filtering and aggregation. This tool provides powerful querying capabilities for traces using a pipeline-based approach with filters, aggregations, and transformations.
331
+ Parameters:
294
332
 
295
- Query traces for a specific service with filtering options for span kinds, status codes, and other trace attributes. This tool retrieves distributed tracing data for debugging performance issues, understanding request flows, and analyzing service interactions.
333
+ - `tracejson_query` (array, required): JSON pipeline query for traces. Use the tracejson_query_builder prompt to generate JSON pipeline queries from natural language.
334
+ - `start_time_iso` (string, optional): Start time in RFC3339/ISO8601 format (e.g. 2026-02-09T15:04:05Z).
335
+ - `end_time_iso` (string, optional): End time in RFC3339/ISO8601 format (e.g. 2026-02-09T16:04:05Z).
336
+ - `lookback_minutes` (integer, optional): Number of minutes to look back from now. Default: 60 minutes.
337
+ - `limit` (integer, optional): Maximum number of traces to return. Default: 20. Range: 1-100.
338
+ This tool supports complex queries with multiple filter conditions, aggregations, and custom processing pipelines for advanced trace analysis.
296
339
 
340
+ ### get_service_traces
341
+
342
+ Retrieve traces from Last9 by trace ID or service name. This tool allows you to get specific traces either by providing a trace ID for a single trace, or by providing a service name to get all traces for that service within a time range.
297
343
  Parameters:
298
344
 
299
- - `service_name` (string, required): Name of the service to get traces for.
345
+ - `trace_id` (string, optional): Specific trace ID to retrieve. Cannot be used with service_name.
346
+ - `service_name` (string, optional): Name of service to get traces for. Cannot be used with trace_id.
300
347
  - `lookback_minutes` (integer, optional): Number of minutes to look back from now. Default: 60 minutes. Examples: 60, 30, 15.
301
- - `limit` (integer, optional): Maximum number of traces to return. Default: 10.
348
+ - `start_time_iso` (string, optional): Start time in RFC3339/ISO8601 format (e.g. 2026-02-09T15:04:05Z). Leave empty to use lookback_minutes.
349
+ - `end_time_iso` (string, optional): End time in RFC3339/ISO8601 format (e.g. 2026-02-09T16:04:05Z). Leave empty to default to current time.
350
+ - `limit` (integer, optional): Maximum number of traces to return. Default: 10. Range: 1-100.
302
351
  - `env` (string, optional): Environment to filter by. Use "get_service_environments" tool to get available environments.
303
- - `span_kind` (array, optional): Filter by span types (server, client, internal, consumer, producer).
304
- - `span_name` (string, optional): Filter by specific span name.
305
- - `status_code` (array, optional): Filter by trace status (ok, error, unset, success).
306
- - `order` (string, optional): Field to order traces by. Default: "Duration". Options: Duration, Timestamp.
307
- - `direction` (string, optional): Sort direction. Default: "backward". Options: forward, backward.
308
- - `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to now - lookback_minutes.
309
- - `end_time_iso` (string, optional): End time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to current time.
310
-
311
- Filtering options:
312
- - Combine multiple filters to narrow down specific traces of interest
313
- - Use time range filters with lookback_minutes or explicit start/end times
314
-
315
- Examples:
316
- - service_name="api" + span_kind=["server"] + status_code=["error"] → finds failed server-side traces
317
- - service_name="payment" + span_name="process_payment" + lookback_minutes=30 → finds payment processing traces from last 30 minutes
352
+ Usage rules:
353
+ - Exactly one of `trace_id` or `service_name` must be provided (not both, not neither)
354
+ - Time range filtering only applies when using `service_name`
355
+ Examples:
356
+ - trace_id="abc123def456" - retrieves the specific trace
357
+ - service_name="payment-service" + lookback_minutes=30 - gets all payment service traces from last 30 minutes
358
+ Returns trace data including trace IDs, spans, duration, timestamps, and status information.
318
359
 
319
360
  ### get_trace_attributes
320
361
 
321
362
  Get available trace attributes (series) for a specified time window. This tool retrieves all attribute names that exist in traces during the specified time range, which can be used for filtering and querying traces.
322
-
323
363
  Parameters:
324
364
 
325
365
  - `lookback_minutes` (integer, optional): Number of minutes to look back from now for the time window. Default: 15. Examples: 15, 30, 60.
326
- - `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to use lookback_minutes.
327
- - `end_time_iso` (string, optional): End time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to current time.
366
+ - `start_time_iso` (string, optional): Start time in RFC3339/ISO8601 format (e.g. 2026-02-09T15:04:05Z). Leave empty to use lookback_minutes.
367
+ - `end_time_iso` (string, optional): End time in RFC3339/ISO8601 format (e.g. 2026-02-09T16:04:05Z). Leave empty to default to current time.
328
368
  - `region` (string, optional): AWS region to query. Leave empty to use default from configuration. Examples: ap-south-1, us-east-1, eu-west-1.
329
-
330
- Returns:
369
+ Returns:
331
370
  - An alphabetically sorted list of all available trace attributes (e.g., http.method, http.status_code, db.name, resource_service.name, duration, etc.)
332
371
 
333
372
  ### get_change_events
334
373
 
335
374
  Get change events from the last9_change_events prometheus metric over a given time range. Returns change events that occurred in the specified time window, including deployments, configuration changes, and other system modifications.
336
-
337
375
  Parameters:
338
376
 
339
- - `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to now - lookback_minutes.
340
- - `end_time_iso` (string, optional): End time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to current time.
377
+ - `start_time_iso` (string, optional): Start time in RFC3339/ISO8601 format (e.g. 2026-02-09T15:04:05Z). Leave empty to default to now - lookback_minutes.
378
+ - `end_time_iso` (string, optional): End time in RFC3339/ISO8601 format (e.g. 2026-02-09T16:04:05Z). Leave empty to default to current time.
341
379
  - `lookback_minutes` (integer, optional): Number of minutes to look back from now. Default: 60 minutes. Examples: 60, 30, 15.
342
380
  - `service` (string, optional): Name of the service to filter change events for.
343
381
  - `environment` (string, optional): Environment to filter by.
344
382
  - `event_name` (string, optional): Name of the change event to filter by (use available_event_names to see valid values).
345
-
346
- Returns:
383
+ Returns:
347
384
  - `available_event_names`: List of all available event types that can be used for filtering
348
385
  - `change_events`: Array of timeseries data with metric labels and timestamp-value pairs
349
386
  - `count`: Total number of change events returned
350
387
  - `time_range`: Start and end time of the query window
351
-
352
- Each change event includes:
388
+ Each change event includes:
353
389
  - `metric`: Map of metric labels (service_name, env, event_type, message, etc.)
354
390
  - `values`: Array of timestamp-value pairs representing the timeseries data
391
+ Common event types include: deployment, config_change, rollback, scale_up/scale_down, restart, upgrade/downgrade, maintenance, backup/restore, health_check, certificate, database.
392
+ Best practices:
355
393
 
356
- Common event types include: deployment, config_change, rollback, scale_up/scale_down, restart, upgrade/downgrade, maintenance, backup/restore, health_check, certificate, database.
357
-
358
- Best practices:
359
394
  1. First call without event_name to get available_event_names
360
395
  2. Use exact event name from available_event_names for the event_name parameter
361
396
  3. Combine with other filters (service, environment, time) for precise results
362
397
 
363
- ## Installation
364
-
365
- You can install and run the Last9 Observability MCP server in several ways:
366
-
367
- ### Local Installation
398
+ ## Configuration
368
399
 
369
- For local development and traditional STDIO usage:
400
+ ### Managed HTTP transport (recommended)
370
401
 
371
- #### Homebrew
402
+ Set this header in your MCP client config:
372
403
 
373
- ```bash
374
- # Add the Last9 tap
375
- brew tap last9/tap
404
+ - `X-LAST9-API-TOKEN`: Bearer token for Last9 API access.
376
405
 
377
- # Install the Last9 MCP CLI
378
- brew install last9-mcp
379
- ```
406
+ ### Local STDIO server environment variables
380
407
 
381
- #### NPM
408
+ If you run the server locally (`last9-mcp`), use these environment variables:
382
409
 
383
- ```bash
384
- # Install globally
385
- npm install -g @last9/mcp-server
410
+ - `LAST9_REFRESH_TOKEN`: (required) Refresh Token with Write permissions from
411
+ [API Access](https://app.last9.io/settings/api-access). This token is used for
412
+ all authentication and will automatically obtain access tokens as needed.
413
+ - `OTEL_EXPORTER_OTLP_ENDPOINT`: (required) OpenTelemetry collector endpoint URL
414
+ - `OTEL_EXPORTER_OTLP_HEADERS`: (required) Headers for OTLP exporter authentication
386
415
 
387
- # Or run directly with npx
388
- npx @last9/mcp-server
389
- ```
390
-
391
- ## Configuration
392
-
393
- ### Environment Variables
416
+ Optional environment variables:
394
417
 
395
- The Last9 MCP server requires the following environment variables:
396
-
397
- - `LAST9_BASE_URL`: (required) Last9 API URL from
398
- [OTel integration](https://app.last9.io/integrations?integration=OpenTelemetry)
399
- - `LAST9_AUTH_TOKEN`: (required) Authentication token for Last9 MCP server from
400
- [OTel integration](https://app.last9.io/integrations?integration=OpenTelemetry)
401
- - `LAST9_REFRESH_TOKEN`: (required) Refresh Token with Write permissions, needed
402
- for accessing control plane APIs from
403
- [API Access](https://app.last9.io/settings/api-access)
418
+ - `LAST9_DATASOURCE`: Name of the datasource/cluster to use. If not specified, the default datasource configured in your Last9 organization will be used.
419
+ - `LAST9_API_HOST`: API host to connect to. Defaults to `app.last9.io`. Use this if you need to connect to a different Last9 endpoint (e.g., regional or self-hosted instances).
420
+ - `LAST9_DISABLE_TELEMETRY`: Set to `true` to disable OpenTelemetry tracing and metrics. Use this if you don't have an OTLP collector running or want to skip telemetry.
404
421
 
405
422
  ## Usage
406
423
 
424
+ Use the managed HTTP transport config from [Installation](#installation) whenever possible. The examples below are for local STDIO setup via Homebrew or NPM.
425
+
407
426
  ## Usage with Claude Desktop
408
427
 
409
428
  Configure the Claude app to use the MCP server:
@@ -415,15 +434,16 @@ Configure the Claude app to use the MCP server:
415
434
  5. Restart Claude
416
435
 
417
436
  ### If installed via Homebrew:
437
+
418
438
  ```json
419
439
  {
420
440
  "mcpServers": {
421
441
  "last9": {
422
442
  "command": "/opt/homebrew/bin/last9-mcp",
423
443
  "env": {
424
- "LAST9_BASE_URL": "<last9_otlp_host>",
425
- "LAST9_AUTH_TOKEN": "<last9_otlp_auth_token>",
426
- "LAST9_REFRESH_TOKEN": "<last9_write_refresh_token>"
444
+ "LAST9_REFRESH_TOKEN": "<last9_refresh_token>",
445
+ "OTEL_EXPORTER_OTLP_ENDPOINT": "<otel_endpoint_url>",
446
+ "OTEL_EXPORTER_OTLP_HEADERS": "<otel_headers>"
427
447
  }
428
448
  }
429
449
  }
@@ -431,16 +451,17 @@ Configure the Claude app to use the MCP server:
431
451
  ```
432
452
 
433
453
  ### If installed via NPM:
454
+
434
455
  ```json
435
456
  {
436
457
  "mcpServers": {
437
458
  "last9": {
438
459
  "command": "npx",
439
- "args": ["-y", "@last9/mcp-server"],
460
+ "args": ["-y", "@last9/mcp-server@latest"],
440
461
  "env": {
441
- "LAST9_BASE_URL": "<last9_otlp_host>",
442
- "LAST9_AUTH_TOKEN": "<last9_otlp_auth_token>",
443
- "LAST9_REFRESH_TOKEN": "<last9_write_refresh_token>"
462
+ "LAST9_REFRESH_TOKEN": "<last9_refresh_token>",
463
+ "OTEL_EXPORTER_OTLP_ENDPOINT": "<otel_endpoint_url>",
464
+ "OTEL_EXPORTER_OTLP_HEADERS": "<otel_headers>"
444
465
  }
445
466
  }
446
467
  }
@@ -458,15 +479,16 @@ Configure Cursor to use the MCP server:
458
479
  5. Restart Cursor
459
480
 
460
481
  ### If installed via Homebrew:
482
+
461
483
  ```json
462
484
  {
463
485
  "mcpServers": {
464
486
  "last9": {
465
487
  "command": "/opt/homebrew/bin/last9-mcp",
466
488
  "env": {
467
- "LAST9_BASE_URL": "<last9_otlp_host>",
468
- "LAST9_AUTH_TOKEN": "<last9_otlp_auth_token>",
469
- "LAST9_REFRESH_TOKEN": "<last9_write_refresh_token>"
489
+ "LAST9_REFRESH_TOKEN": "<last9_refresh_token>",
490
+ "OTEL_EXPORTER_OTLP_ENDPOINT": "<otel_endpoint_url>",
491
+ "OTEL_EXPORTER_OTLP_HEADERS": "<otel_headers>"
470
492
  }
471
493
  }
472
494
  }
@@ -474,16 +496,17 @@ Configure Cursor to use the MCP server:
474
496
  ```
475
497
 
476
498
  ### If installed via NPM:
499
+
477
500
  ```json
478
501
  {
479
502
  "mcpServers": {
480
503
  "last9": {
481
504
  "command": "npx",
482
- "args": ["-y", "@last9/mcp-server"],
505
+ "args": ["-y", "@last9/mcp-server@latest"],
483
506
  "env": {
484
- "LAST9_BASE_URL": "<last9_otlp_host>",
485
- "LAST9_AUTH_TOKEN": "<last9_otlp_auth_token>",
486
- "LAST9_REFRESH_TOKEN": "<last9_write_refresh_token>"
507
+ "LAST9_REFRESH_TOKEN": "<last9_refresh_token>",
508
+ "OTEL_EXPORTER_OTLP_ENDPOINT": "<otel_endpoint_url>",
509
+ "OTEL_EXPORTER_OTLP_HEADERS": "<otel_headers>"
487
510
  }
488
511
  }
489
512
  }
@@ -501,15 +524,16 @@ Configure Windsurf to use the MCP server:
501
524
  5. Restart Windsurf
502
525
 
503
526
  ### If installed via Homebrew:
527
+
504
528
  ```json
505
529
  {
506
530
  "mcpServers": {
507
531
  "last9": {
508
532
  "command": "/opt/homebrew/bin/last9-mcp",
509
533
  "env": {
510
- "LAST9_BASE_URL": "<last9_otlp_host>",
511
- "LAST9_AUTH_TOKEN": "<last9_otlp_auth_token>",
512
- "LAST9_REFRESH_TOKEN": "<last9_write_refresh_token>"
534
+ "LAST9_REFRESH_TOKEN": "<last9_refresh_token>",
535
+ "OTEL_EXPORTER_OTLP_ENDPOINT": "<otel_endpoint_url>",
536
+ "OTEL_EXPORTER_OTLP_HEADERS": "<otel_headers>"
513
537
  }
514
538
  }
515
539
  }
@@ -517,16 +541,17 @@ Configure Windsurf to use the MCP server:
517
541
  ```
518
542
 
519
543
  ### If installed via NPM:
544
+
520
545
  ```json
521
546
  {
522
547
  "mcpServers": {
523
548
  "last9": {
524
549
  "command": "npx",
525
- "args": ["-y", "@last9/mcp-server"],
550
+ "args": ["-y", "@last9/mcp-server@latest"],
526
551
  "env": {
527
- "LAST9_BASE_URL": "<last9_otlp_host>",
528
- "LAST9_AUTH_TOKEN": "<last9_otlp_auth_token>",
529
- "LAST9_REFRESH_TOKEN": "<last9_write_refresh_token>"
552
+ "LAST9_REFRESH_TOKEN": "<last9_refresh_token>",
553
+ "OTEL_EXPORTER_OTLP_ENDPOINT": "<otel_endpoint_url>",
554
+ "OTEL_EXPORTER_OTLP_HEADERS": "<otel_headers>"
530
555
  }
531
556
  }
532
557
  }
@@ -545,6 +570,7 @@ Configure Windsurf to use the MCP server:
545
570
  4. Restart VS Code
546
571
 
547
572
  ### If installed via Homebrew:
573
+
548
574
  ```json
549
575
  {
550
576
  "mcp": {
@@ -553,9 +579,9 @@ Configure Windsurf to use the MCP server:
553
579
  "type": "stdio",
554
580
  "command": "/opt/homebrew/bin/last9-mcp",
555
581
  "env": {
556
- "LAST9_BASE_URL": "<last9_otlp_host>",
557
- "LAST9_AUTH_TOKEN": "<last9_otlp_auth_token>",
558
- "LAST9_REFRESH_TOKEN": "<last9_write_refresh_token>"
582
+ "LAST9_REFRESH_TOKEN": "<last9_refresh_token>",
583
+ "OTEL_EXPORTER_OTLP_ENDPOINT": "<otel_endpoint_url>",
584
+ "OTEL_EXPORTER_OTLP_HEADERS": "<otel_headers>"
559
585
  }
560
586
  }
561
587
  }
@@ -564,6 +590,7 @@ Configure Windsurf to use the MCP server:
564
590
  ```
565
591
 
566
592
  ### If installed via NPM:
593
+
567
594
  ```json
568
595
  {
569
596
  "mcp": {
@@ -571,11 +598,11 @@ Configure Windsurf to use the MCP server:
571
598
  "last9": {
572
599
  "type": "stdio",
573
600
  "command": "npx",
574
- "args": ["-y", "@last9/mcp-server"],
601
+ "args": ["-y", "@last9/mcp-server@latest"],
575
602
  "env": {
576
- "LAST9_BASE_URL": "<last9_otlp_host>",
577
- "LAST9_AUTH_TOKEN": "<last9_otlp_auth_token>",
578
- "LAST9_REFRESH_TOKEN": "<last9_write_refresh_token>"
603
+ "LAST9_REFRESH_TOKEN": "<last9_refresh_token>",
604
+ "OTEL_EXPORTER_OTLP_ENDPOINT": "<otel_endpoint_url>",
605
+ "OTEL_EXPORTER_OTLP_HEADERS": "<otel_headers>"
579
606
  }
580
607
  }
581
608
  }
@@ -589,15 +616,15 @@ For local development and testing, you can run the MCP server in HTTP mode which
589
616
 
590
617
  ### Running in HTTP Mode
591
618
 
592
- Set the `HTTP_MODE` environment variable to enable HTTP server mode:
619
+ Set the `LAST9_HTTP` environment variable to enable HTTP server mode:
593
620
 
594
621
  ```bash
595
622
  # Export required environment variables
596
- export LAST9_API_TOKEN="your_api_token"
597
- export LAST9_BASE_URL="https://your-last9-endpoint" # Your Last9 endpoint
598
- export HTTP_MODE=true
599
- export HTTP_PORT=8080 # Optional, defaults to 8080
600
-
623
+ export LAST9_REFRESH_TOKEN="your_refresh_token"
624
+ export OTEL_EXPORTER_OTLP_ENDPOINT="<otel_endpoint_url>"
625
+ export OTEL_EXPORTER_OTLP_HEADERS="<otel_headers>"
626
+ export LAST9_HTTP=true
627
+ export LAST9_PORT=8080 # Optional, defaults to 8080
601
628
  # Run the server
602
629
  ./last9-mcp-server
603
630
  ```
@@ -624,7 +651,6 @@ curl -X POST http://localhost:8080/mcp \
624
651
  }
625
652
  }
626
653
  }'
627
-
628
654
  # Test get_service_traces
629
655
  curl -X POST http://localhost:8080/mcp \
630
656
  -H "Content-Type: application/json" \
@@ -642,7 +668,6 @@ curl -X POST http://localhost:8080/mcp \
642
668
  }
643
669
  }
644
670
  }'
645
-
646
671
  # List available tools
647
672
  curl -X POST http://localhost:8080/mcp \
648
673
  -H "Content-Type: application/json" \
@@ -661,15 +686,17 @@ curl -X POST http://localhost:8080/mcp \
661
686
  # Clone the repository
662
687
  git clone https://github.com/last9/last9-mcp-server.git
663
688
  cd last9-mcp-server
664
-
665
689
  # Build the binary
666
690
  go build -o last9-mcp-server
667
-
668
691
  # Run in development mode
669
- HTTP_MODE=true ./last9-mcp-server
692
+ LAST9_HTTP=true ./last9-mcp-server
670
693
  ```
671
694
 
672
- **Note**: HTTP mode is for development and testing only. When integrating with Claude Desktop or other MCP clients, use the default STDIO mode (without `HTTP_MODE=true`).
695
+ **Note**: `LAST9_HTTP=true` is for local development and debugging of your own server process. For normal client integration, prefer the managed HTTP endpoint from [Installation](#installation).
696
+
697
+ ## Testing
698
+
699
+ See [TESTING.md](TESTING.md) for detailed testing instructions.
673
700
 
674
701
  ## Badges
675
702