@last9/mcp-server 0.2.0 → 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 +184 -204
  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,38 +99,36 @@ 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_traces`: Retrieve traces by trace ID or service name with time range filtering.
49
- - `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.
50
105
  - `get_trace_attributes`: Get available trace attributes (series) for a specified time window.
51
-
52
- **Change Events:**
53
-
106
+ **Change Events:**
54
107
  - `get_change_events`: Get change events from the last9_change_events prometheus metric over a given time range.
55
-
56
- **Alert Management:**
57
-
108
+ **Alert Management:**
58
109
  - `get_alert_config`: Get alert configurations (alert rules) from Last9.
59
110
  - `get_alerts`: Get currently active alerts from Last9 monitoring system.
60
111
 
61
112
  ## Tools Documentation
62
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
+
63
121
  ### get_exceptions
64
122
 
65
123
  Retrieves server-side exceptions over a specified time range.
66
-
67
124
  Parameters:
68
125
 
69
126
  - `limit` (integer, optional): Maximum number of exceptions to return.
70
127
  Default: 20.
71
128
  - `lookback_minutes` (integer, recommended): Number of minutes to look back from
72
129
  now. Default: 60. Examples: 60, 30, 15.
73
- - `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD
74
- HH:MM:SS). Leave empty to use lookback_minutes.
75
- - `end_time_iso` (string, optional): End time in ISO format (YYYY-MM-DD
76
- 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.
77
132
  - `service_name` (string, optional): Filter exceptions by service name (e.g., api-service).
78
133
  - `span_name` (string, optional): Name of the span to filter by.
79
134
  - `deployment_environment` (string, optional): Filter exceptions by deployment environment from resource attributes (e.g., production, staging).
@@ -81,110 +136,98 @@ Parameters:
81
136
  ### get_service_summary
82
137
 
83
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.
84
-
85
139
  Parameters:
86
140
 
87
- - `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.
88
- - `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.
89
143
  - `env` (string, optional): Environment to filter by. Defaults to 'prod'.
90
144
 
91
145
  ### get_service_environments
92
146
 
93
147
  Get available environments for services. Returns an array of environments that can be used with other APM tools.
94
-
95
148
  Parameters:
96
149
 
97
- - `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.
98
- - `end_time_iso` (string, optional): End time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to current time.
99
-
100
- 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.
101
153
 
102
154
  ### get_service_performance_details
103
155
 
104
156
  Get detailed performance metrics for a specific service over a given time range.
105
-
106
157
  Parameters:
107
158
 
108
159
  - `service_name` (string, required): Name of the service to get performance details for.
109
- - `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to now - 60 minutes.
110
- - `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.
111
162
  - `env` (string, optional): Environment to filter by. Defaults to 'prod'.
112
163
 
113
164
  ### get_service_operations_summary
114
165
 
115
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.
116
-
117
167
  Parameters:
118
168
 
119
169
  - `service_name` (string, required): Name of the service to get operations summary for.
120
- - `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to now - 60 minutes.
121
- - `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.
122
172
  - `env` (string, optional): Environment to filter by. Defaults to 'prod'.
123
173
 
124
174
  ### get_service_dependency_graph
125
175
 
126
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.
127
-
128
177
  Parameters:
129
178
 
130
179
  - `service_name` (string, optional): Name of the service to get the dependency graph for.
131
- - `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to now - 60 minutes.
132
- - `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.
133
182
  - `env` (string, optional): Environment to filter by. Defaults to 'prod'.
134
183
 
135
184
  ### prometheus_range_query
136
185
 
137
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.
138
-
139
187
  Parameters:
140
188
 
141
189
  - `query` (string, required): The range query to execute.
142
- - `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to now - 60 minutes.
143
- - `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.
144
192
 
145
193
  ### prometheus_instant_query
146
194
 
147
- 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.
148
-
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.
149
196
  Parameters:
150
197
 
151
198
  - `query` (string, required): The instant query to execute.
