MCP tools

The StackNext MCP server is read-only. Every tool is annotated readOnlyHint: true, destructiveHint: false, idempotentHint: true and openWorldHint: false. See MCP server for setup.

Tools

Tool	Arguments	Returns
`get_project_summary`	none	Project name, connection state, counts, latency summary, recent errors and instrumentation coverage. Start here
`list_requests`	`limit`, `offset`, `q`, `method`, `status`, `slow`, `minDurationMs`, `sort`	Request summaries with route, status, duration, span/error/query counts and trace id
`get_request`	`traceId`	Compatibility alias for `get_trace`: request summary, full span timeline, errors and database queries
`list_traces`	`limit`, `offset`, `q`, `sort`	Trace summaries with root span, duration and counts
`get_trace`	`traceId`	Full span tree plus correlated errors, database queries and diagnostic references
`list_errors`	`limit`, `offset`, `q`, `route`, `name`, `includeStack`	Errors, fingerprint groups and trace correlation. Stacks are omitted unless `includeStack` is true
`get_error`	`errorId`	One error with redacted stack and its correlated trace
`list_database_queries`	`limit`, `offset`, `q`, `minDurationMs`, `traceId`, `databaseSystem`	Redacted SQL, duration (nullable), success state and route
`find_slow_requests`	`minDurationMs`, `limit`	Slowest requests above the threshold, default 500 ms
`stacknext_list_diagnostics`	`limit`, `offset`, `category`, `severity`, `status`, `ruleId`, `route`, `traceId`, `since`, `until`, `q`	Deterministic findings with counts, sample window, notes and limitations
`stacknext_get_diagnostic`	`diagnosticId`	One finding with bounded evidence, verification steps, limitations and a related trace
`stacknext_list_test_runs`	`limit`, `offset`	Live and saved capture runs with status, sample/correlation counts, command timing and environment
`stacknext_get_test_run`	`runId`	One run with scenarios, samples, verified trace/query/error evidence, findings, warnings and limitations
`stacknext_list_baselines`	`limit`, `offset`	Immutable baselines with source run, scenario/sample counts and environment
`stacknext_get_baseline`	`baselineId`	One baseline with its source run, environment and captured scenarios
`stacknext_list_comparisons`	`limit`, `offset`	Deterministic comparison summaries with status, severity, counts and environment compatibility
`stacknext_get_comparison`	`comparisonId`	One comparison with per-scenario reasons, metrics, environment differences and limitations
`stacknext_list_snapshots`	`limit`, `offset`	Frozen snapshots with source, capture time, sample window, counts, file size and invalid-record count
`stacknext_get_snapshot`	`snapshotId`	One snapshot with captured config, limitations and its first traces, errors and database queries
`stacknext_get_snapshot_trace`	`snapshotId`, `traceId`	One trace from a snapshot’s detached view, without live diagnostics

Argument constraints

limit is between 1 and 200 (default 50).
minDurationMs is between 0 and 600,000.
status accepts 2xx, 3xx, 4xx, 5xx or none.
sort accepts recent, oldest or slowest.
Diagnostic category accepts database, http, performance, errors or runtime.
Diagnostic severity accepts info, warning or error.
Diagnostic status accepts observed, possible or insufficient-evidence.
ruleId accepts n-plus-one-queries, slow-request, slow-span, repeated-external-http, error-fingerprint or server-error-response.
since and until are epoch milliseconds.

Regression ids are strict: run-<16 hex>, base-<16 hex> and cmp-<16 hex>. Snapshot ids are strict: snap-<16 hex>. An id that does not match the format is rejected before storage is read. Comparison status is improved, regressed, unchanged or inconclusive; severity is high, medium, low or none.

Response metadata

Every successful response adds a top-level meta object:

{
  "meta": {
    "tool": "list_requests",
    "generatedAt": "2026-11-02T12:00:00.000Z",
    "project": "stacknext-example",
    "timeRange": {
      "firstEventTime": "2026-11-02T11:55:00.000Z",
      "lastEventTime": "2026-11-02T11:59:59.000Z"
    },
    "result": {
      "found": 120,
      "returned": 50,
      "limit": 50,
      "offset": 0,
      "hasMore": true,
      "nextOffset": 50
    },
    "connection": {
      "instrumentation": "connected",
      "instances": 1,
      "lastSeen": "2026-11-02T11:59:59.000Z",
      "sdkVersion": "<installed-version>",
      "collectorVersion": "<installed-version>"
    },
    "completeness": { "complete": true, "reasons": [] },
    "notes": []
  }
}

