dotfiles/mcp-config/README.md

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:

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.