152
- - `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.
153
200
 
154
201
  ### prometheus_label_values
155
202
 
156
203
  Return the label values for a particular label and PromQL filter query. Similar to Prometheus /label_values call.
157
-
158
204
  Parameters:
159
205
 
160
206
  - `match_query` (string, required): A valid PromQL filter query.
161
207
  - `label` (string, required): The label to get values for.
162
- - `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to now - 60 minutes.
163
- - `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.
164
210
 
165
211
  ### prometheus_labels
166
212
 
167
213
  Return the labels for a given PromQL match query. Similar to Prometheus /labels call.
168
-
169
214
  Parameters:
170
215
 
171
216
  - `match_query` (string, required): A valid PromQL filter query.
172
- - `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to now - 60 minutes.
173
- - `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.
174
219
 
175
220
  ### get_logs
176
221
 
177
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.
178
-
179
223
  **Note**: This tool now requires a `service_name` parameter and internally uses the same advanced infrastructure as `get_service_logs`.
180
-
181
224
  Parameters:
182
225
 
183
226
  - `service_name` (string, required): Name of the service to get logs for.
184
227
  - `severity` (string, optional): Severity of the logs to get (automatically converted to severity_filters format).
185
228
  - `lookback_minutes` (integer, recommended): Number of minutes to look back from now. Default: 60. Examples: 60, 30, 15.
186
- - `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to use lookback_minutes.
187
- - `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.
188
231
  - `limit` (integer, optional): Maximum number of logs to return. Default: 20.
189
232
  - `env` (string, optional): Environment to filter by. Use "get_service_environments" tool to get available environments.
190
233
 
@@ -197,7 +240,6 @@ reaching Last9.
197
240
 
198
241
  Adds a new drop rule to filter out specific logs at
199
242
  [Last9 Control Plane](https://last9.io/control-plane)
200
-
201
243
  Parameters:
202
244
 
203
245
  - `name` (string, required): Name of the drop rule.
@@ -219,11 +261,8 @@ Parameters:
219
261
  ### get_alert_config
220
262
 
221
263
  Get alert configurations (alert rules) from Last9. Returns all configured alert rules including their conditions, labels, and annotations.
222
-
223
264
  Parameters:
224
-
225
265
  None - This tool retrieves all available alert configurations.
226
-
227
266
  Returns information about:
228
267
 
229
268
  - Alert rule ID and name
@@ -238,14 +277,12 @@ Returns information about:
238
277
  ### get_alerts
239
278
 
240
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.
241
-
242
280
  Parameters:
243
281
 
244
- - `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.
245
284
  - `window` (integer, optional): Time window in seconds to look back for alerts. Defaults to 900 seconds (15 minutes). Range: 60-86400 seconds.
246
-
247
- Returns information about:
248
-
285
+ Returns information about:
249
286
  - Alert rule details (ID, name, group, type)
250
287
  - Current state and severity
251
288
  - Last fired timestamp and duration
@@ -257,7 +294,6 @@ Returns information about:
257
294
  ### get_service_logs
258
295
 
259
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.
260
-
261
297
  Parameters:
262
298
 
263
299
  - `service_name` (string, required): Name of the service to get logs for.
@@ -266,173 +302,127 @@ Parameters:
266
302
  - `env` (string, optional): Environment to filter by. Use "get_service_environments" tool to get available environments.
267
303
  - `severity_filters` (array, optional): Array of severity patterns to filter logs (e.g., ["error", "warn"]). Uses OR logic.
268
304
  - `body_filters` (array, optional): Array of message content patterns to filter logs (e.g., ["timeout", "failed"]). Uses OR logic.
269
- - `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to now - lookback_minutes.
270
- - `end_time_iso` (string, optional): End time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to current time.
271
-
272
- 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:
273
308
  - Multiple filter types are combined with AND logic (service AND severity AND body)
274
309
  - Each filter array uses OR logic (matches any pattern in the array)
275
-
276
- Examples:
310
+ Examples:
277
311
  - service_name="api" + severity_filters=["error"] + body_filters=["timeout"] → finds error logs containing "timeout"
278
312
  - service_name="web" + body_filters=["timeout", "failed", "error 500"] → finds logs containing any of these patterns
279
313
 
280
314
  ### get_log_attributes
281
315
 
282
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.
283
-
284
317
  Parameters:
285
318
 
286
319
  - `lookback_minutes` (integer, optional): Number of minutes to look back from now for the time window. Default: 15. Examples: 15, 30, 60.
287
- - `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to use lookback_minutes.
288
- - `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.
289
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.
290
-
291
- Returns:
323
+ Returns:
292
324
  - List of log attributes grouped into two categories:
293
325
  - Log Attributes: Standard log fields like service, severity, body, level, etc.
294
- - 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.
295
327
 
296
328
  ### get_traces
297
329
 
298
- 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.
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:
332
+
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.
339
+
340
+ ### get_service_traces
299
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.
300
343
  Parameters:
301
344
 
302
345
  - `trace_id` (string, optional): Specific trace ID to retrieve. Cannot be used with service_name.
303
346
  - `service_name` (string, optional): Name of service to get traces for. Cannot be used with trace_id.
304
347
  - `lookback_minutes` (integer, optional): Number of minutes to look back from now. Default: 60 minutes. Examples: 60, 30, 15.
305
- - `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to now - lookback_minutes.
306
- - `end_time_iso` (string, optional): End time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to current time.
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.
307
350
  - `limit` (integer, optional): Maximum number of traces to return. Default: 10. Range: 1-100.
