diff --git a/mcp-config/sync.sh b/mcp-config/sync.sh
new file mode 100644
index 0000000..fc73224
--- /dev/null
+++ b/mcp-config/sync.sh
@@ -0,0 +1,71 @@
+#!/usr/bin/env sh
+# mcp-sync — refresh the shared LiteLLM-gateway MCP config on the laptop and
+# export the user's LiteLLM key into the environment.
+#
+# Sourced from the user's shell rc (installed by install.sh) so it runs at the
+# start of every interactive shell ("session start"). It is intentionally:
+#   - FAST and SILENT on success (no output unless something is wrong)
+#   - NON-FATAL: a network/Gitea hiccup must never break the user's shell, so
+#     every failure path just returns, leaving the last-good config in place.
+#
+# What it does:
+#   1. Fetch the shared opencode.gateway.json from Gitea (the single source of
+#      truth for which gateway MCP servers exist). The file is identical for
+#      all users — the per-user key is injected via {env:LITELLM_KEY}, never
+#      baked into the file.
+#   2. Drop it at ~/.config/opencode/opencode.gateway.json. opencode MERGES
+#      config files, so this coexists with the user's own opencode.json and
+#      any local-only MCP servers (e.g. a client-side kubernetes pointed at
+#      their kubeconfig) — those are never touched.
+#   3. Export LITELLM_KEY from ~/.config/mcp-sync/key so {env:LITELLM_KEY}
+#      resolves.
+
+# --- config (overridable via env before sourcing) -------------------------
+MCP_SYNC_RAW_URL="${MCP_SYNC_RAW_URL:-https://git.nic-oconnor.com/public/dotfiles/raw/branch/main/mcp-config/opencode.gateway.json}"
+MCP_SYNC_HOME="${MCP_SYNC_HOME:-$HOME/.config/mcp-sync}"
+MCP_SYNC_DEST="${MCP_SYNC_DEST:-$HOME/.config/opencode/opencode.gateway.json}"
+MCP_SYNC_KEYFILE="${MCP_SYNC_KEYFILE:-$MCP_SYNC_HOME/key}"
+# Throttle: only re-pull if the cached copy is older than this many seconds
+# (default 1h). Keeps every new shell from hammering Gitea.
+MCP_SYNC_TTL="${MCP_SYNC_TTL:-3600}"
+
+# --- 1+2. refresh the gateway config (throttled, non-fatal) ---------------
+_mcp_sync_fetch() {
+  mkdir -p "$(dirname "$MCP_SYNC_DEST")" || return 0
+
+  # Skip if we pulled recently (mtime within TTL). `find -mmin` is portable
+  # enough; fall back to always-fetch if find is unavailable.
+  if [ -f "$MCP_SYNC_DEST" ] && command -v find >/dev/null 2>&1; then
+    if find "$MCP_SYNC_DEST" -mmin -"$(( MCP_SYNC_TTL / 60 ))" 2>/dev/null | grep -q .; then
+      return 0
+    fi
+  fi
+
+  command -v curl >/dev/null 2>&1 || return 0
+  tmp="$(mktemp 2>/dev/null)" || return 0
+  # -f: fail on HTTP error; -s: silent; -m: hard timeout so a hung network
+  # can't stall the shell.
+  if curl -fsS -m 8 "$MCP_SYNC_RAW_URL" -o "$tmp" 2>/dev/null; then
+    # Only replace if it's non-empty and valid JSON (don't clobber good config
+    # with an error page).
+    if [ -s "$tmp" ] && { ! command -v python3 >/dev/null 2>&1 || python3 -c "import json,sys; json.load(open(sys.argv[1]))" "$tmp" 2>/dev/null; }; then
+      mv "$tmp" "$MCP_SYNC_DEST" 2>/dev/null || rm -f "$tmp"
+    else
+      rm -f "$tmp"
+    fi
+  else
+    rm -f "$tmp"
+  fi
+}
+
+# --- 3. export the per-user key -------------------------------------------
+_mcp_sync_export_key() {
+  [ -f "$MCP_SYNC_KEYFILE" ] || return 0
+  # Strip whitespace/newline; export so {env:LITELLM_KEY} resolves in opencode.
+  LITELLM_KEY="$(tr -d ' \t\r\n' < "$MCP_SYNC_KEYFILE" 2>/dev/null)"
+  [ -n "$LITELLM_KEY" ] && export LITELLM_KEY
+}
+
+_mcp_sync_fetch
+_mcp_sync_export_key
+unset -f _mcp_sync_fetch _mcp_sync_export_key 2>/dev/null || true