result.found is the total in the retention window; returned is this page.
connection.instrumentation is connected, waiting or unknown.
completeness.complete is false for pagination, dropped data, an unconnected app, an empty result or missing parent spans. Read completeness.reasons.
Detail responses add meta.identifiers (traceId, errorId, diagnosticId, runId, baselineId, comparisonId, snapshotId and/or candidateId).
notes carries short caveats such as omitted stacks, unmeasured query durations, findings that are not confirmed root causes, incomplete regression records, or snapshot data that is not live telemetry.

Successful calls also return structuredContent and advertise an outputSchema when the client supports structured tool output. Tool text content remains pretty-printed JSON for compatibility. The server publishes MCP instructions during initialization. Codex reads these directly; other clients may show or ignore them.

Coverage in the summary

get_project_summary returns the same coverage report as GET /api/coverage and stacknext coverage --json, plus a compact summary in meta.coverage:

{
  "coverage": {
    "observed": 5,
    "active": 1,
    "configured": 0,
    "notObserved": 4,
    "unsupported": 3,
    "unknown": 1,
    "requestsInSample": 12
  }
}

coverage.sample gives the retention window and connection state. Each coverage.items[] entry carries a status, evidence count/types, last-seen time and limitations. There is deliberately no percentage or composite score. See instrumentation coverage.

Diagnostics

stacknext_list_diagnostics and stacknext_get_diagnostic expose the same deterministic findings as stacknext diagnose, the dashboard and GET /api/diagnostics. The server does not run a second engine and does not call an AI service. A list response includes total, counts, sample, notes, limitations, engineVersion and ruleSetVersion. Findings are computed over the current in-memory retention window, not all history. total is the number of matching findings; items is the current page. The default finding cap is 100. stacknext_get_diagnostic returns { finding, trace, meta }. The finding contains the rule, category, severity, status, route, time window, affected trace count, fingerprint, bounded evidence, verification steps and limitations. The related trace is bounded; use get_trace for the complete span tree when it is truncated. get_trace adds a diagnostics array of references (id, ruleId, category, severity, status, title) without changing the trace shape. Call stacknext_get_diagnostic for evidence. Findings are evidence, not confirmed root causes, and ids can disappear when telemetry ages out.

Regression and snapshot semantics

Regression tools expose the same records as stacknext runs, stacknext baseline and stacknext compare. They cannot capture, save, compare, remove or edit a record.

A sample is verified only when the collector found the injected trace and a server span parented to the injected span id. Incomplete reasons include trace-not-found, injected-parent-not-found and no-request-trace-recorded.
Run status is running, completed, failed, interrupted or incomplete.
Comparison detail includes environment.compatible, differences, per-scenario status/severity/reasons/metrics, warnings and limitations.
Snapshot tools read frozen copies and never replay them. A snapshot carries no live diagnostics or coverage.

See regression testing and snapshots.

Prompts

The server offers five optional prompts. They shape an investigation but do not add capabilities or execute tools on their own.

Prompt	Arguments	Use
`diagnose-error`	`errorId?`, `route?`	Find an error, inspect its stack and follow the correlated trace
`investigate-slow-request`	`minDurationMs?`, `route?`	Rank slow requests and break down the slowest trace
`inspect-database-activity`	`traceId?`, `minDurationMs?`	Inspect SQL, failures, null durations and trace correlation
`investigate-trace`	`traceId`	Inspect one timeline, its errors and queries
`diagnose-runtime-issue`	`diagnosticId?`, `traceId?`, `route?`	Start from a finding or trace, verify the evidence and report what remains unproven

Overview

Getting started

Guides

Integrations

AI agents

Reference

Troubleshooting

Security and privacy

Tools

Argument constraints

Response metadata

Coverage in the summary

Diagnostics

Regression and snapshot semantics

Prompts

​Tools

​Argument constraints

​Response metadata

​Coverage in the summary

​Diagnostics

​Regression and snapshot semantics

​Prompts

​Related

Tools

Argument constraints

Response metadata

Coverage in the summary

Diagnostics

Regression and snapshot semantics

Prompts

Related