lazy-mcp 2.5.0 → 2.6.6

package/README.md

@@ -14,28 +14,14 @@ A client-agnostic proxy that converts normal MCP servers to use a lazy-loading p
   - [Known Issue](#known-issue)
   - [Installation](#installation)
   - [Usage](#usage)
+    - [Config directory location (XDG Base Directory)](#config-directory-location-xdg-base-directory)
     - [Streamable HTTP Transport](#streamable-http-transport)
   - [Integration (Claude Desktop, OpenCode, Cursor, VS Code, and more)](#integration-claude-desktop-opencode-cursor-vs-code-and-more)
   - [Example](#example)
   - [Development](#development)
     - [Running from Local Source](#running-from-local-source)
   - [Releases](#releases)
-    - [How It Works](#how-it-works)
-    - [Required CI/CD Variables](#required-cicd-variables)
-      - [`GITLAB_RELEASE_TOKEN`](#gitlabreleasetoken)
-      - [`NPM_TOKEN`](#npmtoken)
-      - [`PYPI_TOKEN`](#pypitoken)
-      - [`CARGO_TOKEN`](#cargotoken)
   - [Configuration Reference](#configuration-reference)
-    - [Server Configuration Fields](#server-configuration-fields)
-    - [OAuth 2.0 Authentication](#oauth-20-authentication)
-    - [Command Format](#command-format)
-    - [Environment Variables](#environment-variables)
-    - [Embed Server Summaries](#embed-server-summaries)
-    - [Transport Configuration](#transport-configuration)
-    - [Logging Configuration](#logging-configuration)
-    - [Health Monitoring](#health-monitoring)
-    - [Config Reload (SIGHUP)](#config-reload-sighup)
   - [Benefits](#benefits)
   - [Documentation](#documentation)
 <!-- TOC_END -->
@@ -200,104 +186,43 @@ LAZY_MCP_CONFIG=~/.config/lazy-mcp/servers.json npx lazy-mcp@latest
 lazy-mcp --config ~/.config/lazy-mcp/servers.json
 ```
 
-### Streamable HTTP Transport
+### Config directory location (XDG Base Directory)
 
-By default, lazy-mcp communicates over **stdio** (standard MCP transport). You can also run it as an **HTTP server** using the Streamable HTTP transport, allowing remote clients to connect over the network:
+The config directory defaults to `~/.config/lazy-mcp/`, but lazy-mcp honours the
+[XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html):
+if `$XDG_CONFIG_HOME` is set, lazy-mcp uses `$XDG_CONFIG_HOME/lazy-mcp/`
+instead. This applies to:
 
-**Via config file** — add a `transport` block to `servers.json`:
+- the default `servers.json` location,
+- the OAuth token store (`tokens.json`, `client-info.json`, …),
+- the OAuth callback PID lock files.
 
-```json
-{
-  "servers": [
-    { "name": "my-server", "description": "My MCP server", "command": ["python", "server.py"] }
-  ],
-  "transport": {
-    "type": "http",
-    "port": 3000,
-    "host": "localhost",
-    "path": "/mcp",
-    "authToken": "${MY_API_KEY}"
-  }
-}
-```
-
-**Via CLI flags** (override config values):
+This makes it easy to scope tokens per project (e.g. via `direnv` or `mise`)
+without having to override `$HOME`:
 
 ```bash
-# Start HTTP server on port 3000
-lazy-mcp --config servers.json --transport http --port 3000
-
-# With custom host, path, and auth
-lazy-mcp --config servers.json --transport http --port 3000 --host 127.0.0.1 --path /mcp --auth-token "my-secret"
+# In a project's .envrc / mise.toml:
+export XDG_CONFIG_HOME="$PWD/.config"
 ```
 
-**Security note:** `--host 0.0.0.0` exposes the HTTP server on all network interfaces. Use it only inside Docker or trusted networks.
-
-> **Reverse proxy note:** The default Origin check uses the scheme visible to
-> lazy-mcp's own socket plus the incoming `Host` header. If you run lazy-mcp
-> behind a TLS-terminating reverse proxy, the backend hop is usually plain
-> HTTP, so the implicit same-origin shortcut may reject public HTTPS origins.
-> In that setup, configure `transport.allowedOrigins` explicitly. If your
-> proxy preserves the public `Host` header, configure `transport.allowedHosts`
-> too.
->
-> Example:
-> ```json
-> {
->   "transport": {
->     "type": "http",
->     "host": "127.0.0.1",
->     "port": 8080,
->     "path": "/mcp",
->     "allowedHosts": ["mcp.example.com"],
->     "allowedOrigins": ["https://mcp.example.com"]
->   }
-> }
-> ```
->
-> lazy-mcp intentionally does not trust `Forwarded` / `X-Forwarded-*` headers
-> by default. If proxy-aware origin reconstruction is ever added, it should be
-> behind an explicit trusted-proxy setting.
-
-**Via environment variables** (lowest precedence):
-
-```bash
-LAZY_MCP_TRANSPORT=http LAZY_MCP_PORT=3000 LAZY_MCP_AUTH_TOKEN=my-secret lazy-mcp
-```
+With that set, lazy-mcp will read `./.config/lazy-mcp/servers.json` and store
+tokens under `./.config/lazy-mcp/` — completely isolated from your global
+lazy-mcp state.
 
-**Precedence**: CLI flags > config file > environment variables > defaults.
+### Streamable HTTP Transport
 
-Once running, clients connect as a remote MCP server:
+By default, lazy-mcp communicates over **stdio**. You can also run it as an **HTTP server** so remote clients can connect over the network:
 
 ```bash
-# Quick test with curl
-curl -X POST http://localhost:3000/mcp \
-  -H "Content-Type: application/json" \
-  -H "Accept: application/json, text/event-stream" \
-  -H "Authorization: Bearer ${MY_API_KEY}" \
-  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
+lazy-mcp --config servers.json --transport http --port 3000 --auth-token "my-secret"
 ```
 
-> **Note**: Server-initiated notifications via GET/SSE are not supported in stateless mode. Use POST for all requests.
+See [doc/HTTP_TRANSPORT.md](./doc/HTTP_TRANSPORT.md) for full configuration, security guidance (DNS rebinding protection, payload limits, bearer auth), and reverse-proxy setup.
 
 ## Integration (Claude Desktop, OpenCode, Cursor, VS Code, and more)
 
-Replace multiple MCP server entries with one aggregated proxy:
+Replace multiple MCP server entries in your client with one aggregated lazy-mcp proxy:
 
-**Before** (5 separate MCP servers):
-```json
-{
-  "mcp": {
-    "chrome-devtools": { "command": ["npx", "lazy-mcp@latest", "npx", "-y", "chrome-devtools-mcp@latest"] },
-    "gitlab": { "command": ["npx", "lazy-mcp@latest", "npx", "mcp-remote@latest", "https://..."] },
-    "grepai": { "command": ["npx", "lazy-mcp@latest", "grepai", "mcp-serve"] },
-    "context7": { "command": ["npx", "-y", "@upstash/context7-mcp"] },
-    "perplexity": { "command": ["npx", "-y", "@perplexity-ai/mcp-server"] }
-  }
-}
-```
-
-**After** (Consolidated into 1 multi-server proxy):
 ```json
 {
   "mcp": {
@@ -310,38 +235,9 @@ Replace multiple MCP server entries with one aggregated proxy:
 }
 ```
 
-**HTTP mode** — for clients that support remote MCP servers:
-
-Start lazy-mcp in HTTP mode (e.g. `lazy-mcp --config servers.json --transport http --port 3000`), then configure your client:
-
-```json
-{
-  "mcp": {
-    "lazy-mcp": {
-      "type": "remote",
-      "url": "http://localhost:3000/mcp",
-      "headers": {
-        "Authorization": "Bearer ${LAZY_MCP_AUTH_TOKEN}"
-      }
-    }
-  }
-}
-```
-
-Where `~/.config/lazy-mcp/servers.json` contains all 5 servers:
-```json
-{
-  "servers": [
-    { "name": "chrome-devtools", "description": "Chrome DevTools automation", "command": ["npx", "-y", "chrome-devtools-mcp@latest"] },
-    { "name": "gitlab", "description": "GitLab API integration", "command": ["npx", "mcp-remote@latest", "https://..."] },
-    { "name": "grepai", "description": "Search codebase", "command": ["grepai", "mcp-serve"] },
-    { "name": "context7", "description": "Library documentation", "command": ["npx", "-y", "@upstash/context7-mcp"] },
-    { "name": "perplexity", "description": "Web search", "command": ["npx", "-y", "@perplexity-ai/mcp-server"] }
-  ]
-}
-```
+All downstream MCP servers live in `~/.config/lazy-mcp/servers.json`. **Result**: ~90% context reduction (from ~16K to ~1.5K tokens initially).
 
-**Result**: ~90% context reduction (from ~16K to ~1.5K tokens initially)
+See [doc/INTEGRATION.md](./doc/INTEGRATION.md) for before/after examples and HTTP-mode client configuration.
 
 ## Example
 
@@ -408,384 +304,29 @@ Or with `ts-node` (no build needed, always reflects latest source):
 
 ## Releases
 
-Releases are fully automated via [semantic-release](https://semantic-release.gitbook.io/) on every push to `main`.
-
-### How It Works
-
-1. CI analyzes all commits since the last tag using [Conventional Commits](https://www.conventionalcommits.org/)
-2. Determines the next version (`feat` → minor bump, `fix`/`perf`/`chore`/`refactor`/`test` → patch bump)
-3. Updates `package.json`, `CHANGELOG.md`, `VERSION`, and `RELEASE_NOTES.md`
-4. Commits those files as `chore(release): X.Y.Z` and pushes a `vX.Y.Z` tag
-5. Creates a GitLab Release with the generated release notes
-6. The `vX.Y.Z` tag triggers a separate pipeline that publishes the package to npm automatically
-
-No manual version bumping or tagging needed — just merge to `main` with conventional commit messages.
-
-### Required CI/CD Variables
-
-Four CI/CD variables must be configured (GitLab → Project → Settings → CI/CD → Variables):
+Releases are fully automated via [semantic-release](https://semantic-release.gitbook.io/) on every push to `main`. CI analyzes [Conventional Commits](https://www.conventionalcommits.org/), bumps the version, tags, and publishes to npm, PyPI, and crates.io.
 
-| Variable | Description |
-|----------|-------------|
-| `GITLAB_RELEASE_TOKEN` | Project access token — pushes the release commit + tag to `main` and creates the GitLab Release |
-| `NPM_TOKEN` | npm automation token — publishes the package to the npm registry on tag pipelines |
-| `PYPI_TOKEN` | PyPI API token — publishes the package to PyPI on tag pipelines |
-| `CARGO_TOKEN` | crates.io API token — publishes the crate to crates.io on tag pipelines |
-
-#### `GITLAB_RELEASE_TOKEN`
-
-**Creating the token** (GitLab → Project → Settings → Access Tokens):
-
-| Setting | Value |
-|---------|-------|
-| Token name | `semantic-release-bot` (or any name) |
-| Role | **Developer** (push to a protected branch should be configured separately) |
-| Scopes | `api`, `write_repository` |
-
-**Adding the variable:**
-
-| Setting | Value |
-|---------|-------|
-| Key | `GITLAB_RELEASE_TOKEN` |
-| Masked | ✅ Yes |
-| Protected | ❌ No (must be available on the unprotected `main` pipeline) |
-
-> **Note**: If `main` is a protected branch with push restrictions, the token's bot user must be added to the "Allowed to push" list under GitLab → Project → Settings → Repository → Protected branches.
-
-#### `NPM_TOKEN`
-
-**Creating the token** (npmjs.com → Account → Access Tokens → Generate New Token):
-
-| Setting | Value |
-|---------|-------|
-| Token type | **Automation** (bypasses 2FA, suitable for CI) |
-
-**Adding the variable:**
-
-| Setting | Value |
-|---------|-------|
-| Key | `NPM_TOKEN` |
-| Masked | ✅ Yes |
-| Protected | ✅ Yes (only needed on tag pipelines, which are protected) |
-
-#### `PYPI_TOKEN`
-
-**Creating the token** (pypi.org → Account Settings → API tokens → Add API token):
-
-| Setting | Value |
-|---------|-------|
-| Token name | `lazy-mcp-ci` (or any name) |
-| Scope | **Project: lazy-mcp** (restrict to this project after first publish; use "Entire account" for the very first publish) |
-
-**Adding the variable:**
-
-| Setting | Value |
-|---------|-------|
-| Key | `PYPI_TOKEN` |
-| Masked | ✅ Yes |
-| Protected | ✅ Yes (only needed on tag pipelines, which are protected) |
-
-#### `CARGO_TOKEN`
-
-**Creating the token** (crates.io → Account Settings → API Tokens → New Token):
-
-| Setting | Value |
-|---------|-------|
-| Token name | `lazy-mcp-ci` (or any name) |
-| Scopes | `publish-new`, `publish-update` |
-
-**Adding the variable:**
-
-| Setting | Value |
-|---------|-------|
-| Key | `CARGO_TOKEN` |
-| Masked | ✅ Yes |
-| Protected | ✅ Yes (only needed on tag pipelines, which are protected) |
+See [doc/RELEASES.md](./doc/RELEASES.md) for the full release pipeline and the required CI/CD variables (`GITLAB_RELEASE_TOKEN`, `NPM_TOKEN`, `PYPI_TOKEN`, `CARGO_TOKEN`).
 
 ## Configuration Reference
 
-### Server Configuration Fields
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `name` | string | ✅ | Unique server identifier |
-| `description` | string | ✅ | Human-readable description |
-| `type` | "local" \| "remote" | Optional | Inferred from `url` (remote) or `command` (local) if omitted |
-| `command` | string[] \| string | For local | Command to execute (array format recommended) |
-| `args` | string[] | Optional | Arguments (only if command is string) |
-| `url` | string | For remote | HTTP/HTTPS URL |
-| `headers` | object | Optional | Static HTTP headers for remote servers |
-| `oauth` | object | Optional | OAuth 2.0 config for remote servers (see below) |
-| `env` | object | Optional | Environment variables (supports `${VAR}` and `{file:...}` expansion) |
-| `enabled` | boolean | Optional | Enable/disable server (default: true) |
-| `examples` | object[] | Optional | Usage examples shown in `list_servers` output |
-| `tags` | string[] | Optional | Capability tags for filtering (e.g. `"api"`, `"browser"`) |
-
-### OAuth 2.0 Authentication
-
-lazy-mcp has built-in OAuth 2.0 + PKCE support for remote servers that require user authorization. It works without opening a browser automatically, making it suitable for sandboxed agent environments: when authentication is needed, lazy-mcp returns the authorization URL in the error message so the agent can present it to the user.
-
-OAuth server endpoints are **discovered automatically** via RFC 8414 (`/.well-known/oauth-authorization-server`). Dynamic client registration (RFC 7591) is used when no `clientId` is provided.
-
-Tokens are persisted to `~/.config/lazy-mcp/tokens.json` (mode `0600`) and refreshed automatically via `refresh_token` when available.
-
-**Minimal config** (fully automatic — discovery + dynamic registration):
-```json
-{
-  "name": "glean",
-  "description": "Glean enterprise search",
-  "url": "https://your-company.glean.com/mcp/default",
-  "oauth": {}
-}
-```
-
-**With a pre-registered client ID**:
-```json
-{
-  "name": "glean",
-  "description": "Glean enterprise search",
-  "url": "https://your-company.glean.com/mcp/default",
-  "oauth": {
-    "clientId": "${GLEAN_CLIENT_ID}",
-    "extraHeaders": { "X-Glean-Auth-Type": "OAUTH" }
-  }
-}
-```
-
-**`oauth` object fields:**
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `clientId` | string | — | OAuth client ID. If omitted, dynamic registration (RFC 7591) is attempted |
-| `clientSecret` | string | — | Client secret (omit for public-client / PKCE-only flows) |
-| `callbackPort` | number | `8947` | Local port for the OAuth redirect callback server |
-| `extraHeaders` | object | — | Additional headers added to every authenticated request (e.g. `X-Glean-Auth-Type`) |
-
-**How it works:**
-
-1. Agent calls `invoke_command` (or `list_commands`) on an OAuth-protected server
-2. lazy-mcp returns an `isError: true` response with the authorization URL
-3. Agent presents the URL to the user: _"Open this URL to authorize Glean: https://..."_
-4. User opens the URL in a browser and completes authorization
-5. Browser redirects to `http://localhost:8947/callback` — lazy-mcp captures the token
-6. Agent retries the original command — now succeeds transparently
-
-### Command Format
-
-**Recommended** (OpenCode-compatible):
-```json
-{
-  "command": ["npx", "-y", "my-mcp-server", "--port", "3000"]
-}
-```
-
-**Legacy** (still supported):
-```json
-{
-  "command": "npx",
-  "args": ["-y", "my-mcp-server", "--port", "3000"]
-}
-```
-
-### Environment Variables
-
-Use `${VAR_NAME}` to reference environment variables:
-
-```json
-{
-  "env": {
-    "API_KEY": "${MY_API_KEY}",
-    "DEBUG": "true"
-  },
-  "headers": {
-    "Authorization": "Bearer ${AUTH_TOKEN}"
-  }
-}
-```
-
-Use `{file:/path/to/secret}` to read a secret directly from a file (trailing newline is stripped automatically). `~/` is expanded to the home directory. On Windows, `%VAR_NAME%` references inside the path are expanded from environment variables (e.g. `%USERPROFILE%`):
-
-```json
-{
-  "env": {
-    "GITLAB_API_TOKEN": "{file:~/.secrets/gl-pat-token}",
-    "OTHER_SECRET": "{file:/run/secrets/other-token}"
-  },
-  "headers": {
-    "Authorization": "Bearer {file:~/.secrets/api-token}"
-  }
-}
-```
-
-On Windows you can use `%USERPROFILE%` or any other environment variable in the path:
-
-```json
-{
-  "env": {
-    "API_TOKEN": "{file:%USERPROFILE%\\.secrets\\token}"
-  }
-}
-```
-
-Only absolute paths and `~/` paths are accepted. Relative paths are left unchanged. Both notations can be combined in the same value and work in `env`, `headers`, and `transport.authToken` fields. `${VAR}` references inside a `{file:...}` path are not expanded; use an absolute path, `~/`, or Windows-style `%VAR_NAME%` path expansion instead. If the referenced file cannot be read (missing or permission error), the app exits at startup with an error message — e.g. `Cannot read secret file '/run/secrets/token' (from {file:/run/secrets/token}): ENOENT: no such file or directory`.
-
-**Security best practices for secret files:**
-
-- Set permissions to `0600` (owner read/write only): `chmod 0600 ~/.secrets/my-token`
-- Store secret files in a user-specific directory (e.g. `~/.secrets/`)
-- Never commit secret files to version control — add them to `.gitignore`
-
-### Embed Server Summaries
-
-By default, the AI must call `list_servers` to discover which MCP servers are available.
-You can opt in to embedding server names and descriptions directly in the `list_servers` tool description so the
-AI sees them upfront — useful for routing requests like "check my email" to the correct server without an extra tool call.
-
-```json
-{
-  "servers": [...],
-  "embedServerSummaries": {
-    "enabled": true,
-    "maxServers": 5
-  }
-}
-```
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `embedServerSummaries.enabled` | boolean | — | Enable/disable embedding |
-| `embedServerSummaries.maxServers` | number | `10` | Maximum number of server summaries to embed |
-
-> **Note:** Tool descriptions are included in every request context window. 
-> If your system prompt already instructs the LLM to call `list_servers`, this adds tokens with no benefit. 
-> Per-server descriptions are unbounded, so one verbose description can significantly increase tool description size. 
-> Making this opt-in lets you consciously accept that trade-off.
-
-### Transport Configuration
+lazy-mcp reads its configuration from `~/.config/lazy-mcp/servers.json` (or `--config <path>`). At minimum each server needs `name`, `description`, and either `command` (local) or `url` (remote).
 
-Configure how lazy-mcp exposes its MCP endpoint. By default, it uses stdio (for subprocess-based clients). Set `type: "http"` to run as an HTTP server.
+Common top-level blocks:
 
-**Top-level configuration** (in `servers.json`):
+- **`servers[]`** — list of MCP servers to aggregate (required)
+- **`permissions`** — global and per-server allow/deny rules for `invoke_command` (experimental)
+- **`transport`** — switch from stdio to HTTP, set port, bind host, bearer auth, etc.
+- **`logging`** — structured stderr logging (level, format, body dumps, redaction)
+- **`healthMonitor`** — background health probes (activity-driven by default)
+- **`embedServerSummaries`** — opt-in: embed configured server names/descriptions in `list_servers` description
+- **`requestTimeout`** — per-server request timeout in ms
 
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `transport.type` | `"stdio"` \| `"http"` | `"stdio"` | Transport mode |
-| `transport.port` | number | `8080` | HTTP server port |
-| `transport.host` | string | `"127.0.0.1"` | HTTP server bind address. For TLS-terminating reverse proxies, keep localhost binding and configure `allowedOrigins` explicitly. |
-| `transport.path` | string | `"/mcp"` | MCP endpoint URL path |
-| `transport.authToken` | string | — | Bearer token for HTTP auth (supports `${VAR}` and `{file:...}` expansion) |
-| `transport.allowedOrigins` | string[] | — | List of allowed Origin header values for request-origin validation / CSRF protection (e.g. `["https://example.com"]`). Full origins including scheme and port. Recommended for TLS-terminating reverse-proxy deployments. Does not send CORS response headers. |
-| `transport.allowedHosts` | string[] | — | List of explicitly allowed host domains for DNS rebinding protection. If a reverse proxy preserves the public `Host` header, add that host here. |
-| `transport.maxPayloadSize` | number | `4194304` | Maximum request body size in bytes. Requests exceeding this limit return HTTP 413 |
+You can also expand secrets in any string value with `${VAR}` (env var) or `{file:/path/to/secret}` (file-based, owner-only `0600` recommended).
 
-**CLI flags** (override config values):
+Send `SIGHUP` to reload the config without restarting (`kill -HUP <pid>` — the PID is in `list_servers`).
 
-| Flag | Env Variable | Description |
-|------|-------------|-------------|
-| `--transport` | `LAZY_MCP_TRANSPORT` | Transport type (`stdio` or `http`) |
-| `--port` | `LAZY_MCP_PORT` | HTTP server port |
-| `--host` | `LAZY_MCP_HOST` | HTTP server bind address |
-| `--path` | `LAZY_MCP_PATH` | MCP endpoint URL path |
-| `--auth-token` | `LAZY_MCP_AUTH_TOKEN` | Bearer token for HTTP auth |
-| `--request-timeout` | `LAZY_MCP_REQUEST_TIMEOUT` | Request timeout in ms for server calls, including MCP handshake requests and remote response parsing (default: 10000) |
-| `--max-payload-size` | `LAZY_MCP_MAX_PAYLOAD_SIZE` | Maximum request body size in bytes (default: 4194304) |
-
-When `authToken` is set, all HTTP requests must include `Authorization: Bearer <token>` — unauthenticated requests receive `401 Unauthorized`.
-
-### Logging Configuration
-
-lazy-mcp now emits structured logs to **stderr** (stdout remains reserved for MCP protocol traffic).
-
-**Top-level configuration** (in `servers.json`):
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `logging.level` | `"error"` \| `"info"` \| `"debug"` | `"info"` | Minimum log level |
-| `logging.format` | `"json"` \| `"plain"` | `"json"` | Log output format |
-| `logging.dumpBodies` | boolean | `false` | Enable debug request/response body dumps |
-| `logging.maxBodyLogBytes` | number | `8192` | Max body-dump size in bytes before truncation |
-| `logging.redactKeys` | string[] | — | Additional case-insensitive keys to redact (merged with built-in defaults) |
-
-Built-in redaction includes common secret keys like `authorization`, `token`, `access_token`, `refresh_token`, `client_secret`, and `headers.authorization`.
-
-Example:
-
-```json
-{
-  "servers": [
-    {
-      "name": "my-server",
-      "description": "Example",
-      "command": ["npx", "-y", "my-mcp-server"]
-    }
-  ],
-  "logging": {
-    "level": "debug",
-    "format": "json",
-    "dumpBodies": true,
-    "maxBodyLogBytes": 4096,
-    "redactKeys": ["my_custom_secret"]
-  }
-}
-```
-
-Typical access log event fields include:
-- client source (`clientIp`, optional `forwardedFor`)
-- request shape (`httpMethod`, `path`, `mcpMethod`, `lazyTool`)
-- downstream routing (`downstreamServer`, `downstreamCommand`)
-- outcome (`status`, `reason`, `durationMs`)
-
-### Health Monitoring
-
-lazy-mcp includes a background health monitor that probes all servers periodically. The monitor is **activity-driven**: it sleeps on startup and only begins probing after the first user tool call (`list_servers`, `list_commands`, etc.). After a configurable idle timeout (default: 5 minutes) with no tool calls, the monitor goes back to sleep. This prevents OAuth-protected servers (e.g. GitLab via `mcp-remote`) from opening browser windows when no one is using the tools.
-
-Successful probes populate the discovery cache, so subsequent `list_commands` calls return instantly from cache.
-
-**Top-level configuration** (in `servers.json`):
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `healthMonitor.enabled` | boolean | `true` | Enable/disable background health monitoring |
-| `healthMonitor.interval` | number | `30000` | Interval between health checks (ms) |
-| `healthMonitor.timeout` | number | `10000` | Timeout per server probe (ms) |
-| `healthMonitor.idleTimeout` | number | `300000` | Stop probing after this much inactivity (ms). `0` = never sleep (legacy) |
-| `requestTimeout` | number | `10000` | Timeout for individual server requests. For remote HTTP servers, this includes waiting for headers, reading response bodies, and SSE response parsing. Override via `--request-timeout` or `LAZY_MCP_REQUEST_TIMEOUT` |
-
-To disable health monitoring:
-```json
-{
-  "servers": [...],
-  "healthMonitor": { "enabled": false }
-}
-```
-
-To increase the request timeout (e.g. for slow remote servers):
-```json
-{
-  "servers": [...],
-  "requestTimeout": 30000
-}
-```
-
-### Config Reload (SIGHUP)
-
-You can reload the configuration without restarting the process by sending a `SIGHUP` signal:
-
-```bash
-kill -HUP $(pgrep -f lazy-mcp)
-```
-
-This will:
-- Re-read and validate the config file
-- Add newly configured servers (lazy connection on first use)
-- Remove servers no longer in config (closes connections)
-- Reconnect servers whose config changed (updated URL, env, etc.)
-- Preserve unchanged servers (keeps existing connections and caches)
-- Restart the health monitor and probe all servers
-
-If the new config is invalid, the reload is rejected and the current config continues running. All reload activity is logged to stderr.
-
-> **Note**: SIGHUP is not available on Windows.
+For the full reference — every field, OAuth flow, permission rule semantics, glob syntax, HTTP transport security, logging knobs, health-monitor tuning, and SIGHUP reload semantics — see **[doc/CONFIGURATION.md](./doc/CONFIGURATION.md)**.
 
 ## Benefits
 
@@ -802,9 +343,12 @@ If the new config is invalid, the reload is rejected and the current config cont
 
 ## Documentation
 
-- **[CHANGELOG.md](./CHANGELOG.md)** - Version history and release notes
-- **[AGENTS.md](./AGENTS.md)** - Development guide for AI coding agents (build commands, code style, testing patterns)
+- **[doc/CONFIGURATION.md](./doc/CONFIGURATION.md)** - Full configuration reference (servers, permissions, OAuth, transport, logging, health monitoring, SIGHUP reload)
+- **[doc/HTTP_TRANSPORT.md](./doc/HTTP_TRANSPORT.md)** - Streamable HTTP transport setup, security, and reverse-proxy guidance
+- **[doc/INTEGRATION.md](./doc/INTEGRATION.md)** - Client integration examples (Claude Desktop, OpenCode, Cursor, VS Code) for stdio and HTTP modes
+- **[doc/RELEASES.md](./doc/RELEASES.md)** - Release pipeline and required CI/CD variables
 - **[doc/ARCHITECTURE.md](./doc/ARCHITECTURE.md)** - Architecture overview and design patterns
 - **[doc/CONTRIBUTING.md](./doc/CONTRIBUTING.md)** - Contributing guide with common development tasks
 - **[doc/requests/](./doc/requests/)** - [Bruno](https://www.usebruno.com/) API collection for testing the Streamable HTTP transport. Open the `doc/requests/` folder as a collection in Bruno, select the `local` or `local-with-auth` environment, and run requests against a locally running `lazy-mcp --transport http` instance.
-- **[Configuration Reference](#configuration-reference)** - Server configuration options (above)
+- **[CHANGELOG.md](./CHANGELOG.md)** - Version history and release notes
+- **[AGENTS.md](./AGENTS.md)** - Development guide for AI coding agents (build commands, code style, testing patterns)