@zigrivers/scaffold 3.32.1 → 3.33.1

package/content/knowledge/backend/backend-fintech-broker-integration.md

@@ -1,13 +1,25 @@
 ---
 name: backend-fintech-broker-integration
 description: Multi-broker adapter pattern; credential rotation; error harmonization; rate-limit management; broker-side quirks.
-topics: [backend, fintech, brokers, integration, adapter-pattern, rate-limits, credentials, retry]
+topics:
+  - backend
+  - fintech
+  - brokers
+  - integration
+  - adapter-pattern
+  - rate-limits
+  - credentials
+  - retry
 volatility: evolving
-last-reviewed: null
+last-reviewed: 2025-04-08
 version-pin: null
 sources:
   - url: https://microservices.io/patterns/reliability/circuit-breaker.html
+    hash: sha256:a117f72fc0d279ea99d4234ea8a8cc7bdf23d7ed59d94effc6129d613518a6fa
+    retrieved: 2025-04-08
   - url: https://martinfowler.com/bliki/CircuitBreaker.html
+    hash: sha256:73239948ec03887430a4d139e384e94bc640fec894fb1dce53b56abe579c5da4
+    retrieved: 2025-04-08
 ---
 
 A fintech backend that routes orders or reads positions across more than one broker inherits the union of every broker's quirks, outages, auth schemes, and undocumented behaviors. The broker-integration layer exists to hide that mess behind one normalized internal contract so the rest of the system — risk, order lifecycle, ledger, UI — can stay clean. This doc covers the adapter contract, credential handling, error harmonization, rate-limit strategy, and the specific pitfalls that recur regardless of which brokers you connect.

package/content/knowledge/backend/backend-fintech-compliance.md

@@ -1,15 +1,34 @@
 ---
 name: backend-fintech-compliance
-description: PCI-DSS, SOC 2, SEC/FINRA regulations for consumer/B2B fintech backends; audit trail immutability; data retention; segregation of duties.
-topics: [backend, fintech, compliance, pci-dss, soc2, sec, finra, audit-trail, gdpr]
+description: >-
+  PCI-DSS, SOC 2, SEC/FINRA regulations for consumer/B2B fintech backends; audit trail immutability; data retention;
+  segregation of duties.
+topics:
+  - backend
+  - fintech
+  - compliance
+  - pci-dss
+  - soc2
+  - sec
+  - finra
+  - audit-trail
+  - gdpr
 volatility: evolving
-last-reviewed: null
-version-pin: 'PCI-DSS v4.0.1'
+last-reviewed: 2025-06-01
+version-pin: PCI-DSS v4.0.1
 sources:
   - url: https://www.pcisecuritystandards.org/document_library/
+    hash: sha256:9cb04202115fe2c3275274d93a4eb506c0f97648af0dcee12dc1da0faec0bcbf
+    retrieved: 2025-06-01
   - url: https://www.aicpa-cima.com/topic/audit-assurance
+    hash: sha256:08d2df6fd46adb5e0c62200435b8619d9dd67228ef1c9ce5cbe19e87f048a667
+    retrieved: 2025-06-01
   - url: https://www.finra.org/rules-guidance/rulebooks/finra-rules
+    hash: sha256:0ddd688189c919aeb3903adf06a0a727b515c9a51482c62bf9fdb77f53980e14
+    retrieved: 2025-06-01
   - url: https://eur-lex.europa.eu/eli/reg/2016/679/oj
+    hash: sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
+    retrieved: 2025-06-01
 ---
 
 Fintech compliance is not a checklist applied at the end — it determines schema design, deployment pipelines, and system boundaries. Most regulations apply based on what a service *touches* (cards, trades, PII), so scope reduction is the single highest-leverage design decision available to engineering. This doc covers the regulatory regimes a typical US/EU fintech encounters, the audit-trail patterns they demand, and concrete implementation choices that keep audits survivable.

package/content/knowledge/mcp-server/mcp-authentication.md

