@last9/mcp-server 0.5.1 → 0.6.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 (2) hide show
  1. package/README.md +398 -629
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,504 +1,132 @@
1
1
  # Last9 MCP Server
2
2
 
3
3
  ![last9 mcp demo](mcp-demo.gif)
4
- A [Model Context Protocol](https://modelcontextprotocol.io/) server
5
- implementation for [Last9](https://last9.io/mcp/) that enables AI agents to
6
- seamlessly bring real-time production context — logs, metrics, and traces — into
7
- your local environment to auto-fix code faster.
8
4
 
9
- - [View demo](https://www.youtube.com/watch?v=AQH5xq6qzjI)
10
- - Read our
11
- [announcement blog post](https://last9.io/blog/launching-last9-mcp-server/)
5
+ Your AI agent doesn't know what's broken in production. This fixes that.
12
6
 
13
- ## Quick Links
7
+ [Last9 MCP Server](https://last9.io/mcp/) connects Claude, Cursor, Windsurf, and any other MCP-capable AI assistant directly to your production observability data — logs, metrics, traces, exceptions, database queries, alerts, and deployments. The agent stops guessing and starts reading the actual signal.
14
8
 
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)
9
+ - [Watch the demo](https://www.youtube.com/watch?v=AQH5xq6qzjI)
10
+ - [Announcement post](https://last9.io/blog/launching-last9-mcp-server/)
23
11
 
24
- ## Installation
12
+ ---
25
13
 
26
- You can connect to Last9 MCP in two ways:
14
+ ## Start in 30 seconds (Hosted)
27
15
 
28
- ### Recommended: Managed MCP over HTTP
16
+ No binary to install. No tokens to manage. One URL, OAuth in your browser, done.
29
17
 
30
- This is the easiest and cleanest setup. You do not need to run a local binary.
31
- You'll need a **Client Token** (MCP type) — see [Getting your credentials](#getting-your-credentials) below. Your org slug is in your Last9 URL: `app.last9.io/<org_slug>/...`
18
+ Find your org slug in your Last9 URL: `app.last9.io/<org_slug>/...`
19
+
20
+ ### Claude Code
32
21
 
33
22
  ```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>"
23
+ claude mcp add --transport http last9 https://app.last9.io/api/v4/organizations/<org_slug>/mcp
36
24
  ```
37
25
 
38
- Or add it directly to your MCP client config:
26
+ Type `/mcp`, select last9, authenticate. That's it.
27
+
28
+ ### Cursor
29
+
30
+ **Settings > MCP > Add New MCP Server:**
39
31
 
40
32
  ```json
41
33
  {
42
34
  "mcpServers": {
43
35
  "last9": {
44
36
  "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
- }
37
+ "url": "https://app.last9.io/api/v4/organizations/<org_slug>/mcp"
49
38
  }
50
39
  }
51
40
  }
52
41
  ```
53
42
 
54
- ### Local Installation (STDIO fallback)
43
+ Click **Connect**, complete OAuth.
55
44
 
56
- Use this only if your client needs a local STDIO server process.
45
+ ### VS Code
57
46
 
58
- #### Homebrew
47
+ Requires v1.99+. Open Command Palette → **MCP: Add Server**, paste the URL, authenticate.
59
48
 
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
49
+ Or directly in `settings.json`:
68
50
 
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
51
+ ```json
52
+ {
53
+ "mcp": {
54
+ "servers": {
55
+ "last9": {
56
+ "type": "http",
57
+ "url": "https://app.last9.io/api/v4/organizations/<org_slug>/mcp"
58
+ }
59
+ }
60
+ }
61
+ }
74
62
  ```
75
63
 
76
- #### GitHub Releases (Windows / manual install)
77
-
78
- Download the binary for your platform from [GitHub Releases](https://github.com/last9/last9-mcp-server/releases/latest):
79
-
80
- | Platform | Archive |
81
- |----------|---------|
82
- | Windows (x64) | `last9-mcp-server_Windows_x86_64.zip` |
83
- | Windows (ARM64) | `last9-mcp-server_Windows_arm64.zip` |
84
- | Linux (x64) | `last9-mcp-server_Linux_x86_64.tar.gz` |
85
- | Linux (ARM64) | `last9-mcp-server_Linux_arm64.tar.gz` |
86
- | macOS (x64) | `last9-mcp-server_Darwin_x86_64.tar.gz` |
87
- | macOS (ARM64) | `last9-mcp-server_Darwin_arm64.tar.gz` |
88
-
89
- Extract the archive. On Windows the binary is `last9-mcp-server.exe`. Use the full path to the binary in your MCP client config (see [Windows example](#windows-example-claude-desktop) below).
90
-
91
- > On Windows, [NPM](#npm) is easier to set up (no path management needed), or use the [hosted HTTP transport](#recommended-managed-mcp-over-http) to skip local installation entirely.
92
-
93
- ## Getting Your Credentials
94
-
95
- ### For hosted MCP (recommended)
96
-
97
- You need a **Client Token** with MCP type. Only **admins** can create tokens. If you're not an admin, ask your admin to create one or grant you admin access via [User Access settings](https://app.last9.io/settings/user-access).
98
-
99
- 1. Go to [Ingestion Tokens](https://app.last9.io/control-plane/ingestion-tokens)
100
- 2. Click **New Ingestion Token**
101
- 3. Set **Token Type** to **Client**
102
- 4. Set **Client Type** to **MCP**
103
- 5. Enter a name (e.g., `claude-desktop`, `cursor`)
104
- 6. Click **Create** — copy the token immediately (shown only once)
105
-
106
- Your **organization slug** is in your Last9 URL: `https://app.last9.io/<org_slug>/...`
107
-
108
- ### For local binary (STDIO mode)
109
-
110
- You need a **Refresh Token** with Write permissions. Only **admins** can create them.
111
-
112
- 1. Go to [API Access](https://app.last9.io/settings/api-access)
113
- 2. Click **Generate Token** with Write permissions
114
- 3. Copy the token
115
-
116
- ## Status
117
-
118
- Works with Claude desktop app, or Cursor, Windsurf, and VSCode (Github Copilot)
119
- IDEs. Implements the following MCP
120
- [tools](https://modelcontextprotocol.io/docs/concepts/tools):
121
- **Observability & APM Tools:**
122
-
123
- - `get_exceptions`: Get the list of exceptions.
124
- - `get_service_summary`: Get service summary with throughput, error rate, and response time.
125
- - `get_service_environments`: Get available environments for services.
126
- - `get_service_performance_details`: Get detailed performance metrics for a service.
127
- - `get_service_operations_summary`: Get operations summary for a service.
128
- - `get_service_dependency_graph`: Get service dependency graph showing incoming/outgoing dependencies.
129
- **Prometheus/PromQL Tools:**
130
- - `prometheus_range_query`: Execute PromQL range queries for metrics data.
131
- - `prometheus_instant_query`: Execute PromQL instant queries for metrics data.
132
- - `prometheus_label_values`: Get label values for PromQL queries.
133
- - `prometheus_labels`: Get available labels for PromQL queries.
134
- **Logs Management:**
135
- - `get_logs`: Get logs filtered by service name and/or severity level.
136
- - `get_drop_rules`: Get drop rules for logs that determine what logs get
137
- filtered out at [Last9 Control Plane](https://last9.io/control-plane)
138
- - `add_drop_rule`: Create a drop rule for logs at
139
- [Last9 Control Plane](https://last9.io/control-plane)
140
- - `get_service_logs`: Get raw log entries for a specific service over a time range. Can apply filters on severity and body.
141
- - `get_log_attributes`: Get available log attributes (labels) for a specified time window.
142
- **Traces Management:**
143
- - `get_traces`: Retrieve traces using JSON pipeline queries for advanced filtering.
144
- - `get_service_traces`: Retrieve traces by trace ID or service name with time range filtering.
145
- - `get_trace_attributes`: Get available trace attributes (series) for a specified time window.
146
- **Change Events:**
147
- - `get_change_events`: Get change events from the last9_change_events prometheus metric over a given time range.
148
- **Alert Management:**
149
- - `get_alert_config`: Get alert configurations (alert rules) from Last9.
150
- - `get_alerts`: Get currently active alerts from Last9 monitoring system.
151
-
152
- ## Tools Documentation
153
-
154
- ### Time Input Standard
155
-
156
- - For relative windows, prefer `lookback_minutes` (up to 20160 minutes = 14 days).
157
- - For absolute windows, use `start_time_iso`, `end_time_iso`, or `time_iso` in RFC3339/ISO8601 (for example, `2026-02-09T15:04:05Z`).
158
- - If both relative and absolute inputs are provided, absolute time inputs take precedence.
159
- - Legacy `YYYY-MM-DD HH:MM:SS` is accepted only for compatibility.
160
- - If a lookback limit error occurs, retry using explicit `start_time_iso`/`end_time_iso` timestamps.
161
-
162
- ### Deep Links
163
-
164
- Most tools return a `deep_link` field in the response metadata. This is a direct URL to the relevant Last9 dashboard view for the queried data — click it to open the corresponding alerts, logs, traces, or APM dashboard page.
165
-
166
- ### Attribute Caching
167
-
168
- The server automatically fetches and caches available log and trace attribute names at startup (with a 10-second timeout) and refreshes the cache every 2 hours in the background. These dynamic attributes are embedded into the `get_logs`, `get_traces`, and `prometheus_range_query` tool descriptions, so AI assistants always see up-to-date field names when constructing queries.
169
-
170
- ### get_exceptions
171
-
172
- Retrieves server-side exceptions over a specified time range.
173
- Parameters:
174
-
175
- - `limit` (integer, optional): Maximum number of exceptions to return.
176
- Default: 20.
177
- - `lookback_minutes` (integer, recommended): Number of minutes to look back from
178
- now. Default: 60. Range: 1–20160 (14 days). Examples: 60, 30, 15.
179
- - `start_time_iso` (string, optional): Start time in RFC3339/ISO8601 format (e.g. 2026-02-09T15:04:05Z). Leave empty to use lookback_minutes.
180
- - `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.
181
- - `service_name` (string, optional): Filter exceptions by service name (e.g., api-service).
182
- - `span_name` (string, optional): Name of the span to filter by.
183
- - `deployment_environment` (string, optional): Filter exceptions by deployment environment from resource attributes (e.g., production, staging).
184
-
185
- ### get_service_summary
186
-
187
- 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.
188
- Parameters:
189
-
190
- - `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.
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.
192
- - `env` (string, optional): Environment to filter by. Defaults to 'prod'.
193
-
194
- ### get_service_environments
195
-
196
- Get available environments for services. Returns an array of environments that can be used with other APM tools.
197
- Parameters:
198
-
199
- - `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.
200
- - `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.
201
- 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.
202
-
203
- ### get_service_performance_details
204
-
205
- Get detailed performance metrics for a specific service over a given time range.
206
- Parameters:
207
-
208
- - `service_name` (string, required): Name of the service to get performance details for.
209
- - `lookback_minutes` (integer, optional): Number of minutes to look back from now. Default: 60. Range: 1–20160 (14 days).
210
- - `start_time_iso` (string, optional): Start time in RFC3339/ISO8601 format (e.g. 2026-02-09T15:04:05Z). Leave empty to use lookback_minutes.
211
- - `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.
212
- - `env` (string, optional): Environment to filter by. Defaults to 'prod'.
213
- Returns: throughput, error rate, p50/p90/p95/avg/max response times, apdex score, availability, top operations, and top errors.
214
-
215
- ### get_service_operations_summary
216
-
217
- 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.
218
- Parameters:
219
-
220
- - `service_name` (string, required): Name of the service to get operations summary for.
221
- - `lookback_minutes` (integer, optional): Number of minutes to look back from now. Default: 60. Range: 1–20160 (14 days).
222
- - `start_time_iso` (string, optional): Start time in RFC3339/ISO8601 format (e.g. 2026-02-09T15:04:05Z). Leave empty to use lookback_minutes.
223
- - `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.
224
- - `env` (string, optional): Environment to filter by. Defaults to 'prod'.
225
- Each operation includes: throughput (rpm), error rate (rpm), error percentage, and p50/p90/p95/avg/max response times (ms).
226
-
227
- ### get_service_dependency_graph
228
-
229
- 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.
230
- Parameters:
231
-
232
- - `service_name` (string, optional): Name of the service to get the dependency graph for.
233
- - `lookback_minutes` (integer, optional): Number of minutes to look back from now. Default: 60. Range: 1–20160 (14 days).
234
- - `start_time_iso` (string, optional): Start time in RFC3339/ISO8601 format (e.g. 2026-02-09T15:04:05Z). Leave empty to use lookback_minutes.
235
- - `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.
236
- - `env` (string, optional): Environment to filter by. Defaults to 'prod'.
237
- Each node includes: throughput (rpm), error rate (rpm), error percentage, and p50/p90/p95/avg/max response times (ms).
238
-
239
- ### prometheus_range_query
240
-
241
- Perform a Prometheus range query to get metrics data over a specified time range. Recommended to check available labels first using `prometheus_labels` tool.
242
- Parameters:
243
-
244
- - `query` (string, required): The range query to execute.
245
- - `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.
246
- - `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.
247
-
248
- ### prometheus_instant_query
249
-
250
- 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.
251
- Parameters:
252
-
253
- - `query` (string, required): The instant query to execute.
254
- - `time_iso` (string, optional): Time in RFC3339/ISO8601 format (e.g. 2026-02-09T15:04:05Z). Leave empty to default to current time.
255
-
256
- ### prometheus_label_values
257
-
258
- Return the label values for a particular label and PromQL filter query. Similar to Prometheus /label_values call.
259
- Parameters:
260
-
261
- - `match_query` (string, required): A valid PromQL filter query.
262
- - `label` (string, required): The label to get values for.
263
- - `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.
264
- - `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.
265
-
266
- ### prometheus_labels
267
-
268
- Return the labels for a given PromQL match query. Similar to Prometheus /labels call.
269
- Parameters:
270
-
271
- - `match_query` (string, required): A valid PromQL filter query.
272
- - `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.
273
- - `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.
274
-
275
- ### get_logs
276
-
277
- 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.
278
- **Note**: This tool now requires a `service_name` parameter and internally uses the same advanced infrastructure as `get_service_logs`.
279
- Parameters:
280
-
281
- - `service_name` (string, required): Name of the service to get logs for.
282
- - `severity` (string, optional): Severity of the logs to get (automatically converted to severity_filters format).
283
- - `lookback_minutes` (integer, recommended): Number of minutes to look back from now. Default: 60. Range: 1–20160 (14 days). Examples: 60, 30, 15.
284
- - `start_time_iso` (string, optional): Start time in RFC3339/ISO8601 format (e.g. 2026-02-09T15:04:05Z). Leave empty to use lookback_minutes.
285
- - `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
- - `limit` (integer, optional): Maximum number of logs to return. Default: 20.
287
- - `env` (string, optional): Environment to filter by. Use "get_service_environments" tool to get available environments.
288
-
289
- ### get_drop_rules
290
-
291
- Gets drop rules for logs, which determine what logs get filtered out from
292
- reaching Last9.
293
-
294
- ### add_drop_rule
295
-
296
- Adds a new drop rule to filter out specific logs at
297
- [Last9 Control Plane](https://last9.io/control-plane)
298
- Parameters:
299
-
300
- - `name` (string, required): Name of the drop rule.
301
- - `filters` (array, required): List of filter conditions to apply. Each filter
302
- has:
303
- - `key` (string, required): The key to filter on. Only attributes and
304
- resource.attributes keys are supported. For resource attributes, use format:
305
- resource.attributes[key_name] and for log attributes, use format:
306
- attributes[key_name] Double quotes in key names must be escaped.
307
- - `value` (string, required): The value to filter against.
308
- - `operator` (string, required): The operator used for filtering. Valid
309
- values:
310
- - "equals"
311
- - "not_equals"
312
- - `conjunction` (string, required): The logical conjunction between filters.
313
- Valid values:
314
- - "and"
315
-
316
- ### get_alert_config
317
-
318
- Get alert configurations (alert rules) from Last9. Returns all configured alert rules including their conditions, labels, and annotations.
319
- Parameters:
320
- None - This tool retrieves all available alert configurations.
321
- Returns information about:
322
-
323
- - Alert rule ID and name
324
- - Primary indicator being monitored
325
- - Current state and severity
326
- - Algorithm used for alerting
327
- - Entity ID and organization details
328
- - Properties and configuration
329
- - Creation and update timestamps
330
- - Group timeseries notification settings
331
-
332
- ### get_alerts
333
-
334
- Get currently active alerts from Last9 monitoring system. Returns all alerts that are currently firing or have fired recently within the specified time window.
335
- Parameters:
336
-
337
- - `time_iso` (string, optional): Evaluation time in RFC3339/ISO8601 format (e.g. 2026-02-09T15:04:05Z). Preferred.
338
- - `timestamp` (integer, optional): Unix timestamp for the query time. Deprecated alias.
339
- - `window` (integer, optional): Time window in seconds to look back for alerts. Defaults to 900 seconds (15 minutes). Range: 60-86400 seconds.
340
- - `lookback_minutes` (integer, optional): Relative time window in minutes. Used only when `window` is not provided. Range: 1-1440.
341
- Returns information about:
342
- - Alert rule details (ID, name, group, type)
343
- - Current state and severity
344
- - Last fired timestamp and duration
345
- - Rule properties and configuration
346
- - Alert instances with current values
347
- - Metric degradation information
348
- - Group labels and annotations for each instance
349
-
350
- ### get_service_logs
351
-
352
- 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.
353
- Parameters:
354
-
355
- - `service_name` (string, required): Name of the service to get logs for.
356
- - `lookback_minutes` (integer, optional): Number of minutes to look back from now. Default: 60. Range: 1–20160 (14 days). Examples: 60, 30, 15.
357
- - `limit` (integer, optional): Maximum number of log entries to return. Default: 20.
358
- - `env` (string, optional): Environment to filter by. Use "get_service_environments" tool to get available environments.
359
- - `severity_filters` (array, optional): Array of severity patterns to filter logs (e.g., ["error", "warn"]). Uses OR logic.
360
- - `body_filters` (array, optional): Array of message content patterns to filter logs (e.g., ["timeout", "failed"]). Uses OR logic.
361
- - `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.
362
- - `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.
363
- Filtering behavior:
364
- - Multiple filter types are combined with AND logic (service AND severity AND body)
365
- - Each filter array uses OR logic (matches any pattern in the array)
366
- Examples:
367
- - service_name="api" + severity_filters=["error"] + body_filters=["timeout"] → finds error logs containing "timeout"
368
- - service_name="web" + body_filters=["timeout", "failed", "error 500"] → finds logs containing any of these patterns
369
-
370
- ### get_log_attributes
371
-
372
- 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.
373
- Parameters:
374
-
375
- - `lookback_minutes` (integer, optional): Number of minutes to look back from now for the time window. Default: 15. Examples: 15, 30, 60.
376
- - `start_time_iso` (string, optional): Start time in RFC3339/ISO8601 format (e.g. 2026-02-09T15:04:05Z). Leave empty to use lookback_minutes.
377
- - `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.
378
- - `region` (string, optional): AWS region to query. Leave empty to use default from configuration. Examples: ap-south-1, us-east-1, eu-west-1.
379
- Returns:
380
- - List of log attributes grouped into two categories:
381
- - Log Attributes: Standard log fields like service, severity, body, level, etc.
382
- - Resource Attributes: Resource-related fields prefixed with "resource\_" like resource_k8s.pod.name, resource_service.name, etc.
383
-
384
- ### get_traces
385
-
386
- 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.
387
- Parameters:
388
-
389
- - `tracejson_query` (array, required): JSON pipeline query for traces. Use the tracejson_query_builder prompt to generate JSON pipeline queries from natural language.
390
- - `start_time_iso` (string, optional): Start time in RFC3339/ISO8601 format (e.g. 2026-02-09T15:04:05Z).
391
- - `end_time_iso` (string, optional): End time in RFC3339/ISO8601 format (e.g. 2026-02-09T16:04:05Z).
392
- - `lookback_minutes` (integer, optional): Number of minutes to look back from now. Default: 60. Range: 1–20160 (14 days).
393
- - `limit` (integer, optional): Maximum number of traces to return. Default: 20. Range: 1-100.
394
- This tool supports complex queries with multiple filter conditions, aggregations, and custom processing pipelines for advanced trace analysis.
395
-
396
- ### get_service_traces
397
-
398
- 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.
399
- Parameters:
400
-
401
- - `trace_id` (string, optional): Specific trace ID to retrieve. Cannot be used with service_name.
402
- - `service_name` (string, optional): Name of service to get traces for. Cannot be used with trace_id.
403
- - `lookback_minutes` (integer, optional): Number of minutes to look back from now. Default: 60. Range: 1–20160 (14 days). Examples: 60, 30, 15.
404
- - `start_time_iso` (string, optional): Start time in RFC3339/ISO8601 format (e.g. 2026-02-09T15:04:05Z). Leave empty to use lookback_minutes.
405
- - `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.
406
- - `limit` (integer, optional): Maximum number of traces to return. Default: 10. Range: 1-100.
407
- - `env` (string, optional): Environment to filter by. Use "get_service_environments" tool to get available environments.
408
- Usage rules:
409
- - Exactly one of `trace_id` or `service_name` must be provided (not both, not neither)
410
- - Time range filtering only applies when using `service_name`
411
- Examples:
412
- - trace_id="abc123def456" - retrieves the specific trace
413
- - service_name="payment-service" + lookback_minutes=30 - gets all payment service traces from last 30 minutes
414
- Returns trace data including trace IDs, spans, duration, timestamps, and status information.
415
-
416
- ### get_trace_attributes
417
-
418
- 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.
419
- Parameters:
64
+ ### Windsurf
420
65
 
421
- - `lookback_minutes` (integer, optional): Number of minutes to look back from now for the time window. Default: 15. Examples: 15, 30, 60.
422
- - `start_time_iso` (string, optional): Start time in RFC3339/ISO8601 format (e.g. 2026-02-09T15:04:05Z). Leave empty to use lookback_minutes.
423
- - `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.
424
- - `region` (string, optional): AWS region to query. Leave empty to use default from configuration. Examples: ap-south-1, us-east-1, eu-west-1.
425
- Returns:
426
- - An alphabetically sorted list of all available trace attributes (e.g., http.method, http.status_code, db.name, resource_service.name, duration, etc.)
66
+ **Settings > Cascade > Open MCP Marketplace > gear icon (`mcp_config.json`):**
427
67
 
428
- ### get_change_events
429
-
430
- 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.
431
- Parameters:
432
-
433
- - `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.
434
- - `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.
435
- - `lookback_minutes` (integer, optional): Number of minutes to look back from now. Default: 60. Range: 1–20160 (14 days). Examples: 60, 30, 15.
436
- - `service` (string, optional): Name of the service to filter change events for.
437
- - `environment` (string, optional): Environment to filter by.
438
- - `event_name` (string, optional): Name of the change event to filter by (use available_event_names to see valid values).
439
- Returns:
440
- - `available_event_names`: List of all available event types that can be used for filtering
441
- - `change_events`: Array of timeseries data with metric labels and timestamp-value pairs
442
- - `count`: Total number of change events returned
443
- - `time_range`: Start and end time of the query window
444
- Each change event includes:
445
- - `metric`: Map of metric labels (service_name, env, event_type, message, etc.)
446
- - `values`: Array of timestamp-value pairs representing the timeseries data
447
- Common event types include: deployment, config_change, rollback, scale_up/scale_down, restart, upgrade/downgrade, maintenance, backup/restore, health_check, certificate, database.
448
- Best practices:
449
-
450
- 1. First call without event_name to get available_event_names
451
- 2. Use exact event name from available_event_names for the event_name parameter
452
- 3. Combine with other filters (service, environment, time) for precise results
68
+ ```json
69
+ {
70
+ "mcpServers": {
71
+ "last9": {
72
+ "serverUrl": "https://app.last9.io/api/v4/organizations/<org_slug>/mcp"
73
+ }
74
+ }
75
+ }
76
+ ```
453
77
 
454
- ## Configuration
78
+ ### Claude Web/Desktop
455
79
 
456
- ### Managed HTTP transport (recommended)
80
+ **Settings > Connectors > Add custom connector.** Name it `last9`, paste the URL, authenticate.
457
81
 
458
- Set this header in your MCP client config:
82
+ > Requires admin access to your Claude organization.
459
83
 
460
- - `X-LAST9-API-TOKEN`: Bearer token for Last9 API access.
84
+ ---
461
85
 
462
- ### Local STDIO server environment variables
86
+ ## Self-Hosted (STDIO)
463
87
 
464
- If you run the server locally (`last9-mcp`), use these environment variables:
88
+ Use this when your MCP client doesn't support HTTP transport, or when you need the server running locally.
465
89
 
466
- - `LAST9_REFRESH_TOKEN`: (required) Refresh Token with Write permissions from
467
- [API Access](https://app.last9.io/settings/api-access). Only admins can create
468
- refresh tokens.
90
+ ### Install
469
91
 
470
- Optional environment variables:
92
+ **Homebrew:**
471
93
 
472
- - `LAST9_DISABLE_TELEMETRY`: Defaults to `true` (telemetry is disabled by default). Set to `false` to enable OpenTelemetry tracing if you have an OTLP collector configured.
473
- - `OTEL_SDK_DISABLED`: Standard OTel env var. Set to `false` to enable telemetry (overrides `LAST9_DISABLE_TELEMETRY`). Set to `true` to disable telemetry explicitly.
474
- - `OTEL_EXPORTER_OTLP_ENDPOINT`: OpenTelemetry collector endpoint URL. Only needed if telemetry is enabled.
475
- - `OTEL_EXPORTER_OTLP_HEADERS`: Headers for OTLP exporter authentication. Only needed when telemetry is enabled (i.e., `OTEL_SDK_DISABLED` is not `true` and `LAST9_DISABLE_TELEMETRY` is not `true`).
476
- - `LAST9_DATASOURCE`: Name of the datasource/cluster to use. If not specified, the default datasource configured in your Last9 organization will be used.
477
- - `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).
94
+ ```bash
95
+ brew install last9/tap/last9-mcp
96
+ ```
478
97
 
479
- ## Usage
98
+ **NPM:**
480
99
 
481
- Use the managed HTTP transport config from [Installation](#installation) whenever possible. The examples below are for local STDIO setup via Homebrew or NPM.
100
+ ```bash
101
+ npm install -g @last9/mcp-server@latest
102
+ # or directly:
103
+ npx -y @last9/mcp-server@latest
104
+ ```
482
105
 
483
- ## Usage with Claude Desktop
106
+ **Binary releases** (Windows / manual):
484
107
 
485
- Configure the Claude app to use the MCP server:
108
+ Download from [GitHub Releases](https://github.com/last9/last9-mcp-server/releases/latest):
486
109
 
487
- 1. Open the Claude Desktop app, go to Settings, then Developer
488
- 2. Click Edit Config
489
- 3. Open the `claude_desktop_config.json` file
490
- 4. Copy and paste the server config to your existing file, then save
491
- 5. Restart Claude
110
+ | Platform | Archive |
111
+ | --------------- | --------------------------------------- |
112
+ | Windows (x64) | `last9-mcp-server_Windows_x86_64.zip` |
113
+ | Windows (ARM64) | `last9-mcp-server_Windows_arm64.zip` |
114
+ | Linux (x64) | `last9-mcp-server_Linux_x86_64.tar.gz` |
115
+ | Linux (ARM64) | `last9-mcp-server_Linux_arm64.tar.gz` |
116
+ | macOS (x64) | `last9-mcp-server_Darwin_x86_64.tar.gz` |
117
+ | macOS (ARM64) | `last9-mcp-server_Darwin_arm64.tar.gz` |
492
118
 
493
- ### Local STDIO
119
+ ### Get a Refresh Token
494
120
 
495
- > **Note:** Claude Desktop currently supports local STDIO-based MCP servers only. Hosted HTTP transport is not yet supported in Claude Desktop.
121
+ Only **admins** can create tokens.
496
122
 
497
- Use a [Refresh Token](#getting-your-credentials).
123
+ 1. Go to [API Access](https://app.last9.io/settings/api-access)
124
+ 2. Click **Generate Token** with Write permissions
125
+ 3. Copy it
498
126
 
499
- Install via [Homebrew](#homebrew) or [NPM](#npm) first, then use a [Refresh Token](#getting-your-credentials).
127
+ ### Client Configuration
500
128
 
501
- ### If installed via Homebrew:
129
+ **Homebrew:**
502
130
 
503
131
  ```json
504
132
  {
@@ -506,14 +134,14 @@ Install via [Homebrew](#homebrew) or [NPM](#npm) first, then use a [Refresh Toke
506
134
  "last9": {
507
135
  "command": "/opt/homebrew/bin/last9-mcp",
508
136
  "env": {
509
- "LAST9_REFRESH_TOKEN": "<last9_refresh_token>"
137
+ "LAST9_REFRESH_TOKEN": "<your_refresh_token>"
510
138
  }
511
139
  }
512
140
  }
513
141
  }
514
142
  ```
515
143
 
516
- ### If installed via NPM:
144
+ **NPM:**
517
145
 
518
146
  ```json
519
147
  {
@@ -522,244 +150,173 @@ Install via [Homebrew](#homebrew) or [NPM](#npm) first, then use a [Refresh Toke
522
150
  "command": "npx",
523
151
  "args": ["-y", "@last9/mcp-server@latest"],
524
152
  "env": {
525
- "LAST9_REFRESH_TOKEN": "<last9_refresh_token>"
153
+ "LAST9_REFRESH_TOKEN": "<your_refresh_token>"
526
154
  }
527
155
  }
528
156
  }
529
157
  }
530
158
  ```
531
159
 
532
- ## Usage with Cursor
533
-
534
- Configure Cursor to use the MCP server:
160
+ **Where to paste this:**
535
161
 
536
- 1. Open Cursor, go to Settings, then Cursor Settings
537
- 2. Select MCP on the left
538
- 3. Click Add "New Global MCP Server" at the top right
539
- 4. Copy and paste the server config to your existing file, then save
540
- 5. Restart Cursor
162
+ | Client | Location |
163
+ | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
164
+ | Claude Web/Desktop | Settings > Developer > Edit Config (`claude_desktop_config.json`) |
165
+ | Cursor | Settings > Cursor Settings > MCP > Add New Global MCP Server |
166
+ | Windsurf | Settings > Cascade > MCP Marketplace > gear icon (`mcp_config.json`) |
167
+ | VS Code | Wrap in `{ "mcp": { "servers": { ... } } }` in `settings.json` — [details](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) |
541
168
 
542
- ### Hosted MCP over HTTP (recommended)
169
+ <details>
170
+ <summary>VS Code STDIO config</summary>
543
171
 
544
172
  ```json
545
173
  {
546
- "mcpServers": {
547
- "last9": {
548
- "type": "http",
549
- "url": "https://app.last9.io/api/v4/organizations/<org_slug>/mcp",
550
- "headers": {
551
- "X-LAST9-API-TOKEN": "Bearer <mcp_client_token>"
174
+ "mcp": {
175
+ "servers": {
176
+ "last9": {
177
+ "type": "stdio",
178
+ "command": "/opt/homebrew/bin/last9-mcp",
179
+ "env": {
180
+ "LAST9_REFRESH_TOKEN": "<your_refresh_token>"
181
+ }
552
182
  }
553
183
  }
554
184
  }
555
185
  }
556
186
  ```
557
187
 
558
- ### Local STDIO (alternative)
188
+ For NPM: use `"command": "npx"` and add `"args": ["-y", "@last9/mcp-server@latest"]`.
559
189
 
560
- ### If installed via Homebrew:
190
+ </details>
561
191
 
562
- ```json
563
- {
564
- "mcpServers": {
565
- "last9": {
566
- "command": "/opt/homebrew/bin/last9-mcp",
567
- "env": {
568
- "LAST9_REFRESH_TOKEN": "<last9_refresh_token>"
569
- }
570
- }
571
- }
572
- }
573
- ```
192
+ <details>
193
+ <summary>Windows</summary>
574
194
 
575
- ### If installed via NPM:
195
+ After downloading from [GitHub Releases](https://github.com/last9/last9-mcp-server/releases/latest), extract and point to the full path:
576
196
 
577
197
  ```json
578
198
  {
579
199
  "mcpServers": {
580
200
  "last9": {
581
- "command": "npx",
582
- "args": ["-y", "@last9/mcp-server@latest"],
201
+ "command": "C:\\Users\\<user>\\AppData\\Local\\Programs\\last9-mcp-server.exe",
583
202
  "env": {
584
- "LAST9_REFRESH_TOKEN": "<last9_refresh_token>"
203
+ "LAST9_REFRESH_TOKEN": "<your_refresh_token>"
585
204
  }
586
205
  }
587
206
  }
588
207
  }
589
208
  ```
590
209
 
591
- ## Usage with Windsurf
210
+ The NPM route is easier on Windows — no path management.
592
211
 
593
- Configure Windsurf to use the MCP server:
212
+ </details>
594
213
 
595
- 1. Open Windsurf, go to Settings, then Developer
596
- 2. Click Edit Config
597
- 3. Open the `windsurf_config.json` file
598
- 4. Copy and paste the server config to your existing file, then save
599
- 5. Restart Windsurf
214
+ ### Environment Variables
600
215
 
601
- ### Hosted MCP over HTTP (recommended)
216
+ | Variable | Default | Description |
217
+ | ---------------------------- | -------------------- | ----------- |
218
+ | `LAST9_REFRESH_TOKEN` | *(required)* | Refresh token from [API Access](https://app.last9.io/settings/api-access) |
219
+ | `LAST9_DATASOURCE` | org default | Datasource/cluster name — useful when you have multiple Levitate clusters |
220
+ | `LAST9_API_HOST` | `app.last9.io` | Override the API host |
221
+ | `LAST9_MAX_GET_LOGS_ENTRIES` | `5000` | Max entries for chunked `get_logs` requests |
222
+ | `LAST9_DEBUG_CHUNKING` | `false` | Set `true` to log chunk-planning details for `get_logs`, `get_service_logs`, `get_traces` |
223
+ | `LAST9_DISABLE_TELEMETRY` | `true` | Set `false` to enable internal OTel tracing |
224
+ | `OTEL_SDK_DISABLED` | — | Standard OTel env var. Overrides `LAST9_DISABLE_TELEMETRY` |
225
+ | `OTEL_EXPORTER_OTLP_ENDPOINT`| — | OTLP collector endpoint (only when telemetry is enabled) |
226
+ | `OTEL_EXPORTER_OTLP_HEADERS` | — | OTLP auth headers (only when telemetry is enabled) |
602
227
 
603
- ```json
604
- {
605
- "mcpServers": {
606
- "last9": {
607
- "type": "http",
608
- "url": "https://app.last9.io/api/v4/organizations/<org_slug>/mcp",
609
- "headers": {
610
- "X-LAST9-API-TOKEN": "Bearer <mcp_client_token>"
611
- }
612
- }
613
- }
614
- }
615
- ```
228
+ ---
616
229
 
617
- ### Local STDIO (alternative)
230
+ ## What It Can Do
618
231
 
619
- ### If installed via Homebrew:
232
+ ### Service Health
620
233
 
621
- ```json
622
- {
623
- "mcpServers": {
624
- "last9": {
625
- "command": "/opt/homebrew/bin/last9-mcp",
626
- "env": {
627
- "LAST9_REFRESH_TOKEN": "<last9_refresh_token>"
628
- }
629
- }
630
- }
631
- }
632
- ```
234
+ - **`get_service_summary`** — Throughput, error rate, p95 response time across all services
235
+ - **`get_service_environments`** — Available environments for your services. Run this first — other APM tools need `env` from here
236
+ - **`get_service_performance_details`** — Full breakdown: throughput, error rate, p50/p90/p95/avg/max, apdex, availability
237
+ - **`get_service_operations_summary`** — Operations grouped by HTTP endpoints, DB calls, messaging, HTTP clients
238
+ - **`get_service_dependency_graph`** — Dependency map with throughput, latency, and error rates for upstream/downstream/infra
239
+ - **`get_exceptions`** — Server-side exceptions with service and span filters
633
240
 
634
- ### If installed via NPM:
241
+ ### Database Observability
635
242
 
636
- ```json
637
- {
638
- "mcpServers": {
639
- "last9": {
640
- "command": "npx",
641
- "args": ["-y", "@last9/mcp-server@latest"],
642
- "env": {
643
- "LAST9_REFRESH_TOKEN": "<last9_refresh_token>"
644
- }
645
- }
646
- }
647
- }
648
- ```
243
+ Four tools that go directly at your database performance, derived from OpenTelemetry trace spans. No extra instrumentation needed if you're already using OTel.
649
244
 
650
- ## Usage with VS Code
245
+ - **`get_databases`** — Discover all databases across your infrastructure: DB type, host, throughput (queries/min), p95 latency, error rate, number of dependent services
246
+ - **`get_database_slow_queries`** — The actual slowest query executions, ordered by duration, with trace IDs for drilling into full traces
247
+ - **`get_database_queries`** — Query patterns and aggregates: how often a query runs, average/p95 duration, error rate
248
+ - **`get_database_server_metrics`** — Server-side metrics from the DB host itself (CPU, connections, buffer hit rates — depends on your DB system)
651
249
 
652
- > Note: MCP support in VS Code is available starting v1.99 and is currently in
653
- > preview. For advanced configuration options and alternative setup methods,
654
- > [view the VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers).
250
+ Supports PostgreSQL, MySQL, MongoDB, Redis, Aerospike, and anything else OTel traces with a `db_system` attribute.
655
251
 
656
- 1. Open VS Code, go to Settings, select the User tab, then Features, then Chat
657
- 2. Click "Edit settings.json"
658
- 3. Copy and paste the server config to your existing file, then save
659
- 4. Restart VS Code
252
+ ### Prometheus / PromQL
660
253
 
661
- ### Hosted MCP over HTTP (recommended)
254
+ - **`prometheus_range_query`** — PromQL range queries over any metric
255
+ - **`prometheus_instant_query`** — Instant queries; use rollup functions like `avg_over_time`, `sum_over_time`
256
+ - **`prometheus_label_values`** — Label values for a given series
257
+ - **`prometheus_labels`** — All labels available for a series
662
258
 
663
- ```json
664
- {
665
- "mcp": {
666
- "servers": {
667
- "last9": {
668
- "type": "http",
669
- "url": "https://app.last9.io/api/v4/organizations/<org_slug>/mcp",
670
- "headers": {
671
- "X-LAST9-API-TOKEN": "Bearer <mcp_client_token>"
672
- }
673
- }
674
- }
675
- }
676
- }
677
- ```
259
+ Point these at a different datasource/cluster than the default by setting `LAST9_DATASOURCE`.
678
260
 
679
- ### Local STDIO (alternative)
261
+ ### Logs
680
262
 
681
- ### If installed via Homebrew:
263
+ - **`get_logs`** — Full JSON pipeline log queries (aggregations, filters, field extraction)
264
+ - **`get_service_logs`** — Raw log lines for a service, filterable by severity and body content
265
+ - **`get_log_attributes`** — Available attributes in the log schema for a time window
266
+ - **`get_drop_rules`** — Log drop rules from [Last9 Control Plane](https://last9.io/control-plane)
267
+ - **`add_drop_rule`** — Create a new drop rule to cut log volume at the source
682
268
 
683
- ```json
684
- {
685
- "mcp": {
686
- "servers": {
687
- "last9": {
688
- "type": "stdio",
689
- "command": "/opt/homebrew/bin/last9-mcp",
690
- "env": {
691
- "LAST9_REFRESH_TOKEN": "<last9_refresh_token>"
692
- }
693
- }
694
- }
695
- }
696
- }
697
- ```
269
+ ### Traces
698
270
 
699
- ### If installed via NPM:
271
+ - **`get_traces`** — JSON pipeline trace queries for broad searches and aggregations
272
+ - **`get_service_traces`** — Traces by exact trace ID or service name. Use this when you have a trace ID — it's faster
273
+ - **`get_trace_attributes`** — Available attributes in the trace schema
700
274
 
701
- ```json
702
- {
703
- "mcp": {
704
- "servers": {
705
- "last9": {
706
- "type": "stdio",
707
- "command": "npx",
708
- "args": ["-y", "@last9/mcp-server@latest"],
709
- "env": {
710
- "LAST9_REFRESH_TOKEN": "<last9_refresh_token>"
711
- }
712
- }
713
- }
714
- }
715
- }
716
- ```
275
+ ### Change Events & Alerts
717
276
 
718
- ## Windows Example (Claude Desktop)
277
+ - **`get_change_events`** — Deployments, config changes, rollbacks. Correlate incidents with what changed
278
+ - **`get_alert_config`** — Alert rule configurations — searchable by name, severity, type, tags
279
+ - **`get_alerts`** — Currently firing alerts within a time window
280
+ - **`get_notification_channels`** — Configured notification channels (Slack, PagerDuty, email, etc.)
719
281
 
720
- After downloading `last9-mcp-server_Windows_x86_64.zip` from [GitHub Releases](https://github.com/last9/last9-mcp-server/releases/latest), extract to get `last9-mcp-server.exe` and use its full path:
282
+ ### Fuzzy Name Resolution
721
283
 
722
- ```json
723
- {
724
- "mcpServers": {
725
- "last9": {
726
- "command": "C:\\Users\\<user>\\AppData\\Local\\Programs\\last9-mcp-server.exe",
727
- "env": {
728
- "LAST9_REFRESH_TOKEN": "<last9_refresh_token>"
729
- }
730
- }
731
- }
732
- }
733
- ```
284
+ - **`did_you_mean`** — When the agent isn't sure about an entity name, this returns the closest matches from your catalog (services, environments, hosts, databases, K8s deployments/namespaces, jobs). Up to 3 suggestions with similarity scores. The server calls this automatically before most tools when a name lookup returns empty.
734
285
 
735
- The same pattern applies for Cursor and Windsurf on Windows. For VS Code, use the `"mcp": { "servers": { ... } }` wrapper. On Windows, prefer [NPM](#npm) to avoid path management, or use the [hosted HTTP transport](#recommended-managed-mcp-over-http) to skip local installation entirely.
286
+ ---
736
287
 
737
- ## Development
288
+ ## How It Works
738
289
 
739
- For local development and testing, you can run the MCP server in HTTP mode which makes it easier to debug requests and responses.
290
+ **Deep links on every response.** Every tool returns a `deep_link` field — a direct URL into the Last9 dashboard for that exact query and time range. The agent can hand you the link; you click it; you're there.
740
291
 
741
- ### Running in HTTP Mode
292
+ **Live attribute caching.** At startup, the server fetches the actual log and trace attribute names from your data and embeds them into tool descriptions. This means the AI assistant knows what fields exist in your schema, not just a generic list. The cache refreshes every 2 hours.
742
293
 
743
- Set the `LAST9_HTTP` environment variable to enable HTTP server mode:
294
+ **Chunked large results.** `get_logs` and `get_traces` handle large result sets through chunking rather than truncating. The default limit is 5000 entries for logs; configurable via `LAST9_MAX_GET_LOGS_ENTRIES`.
295
+
296
+ ---
297
+
298
+ ## Development
299
+
300
+ <details>
301
+ <summary>HTTP mode, curl testing, building from source</summary>
302
+
303
+ ### Run in HTTP Mode
744
304
 
745
305
  ```bash
746
- # Export required environment variables
747
306
  export LAST9_REFRESH_TOKEN="your_refresh_token"
748
307
  export LAST9_HTTP=true
749
- export LAST9_PORT=8080 # Optional, defaults to 8080
750
- # Run the server
308
+ export LAST9_PORT=8080
751
309
  ./last9-mcp-server
752
310
  ```
753
311
 
754
- The server will start on `http://localhost:8080/mcp` and you can test it with curl:
312
+ Server starts at `http://localhost:8080/mcp`.
755
313
 
756
- ### Testing with curl
314
+ ### Test with curl
757
315
 
758
- The MCP Streamable HTTP protocol requires an initialize handshake first. The server creates and returns a session ID in the response — do **not** set `Mcp-Session-Id` on the first request.
316
+ MCP Streamable HTTP requires an initialize handshake first. Don't set `Mcp-Session-Id` on the first request.
759
317
 
760
318
  ```bash
761
- # Step 1: Initialize — omit Mcp-Session-Id so the server creates the session.
762
- # Extract the returned Mcp-Session-Id from the response headers.
319
+ # Step 1: Initialize
763
320
  SESSION_ID=$(curl -si -X POST http://localhost:8080/mcp \
764
321
  -H "Content-Type: application/json" \
765
322
  -d '{
@@ -774,13 +331,13 @@ SESSION_ID=$(curl -si -X POST http://localhost:8080/mcp \
774
331
  }' | grep -i "^Mcp-Session-Id:" | awk '{print $2}' | tr -d '\r')
775
332
  echo "Session: $SESSION_ID"
776
333
 
777
- # Step 2: Send the initialized notification
334
+ # Step 2: Send initialized notification
778
335
  curl -s -X POST http://localhost:8080/mcp \
779
336
  -H "Content-Type: application/json" \
780
337
  -H "Mcp-Session-Id: $SESSION_ID" \
781
338
  -d '{"jsonrpc": "2.0", "method": "notifications/initialized", "params": {}}'
782
339
 
783
- # Step 3: List available tools
340
+ # Step 3: List tools
784
341
  curl -s -X POST http://localhost:8080/mcp \
785
342
  -H "Content-Type: application/json" \
786
343
  -H "Mcp-Session-Id: $SESSION_ID" \
@@ -797,7 +354,7 @@ curl -s -X POST http://localhost:8080/mcp \
797
354
  "params": {
798
355
  "name": "get_service_logs",
799
356
  "arguments": {
800
- "service_name": "your-service-name",
357
+ "service": "your-service-name",
801
358
  "lookback_minutes": 30,
802
359
  "limit": 10
803
360
  }
@@ -805,24 +362,236 @@ curl -s -X POST http://localhost:8080/mcp \
805
362
  }'
806
363
  ```
807
364
 
808
- ### Building from Source
365
+ ### Build from Source
809
366
 
810
367
  ```bash
811
- # Clone the repository
812
368
  git clone https://github.com/last9/last9-mcp-server.git
813
369
  cd last9-mcp-server
814
- # Build the binary
815
370
  go build -o last9-mcp-server
816
- # Run in development mode
817
371
  LAST9_HTTP=true ./last9-mcp-server
818
372
  ```
819
373
 
820
- **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).
374
+ `LAST9_HTTP=true` is for local development. For actual usage, the [hosted HTTP endpoint](#start-in-30-seconds-hosted) is easier.
375
+
376
+ </details>
377
+
378
+ ---
379
+
380
+ ## Tool Reference
381
+
382
+ <details>
383
+ <summary>All parameters, time input standards, and details</summary>
384
+
385
+ ### Time Input
386
+
387
+ - Absolute times (`start_time_iso`/`end_time_iso`, or `time_iso`) take precedence over `lookback_minutes`.
388
+ - For relative windows: use `lookback_minutes`.
389
+ - For absolute windows: use RFC3339/ISO8601 — `2026-02-09T15:04:05Z`.
390
+ - Legacy `YYYY-MM-DD HH:MM:SS` is accepted for compatibility only.
391
+
392
+ ### get_exceptions
393
+
394
+ - `limit` (integer, optional): Max exceptions. Default: 20.
395
+ - `lookback_minutes` (integer, optional): Default: 60.
396
+ - `start_time_iso` / `end_time_iso` (string, optional): Absolute time range.
397
+ - `service_name` (string, optional): Filter by service.
398
+ - `span_name` (string, optional): Filter by span name.
399
+ - `deployment_environment` (string, optional): Filter by environment.
400
+
401
+ ### get_service_summary
402
+
403
+ - `start_time_iso` / `end_time_iso` (string, optional)
404
+ - `env` (string, optional): Defaults to `prod`.
405
+
406
+ ### get_service_environments
407
+
408
+ - `start_time_iso` / `end_time_iso` (string, optional)
409
+
410
+ > All other APM tools require an `env` value. Use `""` if this returns empty.
411
+
412
+ ### get_service_performance_details
413
+
414
+ - `service_name` (string, required)
415
+ - `lookback_minutes` (integer, optional): Default: 60.
416
+ - `start_time_iso` / `end_time_iso` (string, optional)
417
+ - `env` (string, optional): Defaults to `prod`.
418
+
419
+ ### get_service_operations_summary
420
+
421
+ - `service_name` (string, required)
422
+ - `lookback_minutes` (integer, optional): Default: 60.
423
+ - `start_time_iso` / `end_time_iso` (string, optional)
424
+ - `env` (string, optional): Defaults to `prod`.
425
+
426
+ ### get_service_dependency_graph
427
+
428
+ - `service_name` (string, optional)
429
+ - `lookback_minutes` (integer, optional): Default: 60.
430
+ - `start_time_iso` / `end_time_iso` (string, optional)
431
+ - `env` (string, optional): Defaults to `prod`.
432
+
433
+ ### get_databases
434
+
435
+ - `env` (string, optional): Filter by environment. Default: all.
436
+ - `lookback_minutes` (integer, optional): Default: 60.
437
+ - `start_time_iso` / `end_time_iso` (string, optional)
438
+
439
+ ### get_database_slow_queries
440
+
441
+ - `db_system` (string, optional): e.g. `postgresql`, `mysql`, `mongodb`, `redis`.
442
+ - `host` (string, optional): Database host (`net_peer_name`).
443
+ - `service_name` (string, optional): Calling service name.
444
+ - `env` (string, optional)
445
+ - `min_duration_ms` (float, optional): Minimum query duration in ms.
446
+ - `lookback_minutes` (integer, optional): Default: 60.
447
+ - `start_time_iso` / `end_time_iso` (string, optional)
448
+ - `limit` (integer, optional): Default: 20.
449
+
450
+ ### get_database_queries
451
+
452
+ - `db_system` (string, optional)
453
+ - `host` (string, optional)
454
+ - `service_name` (string, optional)
455
+ - `env` (string, optional)
456
+ - `lookback_minutes` (integer, optional): Default: 60.
457
+ - `start_time_iso` / `end_time_iso` (string, optional)
458
+ - `limit` (integer, optional): Default: 20.
459
+
460
+ ### get_database_server_metrics
461
+
462
+ - `db_system` (string, required): e.g. `postgresql`, `mysql`, `mongodb`, `redis`, `aerospike`.
463
+ - `host` (string, optional)
464
+ - `lookback_minutes` (integer, optional): Default: 60.
465
+ - `start_time_iso` / `end_time_iso` (string, optional)
466
+
467
+ ### prometheus_range_query
468
+
469
+ - `query` (string, required): The PromQL query.
470
+ - `start_time_iso` / `end_time_iso` (string, optional): Defaults to last 60 min.
471
+ - `lookback_minutes` (float, optional): Default: 60.
472
+
473
+ ### prometheus_instant_query
474
+
475
+ - `query` (string, required)
476
+ - `time_iso` (string, optional): Defaults to now.
477
+ - `lookback_minutes` (float, optional)
478
+
479
+ ### prometheus_label_values
480
+
481
+ - `match_query` (string, optional): PromQL filter.
482
+ - `label` (string, required): Label name.
483
+ - `start_time_iso` / `end_time_iso` (string, optional)
484
+
485
+ ### prometheus_labels
486
+
487
+ - `match_query` (string, optional): PromQL filter.
488
+ - `start_time_iso` / `end_time_iso` (string, optional)
489
+
490
+ ### get_logs
491
+
492
+ - `logjson_query` (array, required): JSON pipeline query.
493
+ - `lookback_minutes` (integer, optional): Default: 5.
494
+ - `start_time_iso` / `end_time_iso` (string, optional)
495
+ - `limit` (integer, optional): Server default: 5000.
496
+ - `index` (string, optional): `physical_index:<name>` or `rehydration_index:<block_name>`.
497
+
498
+ ### get_service_logs
499
+
500
+ - `service` (string, required)
501
+ - `lookback_minutes` (integer, optional): Default: 60.
502
+ - `limit` (integer, optional): Default: 20.
503
+ - `env` (string, optional)
504
+ - `severity_filters` (array, optional): e.g. `["error", "warn"]`. OR logic.
505
+ - `body_filters` (array, optional): e.g. `["timeout", "failed"]`. OR logic.
506
+ - `start_time_iso` / `end_time_iso` (string, optional)
507
+ - `index` (string, optional)
508
+
509
+ Multiple filter types combine with AND. Each array uses OR internally.
510
+
511
+ ### get_log_attributes
512
+
513
+ - `lookback_minutes` (integer, optional): Default: 15.
514
+ - `start_time_iso` / `end_time_iso` (string, optional)
515
+ - `region` (string, optional)
516
+ - `index` (string, optional)
517
+
518
+ ### get_drop_rules
519
+
520
+ No parameters.
521
+
522
+ ### add_drop_rule
523
+
524
+ - `name` (string, required)
525
+ - `filters` (array, required): Each filter: `key`, `value`, `operator` (`equals`/`not_equals`), `conjunction` (`and`).
526
+
527
+ ### get_traces
528
+
529
+ Use for broad searches and aggregations. For exact trace ID lookup, use `get_service_traces`.
530
+
531
+ - `tracejson_query` (array, required)
532
+ - `start_time_iso` / `end_time_iso` (string, optional)
533
+ - `lookback_minutes` (integer, optional): Default: 60.
534
+ - `limit` (integer, optional): Default: 5000.
535
+
536
+ ### get_service_traces
537
+
538
+ Exactly one of `trace_id` or `service_name` is required.
539
+
540
+ - `trace_id` (string, optional): Default lookback: 72 hours.
541
+ - `service_name` (string, optional): Default lookback: 60 min.
542
+ - `lookback_minutes` (integer, optional)
543
+ - `start_time_iso` / `end_time_iso` (string, optional)
544
+ - `limit` (integer, optional): Default: 10.
545
+ - `env` (string, optional)
546
+
547
+ ### get_trace_attributes
548
+
549
+ - `lookback_minutes` (integer, optional): Default: 15.
550
+ - `start_time_iso` / `end_time_iso` (string, optional)
551
+ - `region` (string, optional)
552
+
553
+ ### get_change_events
554
+
555
+ - `start_time_iso` / `end_time_iso` (string, optional)
556
+ - `lookback_minutes` (integer, optional): Default: 60.
557
+ - `service` (string, optional)
558
+ - `environment` (string, optional)
559
+ - `event_name` (string, optional): Call without this first to get `available_event_names`.
560
+
561
+ ### get_alert_config
562
+
563
+ - `search_term` (string, optional): Free-text search across name, group, data source, tags.
564
+ - `rule_name` (string, optional)
565
+ - `severity` (string, optional)
566
+ - `rule_type` (string, optional): `static` or `anomaly`.
567
+ - `alert_group_name` / `alert_group_type` / `data_source_name` (string, optional)
568
+ - `tags` (array, optional): All must match (AND logic).
569
+
570
+ ### get_alerts
571
+
572
+ - `time_iso` (string, optional): Evaluation time in RFC3339.
573
+ - `window` (integer, optional): Lookback in seconds. Default: 900. Range: 60–86400.
574
+ - `lookback_minutes` (integer, optional): Range: 1–1440.
575
+
576
+ ### get_notification_channels
577
+
578
+ No parameters. Returns all configured notification channels (Slack, PagerDuty, email, webhooks, etc.).
579
+
580
+ ### did_you_mean
581
+
582
+ - `query` (string, required): The name to search for — partial, misspelled, or abbreviated.
583
+ - `type` (string, optional): Restrict to entity type: `service`, `environment`, `host`, `database`, `k8s_deployment`, `k8s_namespace`, `job`.
584
+
585
+ Returns up to 3 closest matches with similarity scores. Use this before any tool call where the entity name is uncertain. If a previous call returned empty results, try this before retrying.
586
+
587
+ </details>
588
+
589
+ ---
821
590
 
822
591
  ## Testing
823
592
 
824
- See [TESTING.md](TESTING.md) for detailed testing instructions.
593
+ See [TESTING.md](TESTING.md) for integration test setup and instructions.
825
594
 
826
- ## Badges
595
+ ---
827
596
 
828
597
  [![MseeP.ai Security Assessment Badge](https://mseep.net/pr/last9-last9-mcp-server-badge.png)](https://mseep.ai/app/last9-last9-mcp-server)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@last9/mcp-server",
3
- "version": "0.5.1",
3
+ "version": "0.6.0",
4
4
  "description": "Last9 MCP Server - Model Context Protocol server implementation for Last9",
5
5
  "bin": {
6
6
  "last9-mcp": "./bin/cli.js"