opentel-mcp 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,94 @@
 # Changelog
 
+## 0.16.0
+
+Finishes what 0.15 started. Telemetry now survives the way MCP clients
+actually stop servers (`flushOnExit`), and two new signals land: errors
+your agent can't act on, and opt-in resources/prompts coverage. Plus a fix
+for SDK v2 servers that declare `capabilities.tools`.
+`setupNodeSdk: false` (production) behavior is unchanged apart from the
+new span attributes on `isError: true` results and the v2 fix; resources/
+prompts coverage is off unless you opt in. No new metric label keys.
+
+### Added
+
+- **`flushOnExit` (ADR 024, `docs/adr/024-flush-on-exit.md`).** Under
+  `setupNodeSdk: true`, buffered spans and dev-mode metrics are now
+  flushed automatically when the process stops: on `beforeExit` (stdin
+  closed, loop drained), `SIGTERM` and `SIGINT`. MCP clients built on the
+  SDK's stdio transport stop servers with exactly that sequence (stdin
+  close → SIGTERM → SIGKILL, 2 s apart); the old `process.on('beforeExit')`
+  snippet only covered the first step. On by default with
+  `setupNodeSdk: true`; `flushOnExit: false` opts out;
+  `flushOnExit: { timeoutMs }` lowers the 1000 ms cap.
+  - One listener set per process, however many servers are instrumented,
+    and it's removed again once every server has shut down.
+  - After flushing, a signal is re-raised when no other listener for it
+    exists, so the process still dies by that signal. If your code has its
+    own listener, yours decides. `beforeExit` never changes the exit code.
+  - **No effect at all with `setupNodeSdk: false`** (production
+    behavior unchanged): passing it there logs a one-time `diag.warn`.
+  - Not covered: `process.exit()` (call `await server.shutdown()` first)
+    and `SIGKILL`.
+
+- **Unactionable tool errors (ADR 025, `docs/adr/025-unactionable-errors.md`).**
+  Every `isError: true` span now carries `mcp.failure.unactionable`
+  (boolean) and `mcp.failure.content_length_bucket` (`empty` | `tiny` |
+  `short` | `medium` | `long`). Unactionable means no content, or under
+  10 characters of trimmed text with no image/audio/resource item: an
+  error that gives the agent nothing to act on. Computed only from text
+  lengths and non-text item counts, never from the text; a canary-string
+  test checks every exported span and metric. Span-only (no metric label,
+  `METRIC_SAFE_ATTRIBUTES` unchanged); fingerprints and categories
+  unchanged. Configure with `unactionableErrors: { enabled, minTextLength }`
+  or `OTEL_MCP_UNACTIONABLE_ERRORS_ENABLED` /
+  `OTEL_MCP_UNACTIONABLE_ERRORS_MIN_TEXT_LENGTH`.
+
+- **Resources and prompts coverage, opt-in (ADR 026,
+  `docs/adr/026-resources-prompts-coverage.md`).**
+  `coverage: { resources: true, prompts: true }` also traces
+  `resources/read`, `resources/list`, `resources/templates/list`,
+  `prompts/get` and `prompts/list`, on SDK v1 and v2, low-level `Server`
+  and `McpServer`. Both are off by default; nothing changes unless you opt in.
+  - Spans are named by method (`prompts/get <name>` for prompts/get) and
+    carry `mcp.method.name` (+ `gen_ai.prompt.name` on prompts/get, capped
+    at 128 characters). `gen_ai.tool.name` is absent.
+  - Never captured: resource URIs, prompt arguments, result content, or
+    the exception message of a failing request (SDK resource errors embed
+    the URI). Failures get status `ERROR`, `error.type` and the usual
+    fingerprint/category/channel.
+  - New histogram `mcp.server.operation.duration`, labeled by
+    `mcp.method.name` + `error.type` only. No new label keys;
+    `mcp.method.name` stays a fixed set of constants (now 7 values).
+  - A handler already registered when `instrumentMcpServer()` runs is
+    skipped with one `diag.warn`, never a throw. That includes SDK v2
+    `McpServer` declaring `capabilities.resources/prompts` in its
+    constructor.
+
+### Changed
+
+- `server.shutdown()` (under `setupNodeSdk: true`) is now idempotent:
+  every call returns the same promise, so an explicit `shutdown()` and
+  `flushOnExit` never shut the providers down twice.
+- The README quickstart and both examples no longer need the
+  `process.on('beforeExit', ...)` block; it's been removed.
+
+### Fixed
+
+- **SDK v2: a `McpServer` constructed with `capabilities: { tools: {} }`
+  can now be instrumented.** v2's `McpServer` installs its own
+  `tools/list`/`tools/call` dispatchers in its constructor when that
+  capability is declared, so `instrumentMcpServer()` threw
+  `INSTRUMENT_FIRST_ERROR` on every such server, whatever the call order.
+  It now recognizes McpServer's own constructor-installed handlers (v2
+  McpServer, installer ran, no tool registered yet, not yet connected),
+  takes them down with the public `removeRequestHandler()`, and lets
+  McpServer re-install them through the instrumented `setRequestHandler`,
+  so they're wrapped like any lazily-installed handler. Genuine misorders
+  still throw: a tool registered before instrumenting (v1 or v2, with or
+  without declared capabilities) or a low-level `Server` handler
+  registered first. Present since v2 support shipped (SDK 2.0.0).
+
 ## 0.15.0
 
 "Make it visible" — no instrumentation changes, no `tools/call` hot-path

package/README.md

@@ -79,7 +79,7 @@ const server = new McpServer({ name: 'my-server', version: '1.0.0' });
 
 // Wraps every tool registered below. Must run BEFORE server.tool() —
 // see "Ordering constraint" below for why.
