diff --git a/mcp-config/README.md b/mcp-config/README.md
new file mode 100644
index 0000000..22cc9e9
--- /dev/null
+++ b/mcp-config/README.md
@@ -0,0 +1,60 @@
+# mcp-config — shared MCP gateway config for laptops
+
+Single source of truth for the **shared** MCP servers every covert-gpt user
+gets through the LiteLLM gateway (`llm.covert-gpt.com`). Users install once;
+their config then refreshes automatically on each new shell.
+
+This repo lives in Gitea at `public/dotfiles`. (It is mirrored from the
+`ai-k8s-iac` repo under `mcp-config/`; edit it there or here and keep them in
+sync — the laptops pull from Gitea's `main`.)
+
+## How it works
+
+- `opencode.gateway.json` — the shared server list. **Identical for every
+  user**: the per-user key is injected via `{env:LITELLM_KEY}`, never written
+  into the file. Add a gateway server here and everyone picks it up next shell.
+- `sync.sh` — sourced from each user's shell rc. On a new shell it pulls
+  `opencode.gateway.json` (throttled ~1h), drops it where opencode merges it,
+  and exports `LITELLM_KEY` from `~/.config/mcp-sync/key`. Silent + non-fatal:
+  a Gitea hiccup never breaks the shell, last-good config stays in place.
+- `install.sh` — one-time bootstrap (curl-pipe). Fetches `sync.sh`, stores the
+  user's key (0600), and adds the rc hook.
+
+opencode **merges** config files, so the synced `opencode.gateway.json`
+coexists with each user's own `~/.config/opencode/opencode.json` and any
+**local-only** MCP servers (e.g. a client-side `kubernetes` pointed at their
+own kubeconfig). Sync never touches those.
+
+## User setup (one time)
+
+Each user needs a LiteLLM **virtual key** scoped to the gateway servers (see
+`charts/inference/MCP-GATEWAY.md` in ai-k8s-iac for how keys are minted). Then:
+
+```sh
+curl -fsSL https://git.nic-oconnor.com/public/dotfiles/raw/branch/main/mcp-config/install.sh | sh
+# (prompts for the sk-... key; or pass it: ... | LITELLM_KEY=sk-... sh)
+```
+
+Open a new terminal, run `opencode`, and the gateway tools are there.
+
+## Adding a gateway server (admin)
+
+1. Register it on the gateway (`charts/inference/values.yaml` →
+   `proxy_config.mcp_servers`), deploy, smoke-test.
+2. Add a matching entry to `opencode.gateway.json` here and push to `main`.
+3. Users get it automatically within the sync TTL (or immediately on a new
+   shell). No per-user action.
+
+For **per-user / per-target** tools (cluster access, etc.) do NOT add them
+here — those run client-side with the user's own credentials. See
+`charts/inference/MCP-GATEWAY.md`.
+
+## Notes / caveats
+
+- **Local-server precedence**: opencode merges with later-config-wins on key
+  conflicts. If a user names a local server the same as a gateway one, theirs
+  wins. Use distinct names.
+- **Key rotation**: re-run `install.sh` (or edit `~/.config/mcp-sync/key`).
+- **Other clients**: this ships an opencode config. Claude Code / open-webui
+  would need their own equivalent file + a parallel sync entry; not done yet.
+- **Throttle**: override with `MCP_SYNC_TTL=0` to force a pull every shell.