From 110f87e53ffcfa85a7a129777ab20b23783d9056 Mon Sep 17 00:00:00 2001
From: Bill <bill@bballou.com>
Date: Fri, 2 Jan 2026 13:24:38 -0500
Subject: [PATCH] docs: add logging configuration to README

---
 README.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/README.md b/README.md
index d809dbe..1fc52bc 100644
--- a/README.md
+++ b/README.md
@@ -149,6 +149,7 @@ Add to your MCP client configuration (e.g., Claude Desktop):
 | `PORT` | Server port | `3000` |
 | `GRIST_MCP_TOKEN` | Agent authentication token (required) | - |
 | `CONFIG_PATH` | Path to config file inside container | `/app/config.yaml` |
+| `LOG_LEVEL` | Logging verbosity (`DEBUG`, `INFO`, `WARNING`, `ERROR`) | `INFO` |
 
 ### config.yaml Structure
 
@@ -188,6 +189,55 @@ tokens:
 - `write`: Add, update, delete records
 - `schema`: Create tables, add/modify/delete columns
 
+## Logging
+
+### Configuration
+
+Set the `LOG_LEVEL` environment variable to control logging verbosity:
+
+| Level | Description |
+|-------|-------------|
+| `DEBUG` | Show all logs including HTTP requests and tool arguments |
+| `INFO` | Show tool calls with stats (default) |
+| `WARNING` | Show only auth errors and warnings |
+| `ERROR` | Show only errors |
+
+```bash
+# In .env or docker-compose.yml
+LOG_LEVEL=INFO
+```
+
+### Log Format
+
+At `INFO` level, each tool call produces a single log line:
+
+```
+2026-01-02 10:15:23 | agent-name (abc...xyz) | get_records | sales | 42 records | success | 125ms
+```
+
+| Field | Description |
+|-------|-------------|
+| Timestamp | `YYYY-MM-DD HH:MM:SS` |
+| Agent | Agent name with truncated token |
+| Tool | MCP tool name |
+| Document | Document name (or `-` for list_documents) |
+| Stats | Operation result (e.g., `42 records`, `3 tables`) |
+| Status | `success`, `auth_error`, or `error` |
+| Duration | Execution time in milliseconds |
+
+Errors include details on a second indented line:
+
+```
+2026-01-02 10:15:23 | agent-name (abc...xyz) | add_records | sales | - | error | 89ms
+    Grist API error: Invalid column 'foo'
+```
+
+### Production Recommendations
+
+- Use `LOG_LEVEL=INFO` for normal operation (default)
+- Use `LOG_LEVEL=DEBUG` for troubleshooting (shows HTTP traffic)
+- Use `LOG_LEVEL=WARNING` for minimal logging
+
 ## Security
 
 - **Token-based auth**: Each agent has a unique token with specific document access