-const instrumented = instrumentMcpServer(server, {
+instrumentMcpServer(server, {
   serviceName: 'my-mcp-server', // shows up on your traces
   setupNodeSdk: true, // dev mode: prints traces to your terminal
 });
@@ -91,26 +91,25 @@ server.tool('echo', { text: z.string() }, async ({ text }) => ({
 
 const transport = new StdioServerTransport();
 await server.connect(transport);
-
-// Only needed to see metrics (below) immediately when piping ONE request
-// in and exiting right after, like the "See it working" example does —
-// a real, long-running server sees the same lines on their own, every 5
-// seconds, with no extra code.
-let flushed = false;
-process.on('beforeExit', () => {
-  if (flushed) return;
-  flushed = true;
-  instrumented.shutdown();
-});
 ```
 
 That's it. Every tool call now emits a trace. Wire an exporter to see them
-(next section).
+(next section). When the server stops — your MCP client closing stdin, or
+sending SIGTERM/SIGINT — anything still buffered is flushed first,
+automatically (see "Flushing on exit" below).
 
 ## See it working
 
-Run the snippet above and this prints to your terminal — a real, captured
-run (full dump: `examples/hello-mcpserver/README.md`):
+Save the snippet as `server.js`. On its own it just waits: an MCP server
+reads requests from stdin and does nothing until a client sends one. To
+try it without a client, pipe in a single tool call:
+
+```bash
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"echo","arguments":{"text":"hi"}}}' | node server.js
+```
+
+The JSON-RPC response goes to stdout, and this prints to stderr — a real,
+captured run (full dump: `examples/hello-mcpserver/README.md`):
 
 ```
 name: 'tools/call echo'
@@ -127,10 +126,12 @@ attributes: {
 No dashboard needed — `setupNodeSdk: true`'s dev exporter printed this
 directly. Point it at a real backend later; see "Two modes" below.
 
-**Metrics print too (v0.15.0+)** — within 5 seconds (not the default
-60-second export interval), a compact one-line-per-metric summary follows
+**Metrics print too (v0.15.0+)** — a compact one-line-per-metric summary
 on stderr, reusing the exact `mcp.tool.*` instruments documented in
-"Metrics" below:
+"Metrics" below. A long-running server prints it every 5 seconds (not the
+default 60-second export interval). The one-shot piped run above prints it
+once as it exits, because the server flushes when stdin closes (v0.16.0,
+see "Flushing on exit"):
 
 ```
 [opentel-mcp metrics] mcp.tool.calls{gen_ai.tool.name=echo,mcp.method.name=tools/call} = 1
@@ -315,6 +316,60 @@ error.type = tool_error
 
 Verified in `test/instrument.test.js`'s "tool-level failure" tests.
 
+#### Errors your agent can't act on (v0.16.0)
+
+An `isError: true` result with no content, or just `"Error"`, tells the
+model nothing about what went wrong or what to do next — a common cause
+of retries and thrash. Every `isError: true` span also carries:
+
+| Attribute | Values |
+| --- | --- |
+| `mcp.failure.unactionable` | `true` when there's no content, or fewer than 10 characters of text (whitespace-trimmed) and no image/audio/resource item |
+| `mcp.failure.content_length_bucket` | `empty` (0) · `tiny` (1–9) · `short` (< 80) · `medium` (< 500) · `long` |
+
+Both are computed **only from lengths and item counts — never from the
+text itself** (proved by a canary-string test in
+`test/unactionable.test.js`), on spans only, never as metric labels. They
+don't change fingerprints or categories. Configure with
+`unactionableErrors: { enabled, minTextLength }` (defaults `true`, `10`).
+Design: [ADR 025](../../docs/adr/025-unactionable-errors.md).
+
+### Resources and prompts (opt-in, v0.16.0)
+
+Tools are traced by default. `resources/*` and `prompts/*` requests can be
+traced too, if you turn them on:
+
+```js
+instrumentMcpServer(server, {
+  coverage: { resources: true, prompts: true }, // either or both
+});
+```
+
+| Method | Span name | Attributes |
+| --- | --- | --- |
+| `resources/read`, `resources/list`, `resources/templates/list` | the method, e.g. `resources/read` | `mcp.method.name` |
+| `prompts/get` | `prompts/get <prompt name>` | `mcp.method.name`, `gen_ai.prompt.name` |
+| `prompts/list` | `prompts/list` | `mcp.method.name` |
+
+- **Never captured:** resource URIs, prompt arguments, result content. A
+  failing request gets status `ERROR`, `error.type`, and the usual
+  fingerprint/category/channel (`mcp.failure.*`), but **not** the exception
+  message, because SDK resource errors embed the URI in it.
+- `gen_ai.tool.name` is absent (not empty) on these spans, so they never
+  show up in per-tool views or tool metrics.
+- Durations go to a separate histogram, `mcp.server.operation.duration`,
+  labeled only by `mcp.method.name` (one of the five methods above) and
+  `error.type`. No thrash detection or cost tracking applies.
+- **Ordering:** instrument before registering resources/prompts, same as
+  tools. If a handler for one of these methods already exists, that method
+  is skipped with a single `diag.warn`. It never throws, so turning this on
+  can't break an existing server. On an SDK v2 `McpServer`, declaring
+  `capabilities: { resources: {}, prompts: {} }` in the constructor
+  registers those handlers immediately (and so skips them); leave them out,
+  since registering a resource or prompt declares the capability for you.
+
+Design: [ADR 026](../../docs/adr/026-resources-prompts-coverage.md).
+
 ### Span attributes
 
 Every span follows the OpenTelemetry MCP semantic conventions (see
@@ -449,8 +504,30 @@ What it does, under `setupNodeSdk: true` and `enableMetrics` (default
   already registered, exactly as it does today.
 - Extends `server.shutdown()` (already attached under `setupNodeSdk: true`)
   to also flush and shut down the `MeterProvider` it registered, alongside
-  the existing `TracerProvider` shutdown — call it during your process's
-  shutdown sequence, same as before, to avoid losing buffered metric data.
+  the existing `TracerProvider` shutdown. As of v0.16.0 this runs
+  automatically when the process stops — see "Flushing on exit" below.
+
+### Flushing on exit (`flushOnExit`, v0.16.0)
+
+Under `setupNodeSdk: true`, buffered spans and dev-mode metrics are
+flushed automatically when the process stops. It's on by default; pass
+`flushOnExit: false` to turn it off. MCP clients built on the SDK's stdio
+transport stop a server by closing stdin, then sending SIGTERM 2 seconds
+later, then SIGKILL; this covers the first two:
+
+| Event | What happens |
+| --- | --- |
+| stdin closes and nothing else keeps the process alive | flushed on `beforeExit`; the process exits with its own exit code |
+| `SIGTERM` / `SIGINT` | flushed, then the same signal is re-raised so the process still dies by it, unless your code has its own listener for that signal, in which case yours decides |
+| `process.exit()` | **not covered**: call `await server.shutdown()` before exiting |
+| `SIGKILL` | can't be intercepted |
+
+The flush waits at most 1000 ms (`flushOnExit: { timeoutMs }` can only
+lower that), so a stuck exporter can't keep a stopping server alive.
+`server.shutdown()` is safe to call yourself as well: it runs once, however
+many times it's called. With `setupNodeSdk: false` this option does
+nothing — your application owns its providers and its shutdown. Design:
+[ADR 024](../../docs/adr/024-flush-on-exit.md).
 
 `@opentelemetry/sdk-metrics` is a real (non-dev) dependency of opentel-mcp
 as of this feature — not an optional peer, not a dynamic import with a
@@ -2241,6 +2318,7 @@ so they're spelled out instead of forced into one bucket.
 | `mcp.tool.pricing_status` | span attr, metric label | **blend — library-computed, depends on tool + host** | which of three enum values depends on a tool-controlled model name resolving (or not) in a library-default-or-host-overridden pricing table |
 | `mcp.failure.fingerprint` / `.signature` / `.category` / `.origin` / `.channel` | span attr (2 also metric labels) | library-computed | hashes/enums — the governed core this project has kept clean since v0.4.0 |
 | `mcp.failure.error_class` | span attr | **blend — tool-controlled, capped only** | `err.name`, length-capped at 128 characters but, unlike everything hashed into the fingerprint, *not* pattern-scrubbed — a documented, deliberate tradeoff (`docs/known-gaps.md` entry 10) |
+| `mcp.failure.unactionable` / `.content_length_bucket` | span attr | library-computed | a boolean and a 5-value enum derived from the trimmed text LENGTH and non-text item COUNT of an `isError: true` result — no text is read for anything but its length (ADR 025, v0.16.0) |
 | `mcp.failure.validation_paths` | span attr | mostly library-computed (gated) | one legacy Zod-issue-rendering path can still carry a tool-controlled dynamic object key, now redacted to a `<KEY>` placeholder rather than closed structurally (`docs/known-gaps.md` entry 10, item 3) |
 | `exception.type` (event) | event attr | tool-controlled | length-capped only under `'normalized'` mode; uncapped under `'full'` (the native SDK call) |
 | `exception.message` / `.stacktrace` (event), status message | event attr + status | **blend — layered** | raw tool content under `'full'`; this library's `normalizeMessage()`/`parseAndNormalizeStack()` transform of that same content under `'normalized'`; optionally a host-supplied `errorRecording.redactor`'s output feeding *that*, first (v0.14.0) — the most layered-provenance attribute in the system |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opentel-mcp",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "One-line OpenTelemetry instrumentation for Model Context Protocol (MCP) servers",
   "type": "module",
   "main": "src/index.js",
@@ -73,7 +73,8 @@
     "@opentelemetry/sdk-trace-node": "^2.9.0"
   },
   "devDependencies": {
-    "@modelcontextprotocol/server": "^2.0.0",
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "@modelcontextprotocol/server": "2.3.1",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/context-async-hooks": "^2.9.0",
     "@opentelemetry/sdk-trace-base": "^2.9.0",

package/src/attributes.js

@@ -76,6 +76,29 @@ export const MCP_METHOD_NAME_TOOLS_CALL = 'tools/call';
 /** Well-known mcp.method.name value for a tools/list request (ADR 010, schema drift detection). */
 export const MCP_METHOD_NAME_TOOLS_LIST = 'tools/list';
 
+// ADR 026 (v0.16.0, opt-in `coverage`): the five resource/prompt methods.
+// mcp.method.name only ever takes these fixed string constants, never a
+// value read from a request, so its value space stays bounded (7 total).
+
+/** Well-known mcp.method.name value for a resources/read request (ADR 026). */
+export const MCP_METHOD_NAME_RESOURCES_READ = 'resources/read';
+/** Well-known mcp.method.name value for a resources/list request (ADR 026). */
+export const MCP_METHOD_NAME_RESOURCES_LIST = 'resources/list';
+/** Well-known mcp.method.name value for a resources/templates/list request (ADR 026). */
+export const MCP_METHOD_NAME_RESOURCES_TEMPLATES_LIST = 'resources/templates/list';
+/** Well-known mcp.method.name value for a prompts/get request (ADR 026). */
+export const MCP_METHOD_NAME_PROMPTS_GET = 'prompts/get';
+/** Well-known mcp.method.name value for a prompts/list request (ADR 026). */
+export const MCP_METHOD_NAME_PROMPTS_LIST = 'prompts/list';
+
+/**
+ * gen_ai.prompt.name — the prompt a prompts/get span requested (ADR 026).
+ * Span attribute only, never a metric label. Capped at
+ * MAX_PROMPT_NAME_LENGTH, since the value comes from the request.
+ */
+export const ATTR_GEN_AI_PROMPT_NAME = 'gen_ai.prompt.name';
+export const MAX_PROMPT_NAME_LENGTH = 128;
+
 // --- Custom (non-spec) attributes ---
 
 /**

package/src/config.js

@@ -10,6 +10,8 @@ import { normalizeModelName } from './cost/calculator.js';
 import { resolveThrashConfig } from './thrash/config.js';
 import { resolveSchemaDriftConfig } from './schema-drift/config.js';
 import { resolveErrorRecordingConfig } from './error-recording/config.js';
+import { resolveFlushTimeout } from './flush-on-exit.js';
+import { resolveUnactionableErrorsConfig } from './unactionable.js';
 
 /**
  * @typedef {object} CostTrackingOptions
@@ -98,6 +100,31 @@ import { resolveErrorRecordingConfig } from './error-recording/config.js';
  *   variable (lower precedence than this option), same OTEL_MCP_<FEATURE>_ prefix pattern as
  *   OTEL_MCP_THRASH_ and OTEL_MCP_SCHEMA_DRIFT_; an unrecognized value from either source falls back to
  *   'full' silently, never a throw.
+ * @property {boolean | { timeoutMs?: number }} [flushOnExit] - ADR 024 (docs/adr/024-flush-on-exit.md):
+ *   flush the providers this library created when the process stops — on `beforeExit`, `SIGTERM` and `SIGINT`
+ *   — so spans and dev-mode metrics still buffered aren't lost. Only meaningful with `setupNodeSdk: true`,
+ *   where it defaults to ON; pass `false` to opt out. With `setupNodeSdk: false` (the default) it never has
+ *   any effect: the host owns its providers and its shutdown, and passing it logs a one-time `diag.warn`.
+ *   A signal is re-raised after the flush when the host has no listener of its own for it, so the process
+ *   still dies by that signal; with a host listener, the host decides. The flush waits at most `timeoutMs`
+ *   (default and maximum 1000 ms). Not covered: `process.exit()` (call `await server.shutdown()` first) and
+ *   `SIGKILL`.
+ * @property {Partial<import('./unactionable.js').UnactionableErrorsConfig>} [unactionableErrors] - ADR 025
+ *   (docs/adr/025-unactionable-errors.md): on every `isError: true` result, sets the span attributes
+ *   `mcp.failure.unactionable` (boolean) and `mcp.failure.content_length_bucket` (`empty` | `tiny` | `short` |
+ *   `medium` | `long`), computed only from the whitespace-trimmed length of the text items and the count of
+ *   non-text items — never from the text itself. Unactionable = no content, or under `minTextLength`
+ *   (default 10) characters of text with no image/audio/resource item. `{ enabled: true, minTextLength: 10 }`
+ *   by default; independent of `fingerprinting`. Span-only: never a metric label. Also settable via
+ *   `OTEL_MCP_UNACTIONABLE_ERRORS_ENABLED` / `OTEL_MCP_UNACTIONABLE_ERRORS_MIN_TEXT_LENGTH` (lower precedence).
+ * @property {{ resources?: boolean, prompts?: boolean }} [coverage] - ADR 026 (docs/adr/026-resources-prompts-coverage.md),
+ *   opt-in, both off by default: also trace `resources/read`, `resources/list`, `resources/templates/list`
+ *   (`resources: true`) and `prompts/get`, `prompts/list` (`prompts: true`). Spans are named by method
+ *   (`prompts/get <name>` for prompts/get), carry `mcp.method.name` and never `gen_ai.tool.name`; resource
+ *   URIs and prompt arguments are never captured. A handler for one of these methods that's already
+ *   registered when instrumentMcpServer() runs is skipped (not wrapped) with a single `diag.warn` — never a
+ *   throw. Durations go to the `mcp.server.operation.duration` histogram (labels: `mcp.method.name`,
+ *   `error.type`).
  * @property {string} [instanceKey] - Host-supplied stable identifier for one logical service (ADR 012,
  *   docs/adr/012-tracker-lifecycle-and-shared-state.md, Option C — Phase 2: this option and its wiring).
  *   When provided, the four in-memory trackers this library keeps per instrumented server — budget
@@ -135,6 +162,41 @@ export function __resetServiceNameWarnedForTests() {
   warnedServiceNameIgnored = false;
 }
 
+// Guards the "flushOnExit has no effect without setupNodeSdk" diagnostic
+// (ADR 024), same once-per-process pattern.
+let warnedFlushOnExitIgnored = false;
+
+// Test-only, same purpose as __resetServiceNameWarnedForTests above.
+export function __resetFlushOnExitWarnedForTests() {
+  warnedFlushOnExitIgnored = false;
+}
+
+/**
+ * ADR 024: `false` turns it off; an object supplies `timeoutMs`; anything
+ * else (true, undefined, null, junk) means "on, defaults". Only consulted
+ * when setupNodeSdk is true.
+ *
+ * @param {unknown} value
+ * @returns {{ timeoutMs: number } | null}
+ */
+function resolveFlushOnExit(value) {
+  if (value === false) return null;
+  const timeoutMs = value !== null && typeof value === 'object' ? /** @type {any} */ (value).timeoutMs : undefined;
+  return { timeoutMs: resolveFlushTimeout(timeoutMs) };
+}
+
+/**
+ * ADR 026: opt-in resources/* and prompts/* coverage. Only a literal `true`
+ * turns a family on; anything else (including the default) is off.
+ *
+ * @param {unknown} value
+ * @returns {{ resources: boolean, prompts: boolean }}
+ */
+function resolveCoverage(value) {
+  const v = value !== null && typeof value === 'object' ? /** @type {any} */ (value) : {};
+  return { resources: v.resources === true, prompts: v.prompts === true };
+}
+
 // Guards the DEFAULT_PRICING staleness diagnostic below (ADR 016 point 3),
 // same one-per-process pattern as warnedServiceNameIgnored above.
 let warnedPricingStale = false;
@@ -210,6 +272,16 @@ export function resolveOptions(options) {
     );
   }
 
+  const flushOnExitRequested = opts.flushOnExit !== undefined && opts.flushOnExit !== false;
+  if (!setupNodeSdk && flushOnExitRequested && !warnedFlushOnExitIgnored) {
+    warnedFlushOnExitIgnored = true;
+    diag.warn(
+      'opentel-mcp: flushOnExit was provided but setupNodeSdk is false, so it has no effect. ' +
+        'The host application owns its TracerProvider/MeterProvider and their shutdown — flush them in your ' +
+        "own shutdown sequence. See ADR 024, docs/adr/024-flush-on-exit.md.",
+    );
+  }
+
   const rawCostTracking = opts.costTracking ?? {};
   const costTrackingEnabled = rawCostTracking.enabled ?? true;
 
@@ -275,5 +347,8 @@ export function resolveOptions(options) {
     schemaDrift: resolveSchemaDriftConfig(opts.schemaDrift),
     errorRecording: resolveErrorRecordingConfig(opts.errorRecording),
     instanceKey: resolveInstanceKey(opts.instanceKey, process.env[ENV_INSTANCE_KEY]),
+    flushOnExit: setupNodeSdk ? resolveFlushOnExit(opts.flushOnExit) : null,
+    unactionableErrors: resolveUnactionableErrorsConfig(opts.unactionableErrors),
+    coverage: resolveCoverage(opts.coverage),
   };
 }

package/src/flush-on-exit.js

@@ -0,0 +1,215 @@
+/**
+ * @module flush-on-exit
+ *
+ * ADR 024 (docs/adr/024-flush-on-exit.md): flush the providers this
+ * library owns (setupNodeSdk: true) when the process is about to stop.
+ *
+ * MCP clients built on the SDK's StdioClientTransport stop a server by
+ * closing stdin, then SIGTERM 2 s later, then SIGKILL 2 s after that
+ * (@modelcontextprotocol/sdk client/stdio.js close()). `beforeExit` only
+ * covers the first step, and only when nothing else holds the loop open.
+ *
+ * One listener set per PROCESS, not per instrumented server: per-instance
+ * listeners would each see the others as "the host's own handler" and none
+ * would ever re-raise. Every instrumented server registers its memoized
+ * shutdown() here; the listeners flush them all.
+ *
+ * - beforeExit: flush once. The process then exits on its own with
+ *   whatever process.exitCode already was; nothing here changes it. No
+ *   process.exit() call: a host's own beforeExit work must not be cut short.
+ * - SIGTERM / SIGINT: remove our listener for that signal first (so a
+ *   second signal takes Node's default and kills immediately), flush
+ *   bounded by the timeout, then re-raise the same signal ONLY if no other
+ *   listener for it remains. Installing a signal listener removes Node's
+ *   default "exit on signal"; re-raising with no listeners restores it, so
+ *   the parent sees the same death-by-signal it would have without us. If
+ *   the host has its own listener, the host owns the exit.
+ * - The flush wait is capped (FLUSH_ON_EXIT_MAX_TIMEOUT_MS) with an
+ *   unref'd timer, so it never holds the process open by itself.
+ *
+ * Listeners are removed again once no server is registered (every
+ * instrumented server shut down), so an explicitly shut-down process has
+ * exactly the signal behavior it had before instrumenting.
+ *
+ * Never throws: everything that touches `process` is guarded.
+ */
+
+import { diag } from '@opentelemetry/api';
+
+/** Upper bound on how long a stop waits for telemetry to flush (ADR 024). */
+export const FLUSH_ON_EXIT_MAX_TIMEOUT_MS = 1000;
+
+const SIGNALS = /** @type {const} */ (['SIGTERM', 'SIGINT']);
+
+/** @type {Map<() => Promise<void>, number>} memoized shutdown -> its timeout */
+const registered = new Map();
+
+/** @type {{ beforeExit: (() => void) | null, SIGTERM: (() => void) | null, SIGINT: (() => void) | null }} */
+const listeners = { beforeExit: null, SIGTERM: null, SIGINT: null };
+
+let warnedInstallFailed = false;
+
+/**
+ * Clamps a user-supplied timeout into (0, FLUSH_ON_EXIT_MAX_TIMEOUT_MS].
+ * Anything that isn't a positive finite number gets the maximum.
+ *
+ * @param {unknown} value
+ * @returns {number}
+ */
+export function resolveFlushTimeout(value) {
+  if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
+    return Math.min(value, FLUSH_ON_EXIT_MAX_TIMEOUT_MS);
+  }
+  return FLUSH_ON_EXIT_MAX_TIMEOUT_MS;
+}
+
+/**
+ * Runs every registered shutdown once, in parallel, and resolves when all
+ * settle or the longest registered timeout elapses, whichever is first.
+ * Never rejects.
+ *
+ * @returns {Promise<void>}
+ */
+export function flushAll() {
+  const entries = [...registered];
+  registered.clear();
+  if (entries.length === 0) return Promise.resolve();
+
+  const timeoutMs = Math.max(...entries.map(([, ms]) => ms));
+  const work = Promise.allSettled(
+    entries.map(([shutdown]) => {
+      try {
+        return Promise.resolve(shutdown());
+      } catch (err) {
+        return Promise.reject(err);
+      }
+    }),
+  );
+
+  return new Promise((resolve) => {
+    let timer;
+    try {
+      timer = setTimeout(resolve, timeoutMs);
+      timer.unref?.();
+    } catch {
+      // No timers available: fall back to waiting for the work itself.
+    }
+    work.then(() => {
+      if (timer) clearTimeout(timer);
+      resolve();
+    });
+  });
+}
+
+function onBeforeExit() {
+  // Fires again once our own flush settles and the loop drains: nothing
+  // registered by then, so this returns and the process exits normally.
+  if (registered.size === 0) return;
+  flushAll().then(uninstallIfIdle, uninstallIfIdle);
+}
+
+/** @param {'SIGTERM' | 'SIGINT'} signal */
+function makeSignalListener(signal) {
+  const listener = () => {
+    try {
+      process.removeListener(signal, listener);
+    } catch {
+      // ignore
+    }
+    listeners[signal] = null;
+    flushAll().then(() => {
+      try {
+        if (process.listenerCount(signal) === 0) {
+          process.kill(process.pid, signal);
+          return;
+        }
+        uninstallIfIdle();
+      } catch (err) {
+        diag.debug(`opentel-mcp: flushOnExit could not re-raise ${signal}: ${err?.message ?? err}`);
+      }
+    });
+  };
+  return listener;
+}
+
+function install() {
+  try {
+    if (!listeners.beforeExit) {
+      listeners.beforeExit = onBeforeExit;
+      process.on('beforeExit', onBeforeExit);
+    }
+    for (const signal of SIGNALS) {
+      if (!listeners[signal]) {
+        const listener = makeSignalListener(signal);
+        listeners[signal] = listener;
+        process.on(signal, listener);
+      }
+    }
+    return true;
+  } catch (err) {
+    uninstall();
+    if (!warnedInstallFailed) {
+      warnedInstallFailed = true;
+      diag.warn(
+        `opentel-mcp: flushOnExit could not install process listeners (${err?.message ?? err}); ` +
+          'telemetry will not be flushed automatically on exit. Call `await server.shutdown()` yourself.',
+      );
+    }
+    return false;
+  }
+}
+
+function uninstall() {
+  try {
+    if (listeners.beforeExit) process.removeListener('beforeExit', listeners.beforeExit);
+    for (const signal of SIGNALS) {
+      if (listeners[signal]) process.removeListener(signal, listeners[signal]);
+    }
+  } catch {
+    // ignore
+  }
+  listeners.beforeExit = null;
+  listeners.SIGTERM = null;
+  listeners.SIGINT = null;
+}
+
+function uninstallIfIdle() {
+  if (registered.size === 0) uninstall();
+}
+
+/**
+ * Registers one instrumented server's memoized shutdown(). Returns an
+ * unregister function (idempotent). Never throws.
+ *
+ * @param {() => Promise<void>} shutdown
+ * @param {number} timeoutMs already resolved via resolveFlushTimeout()
+ * @returns {() => void}
+ */
+export function registerFlushOnExit(shutdown, timeoutMs) {
+  try {
+    registered.set(shutdown, timeoutMs);
+    if (!install()) registered.delete(shutdown);
+  } catch {
+    // never throw
+  }
+  return () => {
+    try {
+      registered.delete(shutdown);
+      uninstallIfIdle();
+    } catch {
+      // never throw
+    }
+  };
+}
+
+/** Test-only: drop every registration and listener. Not part of the public API. */
+export function __resetFlushOnExitForTests() {
+  registered.clear();
+  uninstall();
+  warnedInstallFailed = false;
+}
+
+/** Test-only: how many servers are registered. Not part of the public API. */
+export function __registeredCountForTests() {
+  return registered.size;
+}

package/src/index.d.ts

@@ -86,6 +86,65 @@ export interface InstrumentOptions {
    */
   setupNodeSdk?: boolean;
 
+  /**
+   * ADR 024: flush the providers this library created when the process
+   * stops — on `beforeExit`, `SIGTERM` and `SIGINT` — so buffered spans and
+   * dev-mode metrics aren't lost. Only meaningful with `setupNodeSdk: true`,
+   * where it defaults to on; pass `false` to opt out. With `setupNodeSdk:
+   * false` it never has any effect (the host owns its providers), and
+   * passing it logs a one-time `diag.warn`.
+   *
+   * After flushing, a signal is re-raised when no other listener for it
+   * exists, so the process still dies by that signal; if the host has its
+   * own listener, the host decides. The flush waits at most `timeoutMs`
+   * (default and maximum 1000 ms). Not covered: `process.exit()` (call
+   * `await server.shutdown()` first) and `SIGKILL`.
+   *
+   * @default true when `setupNodeSdk` is true
+   */
+  flushOnExit?: boolean | { timeoutMs?: number };
+
+  /**
+   * ADR 025: on every `isError: true` result, sets the span attributes
+   * `mcp.failure.unactionable` (boolean) and
+   * `mcp.failure.content_length_bucket` (`'empty' | 'tiny' | 'short' |
+   * 'medium' | 'long'`). Computed only from the whitespace-trimmed length of
+   * the text items and the count of non-text items, never from the text
+   * itself. Unactionable means no content, or fewer than `minTextLength`
+   * characters of text with no image/audio/resource item. Span-only (never a
+   * metric label); independent of `fingerprinting`. Also settable via
+   * `OTEL_MCP_UNACTIONABLE_ERRORS_ENABLED` /
+   * `OTEL_MCP_UNACTIONABLE_ERRORS_MIN_TEXT_LENGTH` (lower precedence).
+   *
+   * @default { enabled: true, minTextLength: 10 }
+   */
+  /**
+   * ADR 026, opt-in (both off by default): also trace `resources/read`,
+   * `resources/list`, `resources/templates/list` (`resources: true`) and
+   * `prompts/get`, `prompts/list` (`prompts: true`). Spans are named by
+   * method (`prompts/get <name>` for prompts/get), carry `mcp.method.name`,
+   * and never carry `gen_ai.tool.name`. Resource URIs, prompt arguments and
+   * result content are never captured; on a thrown error the span gets
+   * status ERROR, `error.type` and (with fingerprinting) the
+   * `mcp.failure.*` hash/enums, never the exception message. Durations go
+   * to the `mcp.server.operation.duration` histogram (labels:
+   * `mcp.method.name`, `error.type`). A handler for one of these methods
+   * that's already registered when `instrumentMcpServer()` runs is skipped
+   * with a single `diag.warn`, never a throw.
+   *
+   * @default { resources: false, prompts: false }
+   */
+  coverage?: {
+    resources?: boolean;
+    prompts?: boolean;
+  };
+
+  unactionableErrors?: {
+    enabled?: boolean;
+    /** Integer 0–200. `0` flags only empty (or whitespace-only) errors. @default 10 */
+    minTextLength?: number;
+  };
+
   /**
    * Controls the `mcp.tool.tokens.*` / `mcp.tool.model` / `mcp.tool.cost.*` span attributes, the
    * `mcp.tool.tokens.total` / `mcp.tool.cost.total` metrics, and the optional per-session/per-tool budget
@@ -383,6 +442,10 @@ export function instrumentMcpServer<T extends DuckTypedServer | DuckTypedMcpServ
   server: T,
   options?: InstrumentOptions,
 ): T & {
+  /**
+   * Present under `setupNodeSdk: true`. Flushes and shuts down the providers
+   * this library created. Idempotent: every call returns the same promise.
+   */
   shutdown?: () => Promise<void>;
   getThrashSummary?: (options?: { topOffendersLimit?: number }) => ThrashSummary;
   getObservationState?: () => ObservationState;

package/src/instrument.js

@@ -31,8 +31,17 @@ import { createSchemaDriftEmitter } from './schema-drift/emitter.js';
 import { ToolOutcomeCounter } from './observation/tool-outcome-counter.js';
 import { detectObservationIntegrity } from './observation/integrity.js';
 import { InstanceRegistry } from './registry/instance-registry.js';
+import { registerFlushOnExit } from './flush-on-exit.js';
+import { applyUnactionableAttributes } from './unactionable.js';
 import {
   ATTR_MCP_METHOD_NAME,
+  ATTR_GEN_AI_PROMPT_NAME,
+  MAX_PROMPT_NAME_LENGTH,
+  MCP_METHOD_NAME_RESOURCES_READ,
+  MCP_METHOD_NAME_RESOURCES_LIST,
+  MCP_METHOD_NAME_RESOURCES_TEMPLATES_LIST,
+  MCP_METHOD_NAME_PROMPTS_GET,
+  MCP_METHOD_NAME_PROMPTS_LIST,
   ATTR_GEN_AI_TOOL_NAME,
   ATTR_GEN_AI_OPERATION_NAME,
   ATTR_GEN_AI_RESPONSE_MODEL,
@@ -390,8 +399,29 @@ export function instrumentMcpServer(input, options) {
     return input;
   }
 
+  // v2 McpServer declared with `capabilities.tools` installs its own
+  // tools/list + tools/call dispatchers in its constructor, before this
+  // function can ever run — see hasConstructorInstalledToolHandlers().
+  // Those aren't user handlers that would be bypassed: they're McpServer's
+  // own, and McpServer will install identical ones again on request. Take
+  // them down here (public removeRequestHandler) so the ordering check
+  // below only sees genuine user registrations, and re-install them through
+  // the patched setRequestHandler at the end of this function. If anything
+  // in between throws, McpServer re-installs them (unwrapped) on its next
+  // registerTool(), since its own guard flag is reset too.
+  const reinstallToolHandlers = hasConstructorInstalledToolHandlers(server, outer, kind);
+  if (reinstallToolHandlers) {
+    server.removeRequestHandler(TOOLS_CALL_METHOD);
+    server.removeRequestHandler(TOOLS_LIST_METHOD);
+    outer._toolHandlersInitialized = false;
+  }
+
   assertInstrumentFirst(server, resolved);
 
+  // ADR 026: opt-in resources/* and prompts/* methods to wrap — minus any
+  // already registered (skipped with one diag.warn, never a throw).
+  const coveredMethods = resolveCoveredMethods(server, resolved);
+
   const tracer = setupTracer(server, resolved);
   const metricsRecorder = resolved.enableMetrics ? setupMeter(PACKAGE_VERSION) : null;
   // One tracker per instrumented server, not per call — session/tool cost
@@ -586,6 +616,7 @@ export function instrumentMcpServer(input, options) {
           resolved.errorRecording,
           costAttributionState,
           errorRecordingState,
+          resolved.unactionableErrors,
         );
       } else if (schema === v1.ListToolsRequestSchema && schemaDriftDetector) {
         handler = wrapToolsListHandler(
@@ -598,6 +629,11 @@ export function instrumentMcpServer(input, options) {
           resolved.errorRecording,
           errorRecordingState,
         );
+      } else if (coveredMethods.size > 0) {
+        const method = v1CoveredMethodForSchema(v1, schema);
+        if (method && coveredMethods.has(method)) {
+          handler = wrapNonToolHandler(handler, method, tracer, metricsRecorder, resolved.fingerprinting, kind);
+        }
       }
       return originalSetRequestHandler(schema, handler);
     };
@@ -640,6 +676,7 @@ export function instrumentMcpServer(input, options) {
           resolved.errorRecording,
           costAttributionState,
           errorRecordingState,
+          resolved.unactionableErrors,
         );
       } else if (maybeHandler === undefined && method === TOOLS_LIST_METHOD && schemaDriftDetector) {
         handlerOrSchemas = wrapToolsListHandler(
@@ -653,17 +690,202 @@ export function instrumentMcpServer(input, options) {
           errorRecordingState,
         );
       }
+      if (maybeHandler === undefined && coveredMethods.has(method)) {
+        handlerOrSchemas = wrapNonToolHandler(handlerOrSchemas, method, tracer, metricsRecorder, resolved.fingerprinting, kind);
+      }
       return maybeHandler === undefined
         ? originalSetRequestHandler(method, handlerOrSchemas)
         : originalSetRequestHandler(method, handlerOrSchemas, maybeHandler);
     };
   }
 
+  if (reinstallToolHandlers) {
+    // McpServer's own (TS-private) installer, guarded by the flag reset
+    // above: re-registers its tools/list + tools/call dispatchers, this time
+    // through the patched setRequestHandler, so they come back wrapped.
+    outer.setToolRequestHandlers();
+  }
+
   server[kInstrumented] = true;
   if (outer) outer[kInstrumented] = true;
   return input;
 }
 
+/**
+ * True when `outer` is a v2 McpServer whose tools/list + tools/call
+ * handlers were installed by its own constructor rather than by the user:
+ * v2's constructor calls `this.setToolRequestHandlers()` when
+ * `capabilities.tools` is declared (@modelcontextprotocol/server 2.x,
+ * `mcp-*.mjs`: `if (options?.capabilities?.tools) this.setToolRequestHandlers()`),
+ * so with that (common) option the handlers exist before
+ * instrumentMcpServer() can be called at all, and ADR 002's check threw on
+ * every such server.
+ *
+ * Deliberately narrow, so every genuine misorder still throws:
+ * - v2 McpServer only (v1's McpServer never installs eagerly);
+ * - its installer ran (`_toolHandlersInitialized === true`) but no tool has
+ *   been registered yet (`_registeredTools` empty). A tool registered before
+ *   instrumenting keeps throwing, same as v1 and same as before;
+ * - not yet connected: re-installing calls `registerCapabilities()`, which
+ *   v2 refuses after connect, so a connected server keeps the old behavior;
+ * - every member used is feature-detected. These are McpServer internals
+ *   (ADR 001/002 avoid them in general); they're read only to recognize
+ *   McpServer's own handlers, never to reach a handler function. Any
+ *   mismatch falls back to the previous behavior (ADR 002's throw).
+ *
+ * Known limit: a user who replaced McpServer's own dispatcher directly on
+ * `mcp.server` (setRequestHandler after construction, no tool registered)
+ * is indistinguishable from the constructor's handler without reading the
+ * private handler map; that handler would be replaced by McpServer's.
+ *
+ * Never throws.
+ *
+ * @returns {boolean}
+ */
+function hasConstructorInstalledToolHandlers(server, outer, kind) {
+  try {
+    if (kind !== 'v2' || !outer) return false;
+    const registered = outer._registeredTools;
+    return (
+      outer._toolHandlersInitialized === true &&
+      registered !== null &&
+      typeof registered === 'object' &&
+      Object.keys(registered).length === 0 &&
+      typeof outer.setToolRequestHandlers === 'function' &&
+      typeof server.removeRequestHandler === 'function' &&
+      !server.transport
+    );
+  } catch {
+    return false;
+  }
+}
+
+const RESOURCE_METHODS = [
+  MCP_METHOD_NAME_RESOURCES_READ,
+  MCP_METHOD_NAME_RESOURCES_LIST,
+  MCP_METHOD_NAME_RESOURCES_TEMPLATES_LIST,
+];
+const PROMPT_METHODS = [MCP_METHOD_NAME_PROMPTS_GET, MCP_METHOD_NAME_PROMPTS_LIST];
+
+/**
+ * ADR 026: which resources/* and prompts/* methods this instance wraps.
+ * Only the families the caller opted into (`coverage`), minus any method
+ * whose handler is already registered: wrapping happens at registration
+ * (ADR 001), so an existing handler can't be wrapped, and ADR 010 showed
+ * that throwing on misorder breaks upgrades. Such methods are skipped with
+ * ONE diag.warn naming them — never a throw. Never throws.
+ *
+ * @returns {Set<string>}
+ */
+function resolveCoveredMethods(server, resolved) {
+  const covered = new Set();
+  try {
+    const wanted = [
+      ...(resolved.coverage.resources ? RESOURCE_METHODS : []),
+      ...(resolved.coverage.prompts ? PROMPT_METHODS : []),
+    ];
+    const skipped = [];
+    for (const method of wanted) {
+      if (typeof server.assertCanSetRequestHandler === 'function') {
+        try {
+          server.assertCanSetRequestHandler(method);
+        } catch {
+          skipped.push(method);
+          continue;
+        }
+      }
+      covered.add(method);
+    }
+    if (skipped.length > 0) {
+      diag.warn(
+        `opentel-mcp: coverage requested for ${skipped.join(', ')}, but a handler for ` +
+          `${skipped.length === 1 ? 'it' : 'each'} was already registered, so ${skipped.length === 1 ? 'it is' : 'they are'} not traced. ` +
+          'Call instrumentMcpServer() before registering resources/prompts. On an SDK v2 McpServer, ' +
+          "don't declare capabilities.resources/prompts in the constructor (that registers the handlers immediately); " +
+          'registering a resource or prompt declares the capability for you. See ADR 026.',
+      );
+    }
+  } catch {
+    // never throw
+  }
+  return covered;
+}
+
+/**
+ * v1 dispatches by schema object identity (ADR 001); maps a schema to its
+ * ADR 026 method name, or undefined. Never throws.
+ */
+function v1CoveredMethodForSchema(v1, schema) {
+  if (!v1 || !schema) return undefined;
+  if (schema === v1.ReadResourceRequestSchema) return MCP_METHOD_NAME_RESOURCES_READ;
+  if (schema === v1.ListResourcesRequestSchema) return MCP_METHOD_NAME_RESOURCES_LIST;
+  if (schema === v1.ListResourceTemplatesRequestSchema) return MCP_METHOD_NAME_RESOURCES_TEMPLATES_LIST;
+  if (schema === v1.GetPromptRequestSchema) return MCP_METHOD_NAME_PROMPTS_GET;
+  if (schema === v1.ListPromptsRequestSchema) return MCP_METHOD_NAME_PROMPTS_LIST;
+  return undefined;
+}
+
+/**
+ * ADR 026: a SERVER span around one resources/* or prompts/* handler.
+ *
+ * - Name: the method; `prompts/get <prompt name>` for prompts/get.
+ * - `mcp.method.name` always; `gen_ai.prompt.name` on prompts/get (capped);
+ *   `gen_ai.tool.name` NEVER set — absent, not empty.
+ * - Never captured: resource URIs (request params or results), prompt
+ *   arguments, result content. On a thrown error, only status ERROR,
+ *   `error.type` (the class name), and — with fingerprinting — the
+ *   fingerprint hash/category/channel enums. The exception message and
+ *   stack are deliberately NOT recorded here, whatever errorRecording.mode
+ *   says: the SDK's own resource errors embed the URI in the message
+ *   (e.g. `Resource ${uri} not found`).
+ * - Duration: mcp.server.operation.duration, labeled by method (+ error.type).
+ * - No thrash detection, no cost attribution, no isError handling (these
+ *   methods have no such result field).
+ *
+ * The handler's result and errors pass through unchanged.
+ */
+function wrapNonToolHandler(handler, method, tracer, metricsRecorder, fingerprintingEnabled, kind) {
+  return (request, extra) => {
+    let promptName;
+    const rawName = request?.params?.name;
+    if (method === MCP_METHOD_NAME_PROMPTS_GET && typeof rawName === 'string' && rawName !== '') {
+      promptName = rawName.slice(0, MAX_PROMPT_NAME_LENGTH);
+    }
+    const spanName = promptName ? `${method} ${promptName}` : method;
+    const parentContext = extractTraceContext(request?.params?._meta);
+
+    return tracer.startActiveSpan(spanName, { kind: SpanKind.SERVER }, parentContext, async (span) => {
+      span.setAttribute(ATTR_MCP_METHOD_NAME, method);
+      if (promptName) span.setAttribute(ATTR_GEN_AI_PROMPT_NAME, promptName);
+      const { requestId } = extractSessionAndRequestId(kind, extra);
+      if (requestId !== undefined && requestId !== null) {
+        span.setAttribute(ATTR_JSONRPC_REQUEST_ID, String(requestId));
+      }
+
+      const startTime = performance.now();
+      try {
+        const result = await handler(request, extra);
+        span.setStatus({ code: SpanStatusCode.OK });
+        metricsRecorder?.recordOperationDuration(method, performance.now() - startTime);
+        return result;
+      } catch (err) {
+        span.setStatus({ code: SpanStatusCode.ERROR });
+        const errorType = String(err?.name ?? 'Error').slice(0, MAX_ERROR_CLASS_LENGTH);
+        span.setAttribute(ATTR_ERROR_TYPE, errorType);
+        if (fingerprintingEnabled) {
+          const failure = computeFingerprint(err, { toolName: undefined, origin: 'thrown', cwd: process.cwd() });
+          span.setAttributes(toSpanAttributes(failure));
+          span.setAttribute(ATTRIBUTE_KEYS.CHANNEL, classifyFailureChannel(err));
+        }
+        metricsRecorder?.recordOperationDuration(method, performance.now() - startTime, errorType);
+        throw err;
+      } finally {
+        span.end();
+      }
+    });
+  };
+}
+
 /**
  * Throws INSTRUMENT_FIRST_ERROR if a tools/call handler — or, when schema
  * drift detection is enabled, a tools/list handler — is already
@@ -811,10 +1033,25 @@ function setupTracer(server, resolved) {
       }
     }
 
-    server.shutdown = async () => {
-      await provider.shutdown();
-      if (meterProvider) await meterProvider.shutdown();
+    // Memoized (ADR 024): the first call — from the host, or from
+    // flushOnExit's process listeners — creates the promise; every later
+    // call gets the same one, so the providers are shut down exactly once.
+    let shutdownPromise = null;
+    let unregisterFlushOnExit = null;
+    const shutdown = () => {
+      if (!shutdownPromise) {
+        unregisterFlushOnExit?.();
+        shutdownPromise = (async () => {
+          await provider.shutdown();
+          if (meterProvider) await meterProvider.shutdown();
+        })();
+      }
+      return shutdownPromise;
     };
+    server.shutdown = shutdown;
+    if (resolved.flushOnExit) {
+      unregisterFlushOnExit = registerFlushOnExit(shutdown, resolved.flushOnExit.timeoutMs);
+    }
   }
 
   // Always the final step: when setupNodeSdk is false, this picks up
@@ -1712,6 +1949,7 @@ function wrapToolCallHandler(
   errorRecordingConfig,
   costAttributionState,
   errorRecordingState,
+  unactionableErrorsConfig,
 ) {
   return (request, extra) => {
     const toolName = request?.params?.name;
@@ -1772,6 +2010,10 @@ function wrapToolCallHandler(
         if (isToolResultError(result)) {
           span.setAttribute(ATTR_ERROR_TYPE, ERROR_TYPE_TOOL_ERROR);
           span.setStatus({ code: SpanStatusCode.ERROR });
+          // ADR 025: content SHAPE only (lengths, item counts), own
+          // try/catch, before fingerprinting so a classifier problem can't
+          // suppress it. Doesn't feed the fingerprint or the category.
+          applyUnactionableAttributes(span, result, unactionableErrorsConfig);
 
           let failureCategory = '';
           let failure = null;

package/src/metrics.js

@@ -76,6 +76,7 @@ import { ATTRIBUTE_KEYS } from './fingerprint/attributes.js';
  *   recordDuration: (toolName: string | undefined, durationMs: number, outcome: string, failureCategory?: string) => void,
  *   recordTokens: (toolName: string | undefined, model: string | undefined, totalTokens: number, pricingStatus: string) => void,
  *   recordCost: (toolName: string | undefined, model: string | undefined, costUsd: number, pricingStatus: string) => void,
+ *   recordOperationDuration: (method: string, durationMs: number, errorType?: string) => void,
  * }}
  */
 export function setupMeter(packageVersion) {
@@ -103,8 +104,22 @@ export function setupMeter(packageVersion) {
     description: 'Total estimated cost of MCP tool calls (see src/cost/calculator.js).',
     unit: 'USD',
   });
+  // ADR 026 (v0.16.0): resources/* and prompts/* handler durations, only
+  // recorded when that opt-in coverage is on. Labeled by mcp.method.name
+  // (one of five fixed constants) and, on failure, error.type: no new
+  // label keys, and nothing request-derived (no URI, no prompt name).
+  const operationDuration = meter.createHistogram('mcp.server.operation.duration', {
+    description: 'Duration of MCP resources/* and prompts/* request handling (opt-in coverage, ADR 026).',
+    unit: 'ms',
+  });
 
   return {
+    recordOperationDuration(method, durationMs, errorType) {
+      operationDuration.record(durationMs, {
+        [ATTR_MCP_METHOD_NAME]: method,
+        ...(errorType ? { [ATTR_ERROR_TYPE]: errorType } : {}),
+      });
+    },
     recordCall(toolName) {
       calls.add(1, {
         [ATTR_GEN_AI_TOOL_NAME]: toolName,

package/src/sdk/detect.js

@@ -74,13 +74,20 @@ const [v1ServerMod, v1TypesMod, v2Mod] = await Promise.all([
   tryImport('@modelcontextprotocol/server'),
 ]);
 
-/** @type {{ Server: Function, CallToolRequestSchema: unknown, ListToolsRequestSchema: unknown } | null} */
+/** @type {{ Server: Function, CallToolRequestSchema: unknown, ListToolsRequestSchema: unknown, [schema: string]: unknown } | null} */
 const v1Sdk =
   v1ServerMod && v1TypesMod
     ? {
         Server: v1ServerMod.Server,
         CallToolRequestSchema: v1TypesMod.CallToolRequestSchema,
         ListToolsRequestSchema: v1TypesMod.ListToolsRequestSchema,
+        // ADR 026 (opt-in coverage): v1 dispatches by schema identity, so
+        // each resource/prompt method needs its schema object too.
+        ReadResourceRequestSchema: v1TypesMod.ReadResourceRequestSchema,
+        ListResourcesRequestSchema: v1TypesMod.ListResourcesRequestSchema,
+        ListResourceTemplatesRequestSchema: v1TypesMod.ListResourceTemplatesRequestSchema,
+        GetPromptRequestSchema: v1TypesMod.GetPromptRequestSchema,
+        ListPromptsRequestSchema: v1TypesMod.ListPromptsRequestSchema,
       }
     : null;
 
@@ -101,7 +108,7 @@ const v2Sdk = v2Mod ? { Server: v2Mod.Server } : null;
  * Resolves `@modelcontextprotocol/sdk` (v1). `null` when not installed (an
  * optional peer dependency — see this module's docblock).
  *
- * @returns {{ Server: Function, CallToolRequestSchema: unknown, ListToolsRequestSchema: unknown } | null}
+ * @returns {{ Server: Function, CallToolRequestSchema: unknown, ListToolsRequestSchema: unknown, [schema: string]: unknown } | null}
  */
 export function getV1Sdk() {
   return v1Sdk;

package/src/unactionable.js

@@ -0,0 +1,129 @@
+/**
+ * @module unactionable
+ *
+ * ADR 025 (docs/adr/025-unactionable-errors.md): flag tool errors that give
+ * the agent nothing to act on — `isError: true` with empty or near-empty
+ * content.
+ *
+ * PRIVACY: computed only from the SHAPE of `result.content` — how many
+ * items are text vs. non-text, and the whitespace-trimmed LENGTH of the
+ * text items. Strings are read only to be measured; no text is stored,
+ * hashed, compared, or emitted. The two attributes produced have fixed,
+ * tiny value domains (a boolean, and one of five bucket names).
+ *
+ * Span-only. Neither attribute is a metric label (ADR 025 "Metric"); they
+ * are deliberately NOT in any METRIC_SAFE_ATTRIBUTES list.
+ */
+
+/** Boolean: the tool error gave the agent nothing to act on. */
+export const ATTR_MCP_FAILURE_UNACTIONABLE = 'mcp.failure.unactionable';
+
+/** One of CONTENT_LENGTH_BUCKETS: the trimmed text length of the error, bucketed. */
+export const ATTR_MCP_FAILURE_CONTENT_LENGTH_BUCKET = 'mcp.failure.content_length_bucket';
+
+/** The only values `mcp.failure.content_length_bucket` ever takes. */
+export const CONTENT_LENGTH_BUCKETS = Object.freeze(['empty', 'tiny', 'short', 'medium', 'long']);
+
+const SHORT_LIMIT = 80;
+const MEDIUM_LIMIT = 500;
+
+const ENV_PREFIX = 'OTEL_MCP_UNACTIONABLE_ERRORS_';
+const DEFAULTS = Object.freeze({ enabled: true, minTextLength: 10 });
+const MAX_MIN_TEXT_LENGTH = 200;
+
+/**
+ * @typedef {object} UnactionableErrorsConfig
+ * @property {boolean} enabled
+ * @property {number} minTextLength
+ */
+
+function readEnvBoolean(name) {
+  const raw = process.env[name];
+  if (raw === 'true' || raw === '1') return true;
+  if (raw === 'false' || raw === '0') return false;
+  return undefined;
+}
+
+function readEnvInt(name) {
+  const raw = process.env[name];
+  if (raw === undefined || raw.trim() === '') return undefined;
+  const parsed = Number(raw);
+  return Number.isInteger(parsed) ? parsed : undefined;
+}
+
+/**
+ * Same partial-overrides-individual-defaults behavior, and the same
+ * OTEL_MCP_<FEATURE>_ env-var fallback, as resolveSchemaDriftConfig().
+ * Invalid values fall back to the defaults; never throws.
+ *
+ * @param {Partial<UnactionableErrorsConfig> | undefined} partial
+ * @returns {UnactionableErrorsConfig}
+ */
+export function resolveUnactionableErrorsConfig(partial) {
+  const p = partial !== null && typeof partial === 'object' ? partial : {};
+  const enabled = p.enabled !== undefined ? p.enabled : readEnvBoolean(`${ENV_PREFIX}ENABLED`);
+  const minTextLength = p.minTextLength !== undefined ? p.minTextLength : readEnvInt(`${ENV_PREFIX}MIN_TEXT_LENGTH`);
+  return {
+    enabled: typeof enabled === 'boolean' ? enabled : DEFAULTS.enabled,
+    minTextLength:
+      typeof minTextLength === 'number' &&
+      Number.isInteger(minTextLength) &&
+      minTextLength >= 0 &&
+      minTextLength <= MAX_MIN_TEXT_LENGTH
+        ? minTextLength
+        : DEFAULTS.minTextLength,
+  };
+}
+
+/**
+ * @param {unknown} result a CallToolResult with isError: true
+ * @param {number} minTextLength
+ * @returns {{ unactionable: boolean, bucket: string }}
+ */
+export function assessToolErrorContent(result, minTextLength) {
+  const content = /** @type {any} */ (result)?.content;
+  let textLength = 0;
+  let nonText = 0;
+
+  if (Array.isArray(content)) {
+    for (const item of content) {
+      if (item === null || typeof item !== 'object') continue;
+      if (item.type === 'text') {
+        if (typeof item.text === 'string') textLength += item.text.trim().length;
+      } else {
+        // image, audio, resource, resource_link, or anything else typed:
+        // the agent was handed something other than prose.
+        nonText++;
+      }
+    }
+  }
+
+  let bucket;
+  if (textLength === 0) bucket = 'empty';
+  else if (textLength < minTextLength) bucket = 'tiny';
+  else if (textLength < SHORT_LIMIT) bucket = 'short';
+  else if (textLength < MEDIUM_LIMIT) bucket = 'medium';
+  else bucket = 'long';
+
+  const unactionable = nonText === 0 && (textLength === 0 || textLength < minTextLength);
+  return { unactionable, bucket };
+}
+
+/**
+ * Sets both attributes on `span` for an isError: true result. Never throws:
+ * on any failure both attributes are omitted rather than guessed.
+ *
+ * @param {import('@opentelemetry/api').Span} span
+ * @param {unknown} result
+ * @param {UnactionableErrorsConfig} config
+ */
+export function applyUnactionableAttributes(span, result, config) {
+  try {
+    if (!config?.enabled) return;
+    const { unactionable, bucket } = assessToolErrorContent(result, config.minTextLength);
+    span.setAttribute(ATTR_MCP_FAILURE_UNACTIONABLE, unactionable);
+    span.setAttribute(ATTR_MCP_FAILURE_CONTENT_LENGTH_BUCKET, bucket);
+  } catch {
+    // Never throw into the tool-call path (ADR 025 "Order").
+  }
+}