308
351
  - `env` (string, optional): Environment to filter by. Use "get_service_environments" tool to get available environments.
309
-
310
- Usage rules:
352
+ Usage rules:
311
353
  - Exactly one of `trace_id` or `service_name` must be provided (not both, not neither)
312
354
  - Time range filtering only applies when using `service_name`
313
-
314
- Examples:
355
+ Examples:
315
356
  - trace_id="abc123def456" - retrieves the specific trace
316
357
  - service_name="payment-service" + lookback_minutes=30 - gets all payment service traces from last 30 minutes
317
-
318
- Returns trace data including trace IDs, spans, duration, timestamps, and status information.
319
-
320
- ### get_service_traces
321
-
322
- 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.
323
-
324
- Parameters:
325
-
326
- - `service_name` (string, required): Name of the service to get traces for.
327
- - `lookback_minutes` (integer, optional): Number of minutes to look back from now. Default: 60 minutes. Examples: 60, 30, 15.
328
- - `limit` (integer, optional): Maximum number of traces to return. Default: 10.
329
- - `env` (string, optional): Environment to filter by. Use "get_service_environments" tool to get available environments.
330
- - `span_kind` (array, optional): Filter by span types (server, client, internal, consumer, producer).
331
- - `span_name` (string, optional): Filter by specific span name.
332
- - `status_code` (array, optional): Filter by trace status (ok, error, unset, success).
333
- - `order` (string, optional): Field to order traces by. Default: "Duration". Options: Duration, Timestamp.
334
- - `direction` (string, optional): Sort direction. Default: "backward". Options: forward, backward.
335
- - `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to now - lookback_minutes.
336
- - `end_time_iso` (string, optional): End time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to current time.
337
-
338
- Filtering options:
339
- - Combine multiple filters to narrow down specific traces of interest
340
- - Use time range filters with lookback_minutes or explicit start/end times
341
-
342
- Examples:
343
- - service_name="api" + span_kind=["server"] + status_code=["error"] → finds failed server-side traces
344
- - service_name="payment" + span_name="process_payment" + lookback_minutes=30 → finds payment processing traces from last 30 minutes
358
+ Returns trace data including trace IDs, spans, duration, timestamps, and status information.
345
359
 
346
360
  ### get_trace_attributes
347
361
 
348
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.
349
-
350
363
  Parameters:
351
364
 
352
365
  - `lookback_minutes` (integer, optional): Number of minutes to look back from now for the time window. Default: 15. Examples: 15, 30, 60.
353
- - `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to use lookback_minutes.
354
- - `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.
355
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.
356
-
357
- Returns:
369
+ Returns:
358
370
  - An alphabetically sorted list of all available trace attributes (e.g., http.method, http.status_code, db.name, resource_service.name, duration, etc.)
359
371
 
360
372
  ### get_change_events
361
373
 
362
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.
363
-
364
375
  Parameters:
365
376
 
366
- - `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to now - lookback_minutes.
367
- - `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.
368
379
  - `lookback_minutes` (integer, optional): Number of minutes to look back from now. Default: 60 minutes. Examples: 60, 30, 15.
369
380
  - `service` (string, optional): Name of the service to filter change events for.
370
381
  - `environment` (string, optional): Environment to filter by.
371
382
  - `event_name` (string, optional): Name of the change event to filter by (use available_event_names to see valid values).
372
-
373
- Returns:
383
+ Returns:
374
384
  - `available_event_names`: List of all available event types that can be used for filtering
375
385
  - `change_events`: Array of timeseries data with metric labels and timestamp-value pairs
376
386
  - `count`: Total number of change events returned
377
387
  - `time_range`: Start and end time of the query window
378
-
379
- Each change event includes:
388
+ Each change event includes:
380
389
  - `metric`: Map of metric labels (service_name, env, event_type, message, etc.)
381
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:
382
393
 
383
- Common event types include: deployment, config_change, rollback, scale_up/scale_down, restart, upgrade/downgrade, maintenance, backup/restore, health_check, certificate, database.
384
-
385
- Best practices:
386
394
  1. First call without event_name to get available_event_names
387
395
  2. Use exact event name from available_event_names for the event_name parameter
388
396
  3. Combine with other filters (service, environment, time) for precise results
389
397
 
390
- ## Installation
391
-
392
- You can install and run the Last9 Observability MCP server in several ways:
393
-
394
- ### Local Installation
395
-
396
- For local development and traditional STDIO usage:
397
-
398
- #### Homebrew
399
-
400
- ```bash
401
- # Add the Last9 tap
402
- brew tap last9/tap
403
-
404
- # Install the Last9 MCP CLI
405
- brew install last9-mcp
406
- ```
407
-
408
- #### NPM
398
+ ## Configuration
409
399
 
410
- ```bash
411
- # Install globally
412
- npm install -g @last9/mcp-server
400
+ ### Managed HTTP transport (recommended)
413
401
 
