From 4223530f3551f8ee17740a38b93afe2681697559 Mon Sep 17 00:00:00 2001 From: "molecule-ai[bot]" <276602405+molecule-ai[bot]@users.noreply.github.com> Date: Wed, 22 Apr 2026 23:57:30 +0000 Subject: [PATCH] docs(mcp-server): add LOG_LEVEL env var + structured pino logging section (#78) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Pair PR: molecule-mcp-server#6 - Adds LOG_LEVEL to Environment Variables table (pino log levels: trace→fatal) - Adds Structured Logging section explaining AsyncLocalStorage context, JSON output in production, pretty-print in dev - Adds troubleshooting row for high-volume log output - Links to molecule-mcp-server#6 for implementation details Co-authored-by: Molecule AI Documentation Specialist --- content/docs/guides/mcp-server-setup.md | 27 +++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/content/docs/guides/mcp-server-setup.md b/content/docs/guides/mcp-server-setup.md index a270e67..215304b 100644 --- a/content/docs/guides/mcp-server-setup.md +++ b/content/docs/guides/mcp-server-setup.md @@ -53,6 +53,32 @@ list_workspaces | Variable | Default | Description | |----------|---------|-------------| | `MOLECULE_URL` | `http://localhost:8080` | Platform API URL | +| `LOG_LEVEL` | `info` | Log level — `trace`, `debug`, `info`, `warn`, `error`, `fatal` (pino numeric levels: 10–60) | + +## Structured Logging + +The MCP server emits structured JSON logs via [pino](https://github.com/pinojs/pino). Each log entry includes `level`, `time`, `pid`, `hostname`, `msg`, and any extra fields passed as context. + +When `NODE_ENV != "production"`, logs are pretty-printed for human readability. In production the output is machine-parseable JSON. + +Every log entry automatically includes MCP request context (tool name, request ID, workspace ID) when called from within a tool handler: + +```json +{ + "level": 30, + "time": "2026-04-22T18:30:00.000Z", + "pid": 1234, + "hostname": "workspace-server", + "msg": "rate limit hit", + "tool": "list_workspaces", + "requestId": "req_abc123", + "workspaceId": "ws_xyz789" +} +``` + +Set `LOG_LEVEL=debug` (level 20) to trace all tool calls and request IDs. Set `LOG_LEVEL=error` (level 50) in CI to suppress informational output. + +See [`molecule-mcp-server` PR #6](https://github.com/Molecule-AI/molecule-mcp-server/pull/6) for implementation details. ## Tool Reference @@ -248,3 +274,4 @@ The MCP server handles auth automatically when configured with the correct `MOLE | "401 Unauthorized" | Token expired or revoked — create a new one | | Tools not showing | Run `npx @molecule-ai/mcp-server` standalone to check for errors | | Stale data | MCP server doesn't cache — check platform directly | +| High-volume log output | Set `LOG_LEVEL=error` to suppress info/warn; in production, log output is JSON (machine-parseable) |