diff --git a/.env.example b/.env.example
index 43db7e8c..002e0fec 100644
--- a/.env.example
+++ b/.env.example
@@ -148,3 +148,11 @@ GADS_MCC_ID=                   # Google Ads MCC (manager) account ID, format 123
 GADS_CUSTOMER_ID=              # Google Ads child customer ID, format 987-654-3210
 GCP_PROJECT_ID=                # Google Cloud project ID (e.g. my-website-123456)
 GSC_SERVICE_ACCOUNT=           # Search Console reporter service account email
+
+# ---- opencode / remote MCP client auth (see docs/integrations/opencode.md) ----
+# MOLECULE_MCP_URL is the base URL of the Molecule platform's /mcp endpoint.
+# MOLECULE_MCP_TOKEN is a workspace-scoped bearer token issued via
+#   POST /workspaces/:id/tokens  (scopes: mcp:read, mcp:delegate).
+# Token goes in Authorization: Bearer header — never embed in the URL.
+MOLECULE_MCP_URL=                # e.g. https://api.molecule.ai or http://localhost:8080
+MOLECULE_MCP_TOKEN=              # workspace-scoped bearer token — NEVER COMMIT