diff --git a/content/manuals/ai/sandboxes/mcp-gateway.md b/content/manuals/ai/sandboxes/mcp-gateway.md
index d65ca5c529..9048d41d48 100644
--- a/content/manuals/ai/sandboxes/mcp-gateway.md
+++ b/content/manuals/ai/sandboxes/mcp-gateway.md
@@ -339,6 +339,14 @@ If none of these provide a scope set, `sbx` omits the OAuth `scope` parameter so
 the authorization server applies its default grant. Other advertised scopes
 aren't included in the fallback.
 
+When `sbx` uses recorded defaults or resource-required scopes, it also
+requests `offline_access` if the authorization server advertises it. The
+server can then issue a refresh token, so you don't have to authorize again
+when the access token expires. Scopes passed to `sbx mcp auth --scope` are
+requested exactly as given, without `offline_access`. Existing credentials
+issued without a refresh token aren't upgraded; run `sbx mcp auth` again to
+request a new grant.
+
 Pass `--no-scope` to suppress the recorded defaults, resource-required scopes,
 and advertised scope fallback for one authorization, without changing the
 stored defaults: