Widthdom · Widthdom · May 25, 2026 · May 24, 2026 · May 24, 2026 · May 24, 2026
diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md
@@ -177,6 +177,18 @@ Operators can override the defaults with environment variables:
 
 After a successful `cdidx index` run, the writer refreshes SQLite planner statistics so large repositories do not rely on default selectivity estimates for `search`, `references`, `callers`, and related joins. A brand-new index database runs full `ANALYZE` once after the initial population; later successful index runs use SQLite's lighter `PRAGMA optimize`. This maintenance is best-effort and never changes the schema contract.
 
+### MCP request correlation
+
+Each JSON-RPC MCP request gets a server-generated `correlation_id` in addition to the client-controlled JSON-RPC `id`. Successful MCP responses include it under `result._meta.correlation_id`, and error responses include it in `error.data.correlation_id` or tool-error `result.structuredContent.correlation_id`. The serialized JSON-RPC id is echoed as `request_id` in the same metadata when one exists. `batch_query` assigns child correlation IDs to each slot by suffixing the parent value with `.1`, `.2`, and so on.
+
+MCP stderr diagnostics are prefixed with `[rid=<json-rpc-id> cid=<correlation-id>]` when a request context exists. Every `tools/call` also emits one structured JSON line with `event: "mcp.tool.invocation"`, the tool name, elapsed milliseconds, status, result count when available, error metadata, argument keys, and argument lengths. Argument values are intentionally not logged in this telemetry line.
+
+### MCP リクエスト相関
+
+各 JSON-RPC MCP リクエストには、クライアント制御の JSON-RPC `id` とは別に、サーバー生成の `correlation_id` が割り当てられます。成功レスポンスでは `result._meta.correlation_id`、エラーレスポンスでは `error.data.correlation_id` またはツールエラーの `result.structuredContent.correlation_id` に含まれます。JSON-RPC id がある場合は、同じメタデータにシリアライズ済みの値を `request_id` として入れます。`batch_query` は親の値に `.1`、`.2` のような suffix を付けた子 correlation ID を各スロットに割り当てます。
+
+MCP stderr 診断は、リクエストコンテキストがある場合に `[rid=<json-rpc-id> cid=<correlation-id>]` で prefix されます。各 `tools/call` はさらに `event: "mcp.tool.invocation"` の構造化 JSON 行を 1 行出力し、tool 名、経過ミリ秒、status、取得できる場合の result count、エラーメタデータ、引数キー、引数長を含めます。この telemetry 行には引数値を記録しません。
+
 ## Database schema
 
 Persisted SHA-256 hashes are lowercase hexadecimal strings. New hash emitters

diff --git a/changelog.d/unreleased/1814.fixed.md b/changelog.d/unreleased/1814.fixed.md
@@ -0,0 +1,17 @@
+---
+category: fixed
+issues:
+  - 1814
+affected:
+  - src/CodeIndex/Mcp/McpServer.cs
+  - tests/CodeIndex.Tests/McpServerTests.cs
+  - DEVELOPER_GUIDE.md
+---
+
+## English
+
+- **MCP request IDs now flow into diagnostics (#1814)** — MCP stderr diagnostics and error payloads now include request/correlation metadata so operators can tie failures back to the JSON-RPC request that produced them.
+
+## 日本語
+
+- **MCP request ID が診断情報へ伝播するようになりました (#1814)** — MCP の stderr 診断とエラーペイロードに request/correlation metadata を含め、どの JSON-RPC リクエストが失敗を発生させたか追跡できるようにしました。
diff --git a/changelog.d/unreleased/1897.fixed.md b/changelog.d/unreleased/1897.fixed.md
@@ -0,0 +1,18 @@
+---
+category: fixed
+issues:
+  - 1897
+affected:
+  - src/CodeIndex/Mcp/McpServer.cs
+  - src/CodeIndex/Mcp/McpToolHandlers.cs
+  - tests/CodeIndex.Tests/McpServerTests.cs
+  - DEVELOPER_GUIDE.md
+---
+
+## English
+
+- **MCP responses now expose stable correlation IDs (#1897)** — each MCP request now receives a server-generated correlation ID, successful responses echo it under `_meta`, errors include it in structured data, and `batch_query` slots get child IDs.
+
+## 日本語
+
+- **MCP レスポンスが安定した correlation ID を返すようになりました (#1897)** — MCP リクエストごとにサーバー生成の correlation ID を割り当て、成功レスポンスは `_meta`、エラーは構造化データに含め、`batch_query` の各スロットにも子 ID を付与します。
diff --git a/changelog.d/unreleased/1898.added.md b/changelog.d/unreleased/1898.added.md
@@ -0,0 +1,17 @@
+---
+category: added
+issues:
+  - 1898
+affected:
+  - src/CodeIndex/Mcp/McpServer.cs
+  - tests/CodeIndex.Tests/McpServerTests.cs
+  - DEVELOPER_GUIDE.md
+---
+
+## English
+
+- **MCP tool invocation telemetry is emitted to stderr (#1898)** — every MCP `tools/call` now writes a structured `mcp.tool.invocation` event with timing, status, result-count, and redacted argument-shape metadata.
+
+## 日本語
+
+- **MCP tool invocation telemetry を stderr に出力するようになりました (#1898)** — 各 MCP `tools/call` が、所要時間、status、result count、引数形状の redacted metadata を含む構造化 `mcp.tool.invocation` event を出力します。