414
- # Or run directly with npx
415
- npx @last9/mcp-server
416
- ```
402
+ Set this header in your MCP client config:
417
403
 
418
- ## Configuration
404
+ - `X-LAST9-API-TOKEN`: Bearer token for Last9 API access.
419
405
 
420
- ### Environment Variables
406
+ ### Local STDIO server environment variables
421
407
 
422
- The Last9 MCP server requires the following environment variables:
408
+ If you run the server locally (`last9-mcp`), use these environment variables:
423
409
 
424
- - `LAST9_BASE_URL`: (required) Last9 API URL from
425
- [OTel integration](https://app.last9.io/integrations?integration=OpenTelemetry)
426
- - `LAST9_AUTH_TOKEN`: (required) Authentication token for Last9 MCP server from
427
- [OTel integration](https://app.last9.io/integrations?integration=OpenTelemetry)
428
- - `LAST9_REFRESH_TOKEN`: (required) Refresh Token with Write permissions, needed
429
- for accessing control plane APIs from
430
- [API Access](https://app.last9.io/settings/api-access)
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.
431
413
  - `OTEL_EXPORTER_OTLP_ENDPOINT`: (required) OpenTelemetry collector endpoint URL
432
414
  - `OTEL_EXPORTER_OTLP_HEADERS`: (required) Headers for OTLP exporter authentication
433
415
 
416
+ Optional environment variables:
417
+
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.
421
+
434
422
  ## Usage
435
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
+
436
426
  ## Usage with Claude Desktop
437
427
 
438
428
  Configure the Claude app to use the MCP server:
@@ -444,15 +434,14 @@ Configure the Claude app to use the MCP server:
444
434
  5. Restart Claude
445
435
 
446
436
  ### If installed via Homebrew:
437
+
447
438
  ```json