@@ -0,0 +1,100 @@
+---
+name: mcp-authentication
+description: MCP authentication patterns — stdio local trust model, OAuth 2.1 for HTTP transports, PKCE, dynamic client registration, API key alternatives, and token validation
+topics: [mcp, authentication, oauth, security, authorization]
+volatility: evolving
+last-reviewed: null
+version-pin: 'MCP spec 2025-11-25; OAuth 2.1 draft-ietf-oauth-v2-1-13'
+sources:
+  - url: https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization
+  - url: https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13
+  - url: https://datatracker.ietf.org/doc/html/rfc7591
+  - url: https://www.rfc-editor.org/rfc/rfc8707.html
+---
+
+Authentication in MCP is transport-dependent. stdio servers rely on OS process isolation (no network auth needed). HTTP servers should use OAuth 2.1 for multi-user or multi-tenant scenarios, or simpler API key patterns for internal/single-tenant deployments.
+
+## Summary
+
+**stdio transport**: no network authentication — the server inherits credentials from environment variables and the OS controls process access. **Streamable HTTP transport**: use OAuth 2.1 (per spec) for public or multi-user servers. OAuth flow: client hits protected resource, gets 401 with `WWW-Authenticate`, discovers authorization server via OAuth Protected Resource Metadata, completes OAuth 2.1 with PKCE, presents `Bearer` token on all subsequent requests. For simpler deployments, API keys in headers or environment-injected tokens are practical alternatives. The spec mandates `MCP-Protocol-Version` on HTTP requests and audience validation on tokens.
+
+## Deep Guidance
+
+### stdio: local trust model
+
+The stdio transport requires no network authentication. Trust is established by OS-level process ownership: the client spawns the server as a subprocess, which means both run under the same user account. The server process inherits environment variables from the parent, which is the standard mechanism for passing API keys, database credentials, or access tokens to a local MCP server:
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "npx",
+      "args": ["my-mcp-server"],
+      "env": {
+        "DATABASE_URL": "postgresql://localhost/mydb",
+        "API_KEY": "sk-..."
+      }
+    }
+  }
+}
+```
+
+The spec is explicit: implementations using stdio SHOULD NOT follow the OAuth specification and SHOULD instead retrieve credentials from the environment. Do not add HTTP authentication middleware to a stdio server.
+
+### OAuth 2.1 for HTTP transports
+
+For Streamable HTTP servers accessible over a network, the spec defines an OAuth 2.1 authorization flow. The server acts as an OAuth 2.1 **resource server**; a separate authorization server handles token issuance.
+
+**Discovery flow (updated in 2025-11-25 per RFC 9728 and OIDC Discovery 1.0):**
+1. Client sends an unauthenticated MCP request.
+2. Server MAY respond `401 Unauthorized` with a `WWW-Authenticate` header pointing to the resource server metadata URL; however, the `WWW-Authenticate` header is now OPTIONAL — clients MUST fall back to fetching `/.well-known/oauth-protected-resource` directly if no header is present.
+3. Client fetches `/.well-known/oauth-protected-resource` (RFC 9728) to get the authorization server URL.
+4. Client fetches the authorization server's metadata. Authorization servers that support OpenID Connect SHOULD publish an OIDC Discovery document (`/.well-known/openid-configuration`) in addition to `/.well-known/oauth-authorization-server`.
+5. Client completes the OAuth 2.1 authorization code flow with PKCE. Clients SHOULD use OAuth Client ID Metadata Documents (a recommended client registration mechanism in 2025-11-25) where supported by the authorization server.
+6. Client presents `Authorization: Bearer <token>` on all subsequent requests. Servers MAY issue incremental scope consent via the `WWW-Authenticate` header on subsequent `403` responses.
+
+**PKCE is mandatory** for public clients (MCP clients cannot keep secrets). The authorization server MUST support PKCE. The client generates a `code_verifier` (random string), hashes it to `code_challenge`, includes the challenge in the authorization request, and presents the verifier in the token request.
+
+**Resource parameter** (RFC 8707): clients MUST include a `resource` parameter in both authorization and token requests identifying the MCP server's canonical URI (e.g., `https://mcp.example.com`). This binds tokens to their intended audience and prevents cross-service token reuse.
+
+### Token validation requirements
+
+MCP servers MUST validate every incoming access token:
+- Verify the token is valid and not expired.
+- Verify the token's audience claim identifies this server (matches the server's canonical URI).
+- Reject tokens with `401` if invalid or expired; `403` if the token is valid but lacks required scope.
+
+NEVER accept tokens issued for a different resource. NEVER forward a received token to an upstream API — issue a separate token for each upstream call. Token passthrough is explicitly forbidden by the spec and creates confused deputy vulnerabilities.
+
+### Dynamic client registration
+
+Authorization servers and clients SHOULD support OAuth 2.0 Dynamic Client Registration (RFC 7591). As of 2025-11-25, OAuth Client ID Metadata Documents are the recommended client registration mechanism — they allow clients to declare their identity via a URL rather than requiring a registration round-trip. Without dynamic registration support, MCP clients must be pre-registered with every authorization server, which creates friction for discovering and connecting to new servers. Dynamic registration lets a client auto-register on first connection:
+
+```
+POST /register
+{ "client_name": "Claude Desktop", "redirect_uris": ["http://localhost:57842/callback"] }
+→ { "client_id": "abc123", ... }
+```
+
+If the authorization server does not support dynamic registration, the client must hardcode a client ID or present a UI for manual credential entry.
+
+### Simpler alternatives for private/internal deployments
+
+For servers used only within a controlled environment (team tool, internal service), full OAuth is often unnecessary overhead. Practical alternatives:
+
+**API key in header**: The client includes a static API key in a custom header or as a Bearer token. The server validates it against a stored secret. Simple, easy to rotate, no token exchange flow.
+
+**Mutual TLS**: Suitable for service-to-service scenarios where both sides have certificates. The TLS handshake authenticates both parties.
+
+**Reverse proxy with auth**: Run the MCP server behind nginx/Caddy/Cloudflare with authentication handled at the proxy layer. The server itself trusts all proxied connections.
+
+**Network isolation**: For truly internal deployments, rely on network controls (VPN, private subnet, firewall rules) and skip application-layer auth. Acceptable only when the network boundary is the full security boundary.
+
+### Security hardening checklist
+
+- Validate the `Origin` header on all Streamable HTTP connections to prevent DNS rebinding attacks.
+- Use HTTPS for all HTTP transport connections (required by OAuth 2.1 for authorization server endpoints and redirect URIs).
+- Bind local HTTP servers to 127.0.0.1, not 0.0.0.0.
+- Rotate API keys and tokens regularly; issue short-lived access tokens.
+- Log all authentication failures with enough context to diagnose attacks.
+- Do not embed credentials in resource URIs (they appear in logs and referrer headers).

