Debug + Harden MCP Server on Claude Code (WebSocket, HMAC-signed requests)

You are an on-call agent platform engineer. An MCP server works locally (responds to `mcp inspector`) but behaves badly inside Claude Code on WebSocket with HMAC-signed requests. Produce a full diagnostic playbook and a hardening patch.

**Observed symptoms (pick any that apply):** intermittent "tool not found", tool call hangs >30s, auth works on first call then fails, resources render empty, model ignores tool even when clearly needed, server silently exits under Claude Code.

## Part 1 — Diagnostic ladder

Walk through these in order, each with exact commands to run:

1. **Is the server process alive under Claude Code?**
   - Where Claude Code logs MCP server stdout/stderr (exact path)
   - How to tail them live
   - Crash vs. zombie vs. healthy signatures

2. **Is the transport handshake succeeding?**
   - For WebSocket: what the `initialize` request/response looks like
   - Common transport-specific failure modes (WebSocket quirks)
   - How to capture the wire traffic (mcp inspector, proxy, curl -N for SSE, wscat for WebSocket)

3. **Is tool discovery working?**
   - `tools/list` response — is your tool present with the right schema?
   - Are input schemas rejected by Claude Code as invalid? (common JSON Schema pitfalls)
   - Description length limits and truncation behavior in Claude Code

4. **Is HMAC-signed requests surviving the session?**
   - Token expiry within a long session
   - 401 retry behavior
   - Credential-in-env vs. credential-in-request-header for this host

5. **Is the model choosing the tool?**
   - Is the tool description clear enough for the model? (rewrite rules)
   - Does the tool name conflict with built-ins?
   - Is the model instead hallucinating an answer?

6. **Is the tool actually returning useful content?**
   - Content types Claude Code renders vs. silently drops
   - Max result size before truncation

## Part 2 — Hardening patch

Produce a diff-style set of changes covering:

- Idempotency keys on destructive tool calls
- Per-tool timeout with clean cancellation
- Structured error envelope (`isError: true`, machine-readable code, human message)
- Retry logic on the upstream with exponential backoff + jitter
- Graceful HMAC-signed requests refresh mid-session
- Health check endpoint (if WebSocket supports it)
- Concurrency cap (don't let the model hammer a fragile upstream)
- PII redaction in logs
- Graceful SIGTERM that drains in-flight calls

## Part 3 — Regression harness

Create a test suite that runs in CI and would have caught each of the symptoms above:

- Scripted MCP client session replaying a failing trace
- Fault injection: force upstream to 500, force slow response, force HMAC-signed requests expiry
- Golden-trajectory tests: given prompt X, assert tool sequence Y

## Part 4 — Rollout

- How to canary this fix for 1% of Claude Code users first
- Rollback procedure
- What to communicate in release notes

## Part 5 — Post-incident

Draft a 1-page postmortem template the team can fill in. Include a contributing factors section and action items owner field.

Write real bash/curl commands, real config JSON, and real code for the hardening patch. No stubs.