448
439
  {
449
440
  "mcpServers": {
450
441
  "last9": {
451
442
  "command": "/opt/homebrew/bin/last9-mcp",
452
443
  "env": {
453
- "LAST9_BASE_URL": "<last9_otlp_host>",
454
- "LAST9_AUTH_TOKEN": "<last9_otlp_auth_token>",
455
- "LAST9_REFRESH_TOKEN": "<last9_write_refresh_token>",
444
+ "LAST9_REFRESH_TOKEN": "<last9_refresh_token>",
456
445
  "OTEL_EXPORTER_OTLP_ENDPOINT": "<otel_endpoint_url>",
457
446
  "OTEL_EXPORTER_OTLP_HEADERS": "<otel_headers>"
458
447
  }
@@ -462,16 +451,15 @@ Configure the Claude app to use the MCP server:
462
451
  ```
463
452
 
464
453
  ### If installed via NPM:
454
+
465
455
  ```json
466
456
  {
467
457
  "mcpServers": {
468
458
  "last9": {
469
459
  "command": "npx",
470
- "args": ["-y", "@last9/mcp-server"],
460
+ "args": ["-y", "@last9/mcp-server@latest"],
471
461
  "env": {
472
- "LAST9_BASE_URL": "<last9_otlp_host>",
473
- "LAST9_AUTH_TOKEN": "<last9_otlp_auth_token>",
474
- "LAST9_REFRESH_TOKEN": "<last9_write_refresh_token>",
462
+ "LAST9_REFRESH_TOKEN": "<last9_refresh_token>",
475
463
  "OTEL_EXPORTER_OTLP_ENDPOINT": "<otel_endpoint_url>",
476
464
  "OTEL_EXPORTER_OTLP_HEADERS": "<otel_headers>"
477
465
  }
@@ -491,15 +479,14 @@ Configure Cursor to use the MCP server:
491
479
  5. Restart Cursor
492
480
 
493
481
  ### If installed via Homebrew:
482
+
494
483
  ```json
495
484
  {
496
485
  "mcpServers": {
497
486
  "last9": {
498
487
  "command": "/opt/homebrew/bin/last9-mcp",
499
488
  "env": {
500
- "LAST9_BASE_URL": "<last9_otlp_host>",
501
- "LAST9_AUTH_TOKEN": "<last9_otlp_auth_token>",
502
- "LAST9_REFRESH_TOKEN": "<last9_write_refresh_token>",
489
+ "LAST9_REFRESH_TOKEN": "<last9_refresh_token>",
503
490
  "OTEL_EXPORTER_OTLP_ENDPOINT": "<otel_endpoint_url>",
504
491
  "OTEL_EXPORTER_OTLP_HEADERS": "<otel_headers>"
505
492
  }
@@ -509,16 +496,15 @@ Configure Cursor to use the MCP server:
509
496
  ```
510
497
 
511
498
  ### If installed via NPM:
499
+
512
500
  ```json
513
501
  {
514
502
  "mcpServers": {
515
503
  "last9": {
516
504
  "command": "npx",
517
- "args": ["-y", "@last9/mcp-server"],
505
+ "args": ["-y", "@last9/mcp-server@latest"],
518
506
  "env": {
519
- "LAST9_BASE_URL": "<last9_otlp_host>",
520
- "LAST9_AUTH_TOKEN": "<last9_otlp_auth_token>",
521
- "LAST9_REFRESH_TOKEN": "<last9_write_refresh_token>",
507
+ "LAST9_REFRESH_TOKEN": "<last9_refresh_token>",
522
508
  "OTEL_EXPORTER_OTLP_ENDPOINT": "<otel_endpoint_url>",
523
509
  "OTEL_EXPORTER_OTLP_HEADERS": "<otel_headers>"
524
510
  }
@@ -538,15 +524,14 @@ Configure Windsurf to use the MCP server:
538
524
  5. Restart Windsurf
539
525
 
540
526
  ### If installed via Homebrew:
527
+
541
528
  ```json
542
529
  {
543
530
  "mcpServers": {
544
531
  "last9": {
545
532
  "command": "/opt/homebrew/bin/last9-mcp",
546
533
  "env": {
547
- "LAST9_BASE_URL": "<last9_otlp_host>",
548
- "LAST9_AUTH_TOKEN": "<last9_otlp_auth_token>",
549
- "LAST9_REFRESH_TOKEN": "<last9_write_refresh_token>",
534
+ "LAST9_REFRESH_TOKEN": "<last9_refresh_token>",
550
535
  "OTEL_EXPORTER_OTLP_ENDPOINT": "<otel_endpoint_url>",
551
536
  "OTEL_EXPORTER_OTLP_HEADERS": "<otel_headers>"
552
537
  }
@@ -556,16 +541,15 @@ Configure Windsurf to use the MCP server:
556
541
  ```
557
542
 
558
543
  ### If installed via NPM:
544
+
559
545
  ```json
560
546
  {
561
547
  "mcpServers": {
562
548
  "last9": {
563
549
  "command": "npx",
564
- "args": ["-y", "@last9/mcp-server"],
550
+ "args": ["-y", "@last9/mcp-server@latest"],
565
551
  "env": {
566
- "LAST9_BASE_URL": "<last9_otlp_host>",
567
- "LAST9_AUTH_TOKEN": "<last9_otlp_auth_token>",
568
- "LAST9_REFRESH_TOKEN": "<last9_write_refresh_token>",
552
+ "LAST9_REFRESH_TOKEN": "<last9_refresh_token>",
569
553
  "OTEL_EXPORTER_OTLP_ENDPOINT": "<otel_endpoint_url>",
570
554
  "OTEL_EXPORTER_OTLP_HEADERS": "<otel_headers>"
571
555
  }
@@ -586,6 +570,7 @@ Configure Windsurf to use the MCP server:
586
570
  4. Restart VS Code
587
571
 
588
572
  ### If installed via Homebrew:
573
+
589
574
  ```json
590
575
  {
591
576
  "mcp": {
@@ -594,9 +579,7 @@ Configure Windsurf to use the MCP server:
594
579
  "type": "stdio",
595
580
  "command": "/opt/homebrew/bin/last9-mcp",
596
581
  "env": {
597
- "LAST9_BASE_URL": "<last9_otlp_host>",
598
- "LAST9_AUTH_TOKEN": "<last9_otlp_auth_token>",
599
- "LAST9_REFRESH_TOKEN": "<last9_write_refresh_token>",
582
+ "LAST9_REFRESH_TOKEN": "<last9_refresh_token>",
600
583
  "OTEL_EXPORTER_OTLP_ENDPOINT": "<otel_endpoint_url>",
601
584
  "OTEL_EXPORTER_OTLP_HEADERS": "<otel_headers>"
602
585
  }
@@ -607,6 +590,7 @@ Configure Windsurf to use the MCP server:
607
590
  ```
608
591
 
609
592
  ### If installed via NPM:
593
+
610
594
  ```json
611
595
  {
612
596
  "mcp": {
@@ -614,11 +598,9 @@ Configure Windsurf to use the MCP server:
614
598
  "last9": {
615
599
  "type": "stdio",
616
600
  "command": "npx",
617
- "args": ["-y", "@last9/mcp-server"],
601
+ "args": ["-y", "@last9/mcp-server@latest"],
618
602
  "env": {
619
- "LAST9_BASE_URL": "<last9_otlp_host>",
620
- "LAST9_AUTH_TOKEN": "<last9_otlp_auth_token>",
621
- "LAST9_REFRESH_TOKEN": "<last9_write_refresh_token>",
603
+ "LAST9_REFRESH_TOKEN": "<last9_refresh_token>",
622
604
  "OTEL_EXPORTER_OTLP_ENDPOINT": "<otel_endpoint_url>",
623
605
  "OTEL_EXPORTER_OTLP_HEADERS": "<otel_headers>"
624
606
  }
@@ -634,17 +616,15 @@ For local development and testing, you can run the MCP server in HTTP mode which
634
616
 
635
617
  ### Running in HTTP Mode
636
618
 
637
- Set the `HTTP_MODE` environment variable to enable HTTP server mode:
619
+ Set the `LAST9_HTTP` environment variable to enable HTTP server mode:
638
620
 
639
621
  ```bash
640
622
  # Export required environment variables
641
- export LAST9_API_TOKEN="your_api_token"
642
- export LAST9_BASE_URL="https://your-last9-endpoint" # Your Last9 endpoint
623
+ export LAST9_REFRESH_TOKEN="your_refresh_token"
643
624
  export OTEL_EXPORTER_OTLP_ENDPOINT="<otel_endpoint_url>"
644
625
  export OTEL_EXPORTER_OTLP_HEADERS="<otel_headers>"
645
- export HTTP_MODE=true
646
- export HTTP_PORT=8080 # Optional, defaults to 8080
647
-
626
+ export LAST9_HTTP=true
627
+ export LAST9_PORT=8080 # Optional, defaults to 8080
648
628
  # Run the server
649
629
  ./last9-mcp-server
650
630
  ```
@@ -671,7 +651,6 @@ curl -X POST http://localhost:8080/mcp \
671
651
  }
672
652
  }
673
653
  }'
674
-
675
654
  # Test get_service_traces
676
655
  curl -X POST http://localhost:8080/mcp \
677
656
  -H "Content-Type: application/json" \
@@ -689,7 +668,6 @@ curl -X POST http://localhost:8080/mcp \
689
668
  }
690
669
  }
691
670
  }'
692
-
693
671
  # List available tools
694
672
  curl -X POST http://localhost:8080/mcp \
695
673
  -H "Content-Type: application/json" \
@@ -708,15 +686,17 @@ curl -X POST http://localhost:8080/mcp \
708
686
  # Clone the repository
709
687
  git clone https://github.com/last9/last9-mcp-server.git
710
688
  cd last9-mcp-server
711
-
712
689
  # Build the binary
713
690
  go build -o last9-mcp-server
714
-
715
691
  # Run in development mode
716
- HTTP_MODE=true ./last9-mcp-server
692
+ LAST9_HTTP=true ./last9-mcp-server
717
693
  ```
718
694
 
719
- **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.
720
700
 
721
701
  ## Badges
722
702