package/content/knowledge/mcp-server/mcp-deployment-patterns.md

@@ -0,0 +1,119 @@
+---
+name: mcp-deployment-patterns
+description: MCP server deployment — local stdio subprocess, hosted container/serverless, lifecycle management, environment config, and operational patterns for each deployment model
+topics: [mcp, deployment, stdio, container, serverless, operations]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://modelcontextprotocol.io/specification/2025-11-25/basic/transports
+  - url: https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle
+  - url: https://modelcontextprotocol.io/docs/develop/connect-local-servers
+---
+
+MCP server deployment splits into two fundamentally different models: local subprocess (stdio) installed on the user's machine, and hosted service (container or serverless) running independently. Each has different lifecycle, configuration, update, and security characteristics.
+
+## Summary
+
+**Local stdio deployment**: server is installed as a CLI tool (npm package, Python package, binary) and launched as a subprocess by the client. Configuration lives in the client's server registry (e.g., `claude_desktop_config.json`). Updates require reinstalling the package. Lifecycle is tied to the client process. **Hosted deployment**: server runs as a persistent HTTP service, deployed to a container host or serverless platform. Clients connect via Streamable HTTP. Supports multiple concurrent users, centralized updates, and independent scaling. Use `stdio` for local developer tools; use hosted deployment for shared team/organization servers.
+
+## Deep Guidance
+
+### Local stdio deployment
+
+The stdio model packages the MCP server as an installable CLI tool. The user installs it once; each MCP client registers it in its server configuration:
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/alice/projects"],
+      "env": {
+        "NODE_ENV": "production"
+      }
+    },
+    "mydb": {
+      "command": "uvx",
+      "args": ["mcp-server-postgres"],
+      "env": {
+        "DATABASE_URL": "postgresql://localhost/mydb"
+      }
+    }
+  }
+}
+```
+
+**Package distribution**: Publish to npm (`npx`-runnable) for TypeScript/Node.js servers; publish to PyPI (`uvx`-runnable) for Python servers. `npx -y` and `uvx` auto-install on first run, minimizing setup friction. For compiled binaries (Go, Rust), distribute via Homebrew, Winget, or direct download.
+
+**Configuration**: Pass per-installation config via `env` (preferred) or `args`. Avoid config files with relative paths — the working directory is undefined when launched by a client (it could be `/` or the client's install directory). Always use absolute paths for any file references.
+
+**Credentials**: Pass API keys and secrets via `env`, never via `args` (args appear in process listings). The client's server configuration file must be protected with appropriate file permissions.
+
+**Lifecycle**: The client spawns the server on first use and keeps the process alive while connected. On shutdown, the client closes stdin and waits for the server to exit. Implement a clean shutdown handler: flush any pending state, close database connections, release file locks. In Node.js: listen for `SIGTERM`. In Python: implement `atexit` handlers or use FastMCP's lifecycle hooks. The server MUST exit cleanly after stdin is closed — a server that hangs will be forcibly killed.
+
+**Updates**: Users update by reinstalling (`npm update -g my-server`, `uv tool upgrade my-server`). Pin your client in the MCP server registry to exact versions for stability-critical tools; use range specifiers for tools that benefit from automatic minor updates.
+
+### Hosted container deployment
+
+Containerized MCP servers run as long-lived HTTP services behind a container orchestrator (Docker Compose, Kubernetes, ECS, Cloud Run):
+
+```dockerfile
+FROM node:22-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --production
+COPY dist/ ./dist/
+EXPOSE 3000
+CMD ["node", "dist/index.js"]
+```
+
+The server uses the Streamable HTTP transport:
+```typescript
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
+import express from 'express'
+
+const app = express()
+app.use(express.json())
+
+const transport = new StreamableHTTPServerTransport({ endpoint: '/mcp' })
+await server.connect(transport)
+
+app.all('/mcp', (req, res) => transport.handle(req, res))
+app.listen(3000)
+```
+
+**Health checks**: expose a `/health` or `/ping` endpoint that returns 200 when the server is ready. Container orchestrators use this to route traffic only to healthy instances.
+
+**Configuration**: inject secrets via environment variables (Kubernetes Secrets, AWS Parameter Store, Vault). Never bake credentials into container images.
+
+**Graceful shutdown**: listen for `SIGTERM` (sent by orchestrators before `SIGKILL`). Drain in-flight requests, close upstream connections, then exit. Typical drain window: 10–30 seconds.
+
+### Serverless deployment
+
+Serverless (AWS Lambda, Google Cloud Functions, Vercel Edge) works for stateless MCP servers using Streamable HTTP. The primary constraint: serverless functions are stateless across invocations, so session state must be stored externally (Redis, DynamoDB) if you support `Mcp-Session-Id`.
+
+For fully stateless servers (each request is independent, no subscriptions, no session-dependent state), serverless works well:
+- Keep cold start time under 1 second (avoid large imports, use lazy initialization).
+- Set function timeout generously (MCP tool calls that invoke slow APIs may need 30+ seconds).
+- Disable or carefully manage resource subscriptions — subscription state cannot survive function restarts without external storage.
+
+### Multi-user stdio: local multiplexing
+
+Some deployment environments need multiple users to share a single MCP server installation without a hosted service. Options:
+- **Per-user install**: each user installs and configures the server independently. Simplest, most isolated.
+- **System-wide daemon**: run the MCP server as a system service over a Unix domain socket, with per-user authentication at the socket level. Complex but enables centralized configuration and single-instance resource use.
+
+For most teams, a hosted HTTP deployment is simpler than system-level socket multiplexing.
+
+### Choosing deployment model
+
+| Requirement | Recommended model |
+|-------------|------------------|
+| Local file access (user's files) | Local stdio |
+| Developer CLI wrapper | Local stdio |
+| Shared team knowledge base | Hosted container |
+| SaaS integration (multi-tenant) | Hosted container or serverless |
+| Real-time resource subscriptions | Hosted container (stateful) |
+| Zero-infrastructure setup | Local stdio |
+| SOC2/compliance audit trail | Hosted container |

package/content/knowledge/mcp-server/mcp-error-handling.md

@@ -0,0 +1,131 @@
+---
+name: mcp-error-handling
+description: MCP protocol errors (JSON-RPC error codes) vs tool execution errors (isError content), partial failures, error message design, and client recovery patterns
+topics: [mcp, error-handling, json-rpc, tool-errors, protocol-errors]
+volatility: evolving
+last-reviewed: null
+version-pin: 'MCP spec 2025-11-25'
+sources:
+  - url: https://modelcontextprotocol.io/specification/2025-11-25/server/tools
+  - url: https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle
+  - url: https://www.jsonrpc.org/specification
+---
+
+MCP has two distinct error channels. Mixing them up is one of the most common MCP server bugs: using protocol errors for domain failures causes the LLM to lose context about what went wrong; using isError for protocol failures breaks client error-handling logic.
+
+## Summary
+
+**Protocol errors** (JSON-RPC error responses) signal that a request could not be processed at all — unknown method, invalid parameters, server crash. Use standard JSON-RPC error codes. **Tool execution errors** (`isError: true` in the tool result) signal that the tool ran but the operation failed — API error, resource not found, business logic rejection. The LLM can read and react to tool errors; it cannot generally recover from protocol errors. Always prefer `isError: true` for domain-level failures that a well-behaved caller might encounter.
+
+## Deep Guidance
+
+### Protocol errors: JSON-RPC error responses
+
+A protocol error is a JSON-RPC error response object. It replaces the `result` field entirely:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "error": {
+    "code": -32602,
+    "message": "Unknown tool: invalid_tool_name"
+  }
+}
+```
+
+Use protocol errors for:
+- **Method not found** (`-32601`): the client called a method the server does not implement.
+- **Invalid params** (`-32602`): structural/wire-level request problems that prevent dispatch entirely — unknown tool name in `tools/call`, unknown method, missing required prompt arguments to `prompts/get`, invalid resource URI in `resources/read`, malformed params shape at the JSON-RPC level. **Do NOT use `-32602` for a tool that dispatched successfully but whose arguments fail the tool's own `inputSchema` or business validation** — those are tool execution errors (see `isError` below).
+- **Internal error** (`-32603`): unhandled exception or server bug. Include enough detail in `message` to diagnose, but sanitize sensitive data.
+- **Parse error** (`-32700`): malformed JSON received. The SDK handles this automatically.
+- **Invalid request** (`-32600`): request is not valid JSON-RPC 2.0 structure. Also SDK-handled.
+
+Custom server-defined error codes MUST be in the JSON-RPC server-error range `-32099` to `-32000` (most-negative to least-negative). Standard resource error code: `-32002` (resource not found).
+
+The `error` object MAY include a `data` field with additional structured context:
+```json
+{
+  "code": -32602,
+  "message": "Missing required argument",
+  "data": { "argument": "location", "required": true }
+}
+```
+
+### Tool execution errors: isError
+
+When a tool runs but the operation it performs fails, return the failure as a normal result with `isError: true`:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 4,
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "Failed to fetch weather data: API returned 429 Too Many Requests. Rate limit resets at 14:00 UTC. Suggest retrying after that time."
+      }
+    ],
+    "isError": true
+  }
+}
+```
+
+Use `isError: true` for:
+- **Tool input/schema validation failures** — when a tool dispatches but its arguments fail the tool's own `inputSchema` or business validation rules (wrong value, out-of-range number, unsupported enum value, failed cross-field constraint). Per SEP-1303 (2025-11-25), these MUST be `isError: true` so the model can self-correct, NOT `-32602`.
+- External API failures (HTTP 4xx/5xx from downstream services)
+- Resource not found in a domain sense (file doesn't exist at the path the user specified)
+- Business logic rejections (insufficient permissions in the target system, invalid state for the operation)
+- Network timeouts when calling downstream services
+- Partial failures where the overall result is a failure
+
+**Why this distinction matters**: when `isError: true`, the result is a successful JSON-RPC response — the protocol layer worked correctly. The LLM receives the content and can read the error message, decide to retry with different parameters, inform the user, or take an alternative approach. Protocol errors, on the other hand, are invisible to the LLM in most client implementations — they're handled at the transport/client layer. The 2025-11-25 spec revision (SEP-1303) explicitly directs that tool input validation errors MUST be returned as Tool Execution Errors (`isError: true`) rather than Protocol Errors (`-32602`), specifically to enable model self-correction. This applies to any argument that dispatches to a real tool but fails schema/business validation once there.
+
+### Error message quality
+
+Both protocol error messages and `isError` content messages are read by either developers (protocol errors) or LLMs (isError). Write them to be actionable:
+
+**For isError messages** (LLM-readable):
+- State what failed specifically, not just "an error occurred".
+- Include any relevant IDs, timestamps, or context the LLM can use.
+- Suggest what to do next when recovery is possible.
+- Include rate limit reset times, retry suggestions, or alternative approaches.
+
+**For protocol error messages** (developer-readable):
+- Name the specific field or method that caused the error.
+- Quote the invalid value or describe the expected format.
+- Avoid exposing internal file paths, stack traces, or secrets.
+
+### Partial failures in multi-item operations
+
+When a tool processes multiple items and some succeed while others fail:
+
+**Option A (partial success)**: Return successful results and error descriptions in the `content` array, without setting `isError: true`. Use this when partial output is useful:
+```json
+{
+  "content": [
+    { "type": "text", "text": "Processed 3 of 5 items:\n✓ item1: success\n✓ item2: success\n✗ item3: rate limited\n✓ item4: success\n✗ item5: not found" }
+  ]
+}
+```
+
+**Option B (total failure)**: If no items succeeded or the partial result is not useful, set `isError: true` and describe the failure.
+
+Never silently drop failures — always include what failed and why, even in partial success responses.
+
+### Initialization and lifecycle errors
+
+During the `initialize` handshake, return a protocol error if:
+- The client requests a protocol version the server does not support (respond with your supported version per spec, or error if incompatible).
+- Required capabilities cannot be negotiated.
+
+After initialization, if a client calls a method whose capability was not declared (e.g., calls `tools/list` but the server did not declare `tools` capability), return `-32601` (method not found) or `-32602` (invalid params) to indicate the feature is not available.
+
+### Client-side recovery patterns
+
+MCP clients should handle these error patterns from servers:
+- **Protocol error on tool call**: log the error, surface to user if relevant, do not retry automatically (likely a programming error).
+- **`isError: true` on tool result**: pass the error content to the LLM — it can decide whether to retry, use a different tool, or report to the user.
+- **Server disconnect / connection reset**: attempt reconnection and re-run the `initialize` handshake before resuming operations. Do not silently drop in-flight requests.
+- **`notifications/tools/list_changed`**: re-issue `tools/list` before the next tool call to ensure the cached tool list is current.

package/content/knowledge/mcp-server/mcp-observability.md

@@ -0,0 +1,125 @@
+---
+name: mcp-observability
+description: MCP server structured logging, stderr discipline for stdio transport, log message notifications, request tracing, debugging with MCP Inspector, and performance monitoring
+topics: [mcp, observability, logging, tracing, debugging, monitoring]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://modelcontextprotocol.io/docs/tools/debugging
+  - url: https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/logging
+---
+
+Good observability in an MCP server means you can diagnose problems without attaching a debugger. The fundamental constraint is the stdio transport's stdout-is-protocol-only rule, which makes naive logging dangerous. Structured logging to the right channel is non-negotiable.
+
+## Summary
+
+For **stdio servers**, write all logging to **stderr** — stdout is reserved exclusively for JSON-RPC protocol messages. Any stray write to stdout corrupts the protocol stream. For **HTTP servers**, use standard structured logging to files, stdout, or an aggregator — stderr is not captured by clients. MCP also provides a protocol-level logging mechanism via `notifications/message` (usable on any transport). Always include a correlation ID per request. Use the MCP Inspector as your first debugging tool.
+
+## Deep Guidance
+
+### Stderr discipline for stdio transport
+
+The stdio transport reserves stdout entirely for JSON-RPC protocol messages. Even a single line of non-JSON output to stdout — a startup banner, a debug print, a library that logs to stdout by default — will corrupt the message stream and cause parse errors in the client. This is the most common cause of "MCP server not responding" problems.
+
+**TypeScript/Node.js**: use `process.stderr.write(...)` or a logging library configured to stderr:
+```typescript
+import { createWriteStream } from 'node:fs'
+// write to stderr or a log file — never process.stdout
+const log = (msg: string) => process.stderr.write(`[server] ${msg}\n`)
+```
+
+**Python**: use `print(..., file=sys.stderr)` or configure `logging` to use stderr:
+```python
+import logging, sys
+logging.basicConfig(
+    level=logging.INFO,
+    stream=sys.stderr,  # critical: must be stderr, not stdout
+    format='%(asctime)s %(levelname)s %(name)s: %(message)s'
+)
+```
+
+The Python SDK's FastMCP does this correctly by default. Watch for third-party libraries that configure their own logging handlers pointing at stdout.
+
+**Go**: `log.Println` writes to stderr by default — safe for stdio servers. Avoid `fmt.Println` which goes to stdout.
+
+### MCP protocol-level logging (all transports)
+
+For any transport, the server can send log messages to the client via the `notifications/message` notification. The server must declare `logging: {}` in its capabilities during initialization.
+
+Log levels follow RFC 5424: `debug`, `info`, `notice`, `warning`, `error`, `critical`, `alert`, `emergency`. Clients can set the minimum level via `logging/setLevel`.
+
+TypeScript SDK:
+```typescript
+await server.sendLoggingMessage({ level: 'info', data: 'Tool execution started', logger: 'weather-tool' })
+```
+
+Python FastMCP:
+```python
+await ctx.session.send_log_message(level="info", data="Processing request", logger="my-server")
+```
+
+Protocol-level logging is visible to the MCP client (and to the Inspector's Notifications pane), making it useful for surfacing server state to the host application without relying on stderr capture.
+
+### Structured logging format
+
+Use structured logs (JSON or key=value) rather than unstructured strings. Include:
+- `timestamp`: ISO 8601 or epoch milliseconds
+- `level`: debug/info/warning/error
+- `request_id` or `correlation_id`: unique per MCP request (use the JSON-RPC `id` field value)
+- `method`: the JSON-RPC method being handled
+- `tool_name` / `resource_uri` / `prompt_name`: the specific capability invoked
+- `duration_ms`: time taken (for completed requests)
+- `error`: error type and message (for failures)
+
+Example structured log entry:
+```json
+{
+  "timestamp": "2025-06-18T14:32:01.234Z",
+  "level": "info",
+  "request_id": "42",
+  "method": "tools/call",
+  "tool_name": "get_weather",
+  "duration_ms": 234,
+  "location": "New York"
+}
+```
+
+### Request tracing
+
+Assign a correlation ID to each incoming MCP request using the JSON-RPC `id` field (for requests) or a generated UUID (for notifications). Thread this ID through all log entries, downstream API calls, and database queries generated by that request. This makes it possible to reconstruct the full execution path for a single tool call when debugging a failure.
+
+For HTTP transport, also include the `Mcp-Session-Id` in logs to correlate all requests within a session.
+
+### Debugging with MCP Inspector
+
+The MCP Inspector is the most effective debugging tool for local development:
+
+```bash
+# Launch your server with the Inspector
+npx @modelcontextprotocol/inspector node dist/server.js
+```
+
+Inspector debugging workflow:
+1. Check the Notifications pane for server log messages and error notifications.
+2. Invoke a failing tool and inspect the raw request/response in the tool result pane.
+3. Verify capability negotiation — check that the capabilities shown in the Inspector match what your server declares.
+4. Test error paths explicitly: call tools with invalid inputs and verify `isError: true` responses display correctly.
+
+For Claude Desktop specifically, tail the MCP log files:
+```bash
+# macOS
+tail -F ~/Library/Logs/Claude/mcp*.log
+```
+
+### Performance monitoring
+
+Log operation timing for all tool calls and resource reads. Track:
+- **p50/p95/p99 latency** per tool: identify slow tools before users complain.
+- **Error rate** per tool: high error rates indicate API instability or logic bugs.
+- **Payload size**: large tool results consume LLM context; log result byte sizes to catch runaway responses.
+- **Downstream API latency**: separately log time spent waiting for external APIs vs. server-side processing.
+
+For HTTP-transport servers, standard HTTP middleware (Morgan, Express's req timing) captures request-level metrics. For stdio servers, implement timing within each tool handler and write to stderr/log file.
+
+Set alerts on: error rate above 5%, tool latency p99 above 5 seconds, and any `SIGTERM` not followed by clean exit within 30 seconds (hung shutdown).