diff --git a/services/mcp-gateway.md b/services/mcp-gateway.md
index 081308d..e8e1d99 100644
--- a/services/mcp-gateway.md
+++ b/services/mcp-gateway.md
@@ -89,3 +89,32 @@ entrypoint fronting several MCP servers.
   uv run --with playwright -- python -m playwright install chromium   # once
   uv run --with playwright -- python ai/mcp-gateway/ui_check.py        # -> /tmp/mcp_ui.png
   ```
+
+## Client config download — `/mcp-config` (added 2026-05-21)
+
+Instead of asking the user to paste a bearer token into per-server entries
+in `~/.claude/settings.json`, the gateway now hands back a ready-to-use
+config blob for the signed-in user:
+
+```
+GET https://mcp.nuclide.systems/mcp-config?format=claude   # default
+GET https://mcp.nuclide.systems/mcp-config?format=cursor
+GET https://mcp.nuclide.systems/mcp-config?format=raw      # token + server URLs only
+```
+
+- Requires the user's Pocket-ID session cookie OR an existing Bearer token (303 → `/login` if neither).
+- Mints a fresh long-lived gateway token (`mcp_<urlsafe>`) bound to the user; persisted in `gateway_tokens.json` with `purpose=client-config:<format>` so it's distinguishable from OAuth-issued tokens (and revocable).
+- Returns a JSON file with `Content-Disposition: attachment` so the browser saves it.
+
+### Claude Code workflow
+1. Sign in at `https://mcp.nuclide.systems`.
+2. Click **Claude config** in the top nav. Browser downloads `nuclide-mcp.claude.json`.
+3. Merge the `mcpServers` block into `~/.claude/settings.json`. Restart Claude Code.
+
+The downloaded file has 23 entries, one per spawnable MCP server, with `type: http` + `url: https://mcp.nuclide.systems/<server>/mcp` + an `Authorization: Bearer ...` header. No further per-server configuration needed.
+
+### Rotation
+Each download mints a NEW token. Old tokens remain valid until you remove them from `gateway_tokens.json` (manual prune; future: admin UI button).
+
+### Server list reflected in the config
+The gateway populates from `mcp-gateway/config.json` `mcpServers` keys — exactly the set running at the time of download. New servers added later require re-downloading the config.