From 904401a7f13085bc24614021db09070a76055bfc Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 12 Jun 2026 11:26:20 +0000
Subject: [PATCH 1/2] Add provider-declared OAuth bootstrap and run setup
 before registration
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

OAuth bootstrap: a provider YAML can now declare a one-time browser
consent flow with a top-level oauth: block (type: google) naming its
client_secret.json, the token file to mint, and the scopes. The new
oauth_bootstrap module reuses the existing authorization_code machinery
— flows register in AuthCodeTokenStore._pending_flows tagged with a
kind, URLs publish to the pending-auth banner, and the shared
/oauth/callback dispatches non-REST flows back to it — and builds the
consent URL with PKCE, access_type=offline, and prompt=consent. The
exchanged token is written in Credentials.to_json() format so provider
code keeps using Credentials.from_authorized_user_file() unchanged,
with refresh handled by the google libs at call time.

Wiring: a startup oauth-warmup thread surfaces missing tokens in the
banner; POST /api/oauth-bootstrap (and a 🔐 Authorize button with a
read-only summary in the provider editor) restarts the flow on demand;
/api/tools exposes per-provider token status for a list badge; the
oauth block round-trips through the structured editor and is validated
(including a client_secret_file existence check that points at the
Files manager).

Also: bootstrap_provider now runs requirements/setup before
registration, eliminating the noisy failed-first-attempt tracebacks for
code providers that import their declared requirements at module level
(the previous install-then-retry behavior is no longer needed).

41 new tests cover the flow begin/complete, token-file format (loaded
back via google-auth), refresh-token salvage and consent-hint error,
callback dispatch (with REST regression), warm-up, endpoints,
round-trip, and validation.

https://claude.ai/code/session_01WnK1rtXGHDCNpsycAvxFqC
---
 Dockerfile                    |   2 +-
 README.md                     |  41 ++++
 frontend/app.py               | 164 +++++++++++++++-
 oauth_bootstrap.py            | 277 +++++++++++++++++++++++++++
 rest_provider.py              |   5 +
 server.py                     |  74 +++++---
 tests/test_frontend.py        | 162 ++++++++++++++++
 tests/test_oauth_bootstrap.py | 343 ++++++++++++++++++++++++++++++++++
 tests/test_server.py          |  98 ++++++++--
 9 files changed, 1123 insertions(+), 43 deletions(-)
 create mode 100644 oauth_bootstrap.py
 create mode 100644 tests/test_oauth_bootstrap.py

diff --git a/Dockerfile b/Dockerfile
index 9c59b51..9d098b8 100755
--- a/Dockerfile
+++ b/Dockerfile
@@ -18,7 +18,7 @@ RUN pip install --no-cache-dir -r requirements.txt
 RUN pip install --no-cache-dir uv
 ENV PATH="/root/.local/bin:$PATH"
 
-COPY server.py config.py process_runner.py builtin_tools.py tool_registry.py rest_provider.py ./
+COPY server.py config.py process_runner.py builtin_tools.py tool_registry.py rest_provider.py oauth_bootstrap.py ./
 COPY frontend/ ./frontend/
 COPY handlers/ ./handlers/
 
diff --git a/README.md b/README.md
index d318a9b..09906cf 100755
--- a/README.md
+++ b/README.md
@@ -244,6 +244,47 @@ Config knobs: `MCPPROXY_REST_AUTH_DIR`, `MCPPROXY_OAUTH_REDIRECT_BASE`,
 response size before truncation; 0 disables), and `MCPPROXY_OAUTH_FLOW_TTL` (seconds an
 in-flight authorization attempt stays valid; default 600).
 
+### OAuth token-file bootstrap (`oauth:` block)
+
+Some providers — typically **code providers** using Google client libraries — need a
+user-consent OAuth token *file* (e.g. `gmail_token.json` minted from
+`client_secret.json`) rather than header injection. Instead of running
+`InstalledAppFlow` on a machine with a browser and copying the files in, declare the
+need in the provider YAML and let mcpproxy run the flow:
+
+```yaml
+oauth:
+  type: google            # the only supported type today
+  client_secret_file: /app/tools/secrets/client_secret.json
+  token_file: /app/tools/secrets/gmail_token.json
+  scopes:
+    - https://www.googleapis.com/auth/gmail.settings.basic
+    - https://www.googleapis.com/auth/gmail.labels
+  # optional: prompt (default "consent"), login_hint
+```
+
+How it works:
+
+1. Create a Google OAuth client (Desktop **installed** type is easiest) in the Google
+   Cloud Console, download `client_secret.json`, and upload it via the **📁 Files**
+   manager (e.g. into `tools/secrets/`).
+2. At startup (and via the **🔐 Authorize** button in the provider editor), mcpproxy
+   checks `token_file`. If no usable token exists, the consent URL — built with PKCE,
+   `access_type=offline`, and `prompt=consent` — appears in the yellow pending-auth
+   banner.
+3. Click it, approve in Google, and the browser is redirected to mcpproxy's
+   `/oauth/callback`, which exchanges the code and writes `token_file` in exactly the
+   format `google.oauth2.credentials.Credentials.from_authorized_user_file()` accepts.
+4. Your provider code reads the token file as usual; the Google client libraries refresh
+   the access token automatically from the stored `refresh_token` at call time. If the
+   token is ever revoked, the 🔐 badge and banner reappear — re-authorizing is one click.
+
+Redirect URI: Desktop ("installed") Google clients accept `http://localhost:8889/oauth/callback`
+without registration (browse the UI via localhost when authorizing). "Web" clients must
+have the exact URI registered — set `MCPPROXY_OAUTH_REDIRECT_BASE` if the UI is served
+from a different origin. Note `prompt=consent` is the default because Google only issues
+a refresh_token on a full consent screen, not on silent re-approval.
+
 ## Secrets
 
 Each tool provider YAML declares its required environment variables under `secrets.env`:
diff --git a/frontend/app.py b/frontend/app.py
index 1557b4e..bfeb4bb 100644
--- a/frontend/app.py
+++ b/frontend/app.py
@@ -19,6 +19,7 @@
 POST /api/files/upload          — multipart upload (root, path, file)
 GET  /api/files/download        — download a file (?root=&path=)
 DELETE /api/files               — delete a file/dir (?root=&path=&recursive=)
+POST /api/oauth-bootstrap       — begin a provider-declared OAuth consent flow {name}
 POST /api/restart               — send SIGTERM to restart server
 GET  /api/config                — UI feature flags (e.g. web_terminal)
 WS   /ws/terminal               — interactive PTY terminal (optional ?cmd=…)
@@ -318,6 +319,7 @@ def _provider_to_structured(name: str, spec: dict[str, Any]) -> dict[str, Any]:
         "repo_env_keys": repo_env_keys,
         "workdir": workdir,
         "rest": rest_out,
+        "oauth": dict(spec.get("oauth") or {}),
         "tools": tools_out,
     }
 
@@ -375,6 +377,20 @@ def _structured_to_yaml(provider: dict[str, Any]) -> str:
         if code:
             spec["code"] = code + "\n"
 
+    oauth = provider.get("oauth") or {}
+    if oauth.get("type"):
+        oauth_block: dict[str, Any] = {"type": oauth["type"]}
+        for key in ("client_secret_file", "token_file"):
+            if (oauth.get(key) or "").strip():
+                oauth_block[key] = oauth[key].strip()
+        scopes = [s for s in (oauth.get("scopes") or []) if s]
+        if scopes:
+            oauth_block["scopes"] = scopes
+        for key in ("prompt", "login_hint"):
+            if oauth.get(key):
+                oauth_block[key] = oauth[key]
+        spec["oauth"] = oauth_block
+
     requirements = [r for r in (provider.get("requirements") or []) if r]
     if requirements:
         spec["requirements"] = requirements
@@ -461,9 +477,39 @@ def _validate_rest(provider: dict[str, Any]) -> list[str]:
     return errors
 
 
+def _validate_oauth(provider: dict[str, Any]) -> list[str]:
+    """Return validation errors for a provider's top-level ``oauth`` block."""
+    import oauth_bootstrap
+
+    oauth = provider.get("oauth") or {}
+    if not oauth.get("type"):
+        return []
+    errors: list[str] = []
+    otype = (oauth.get("type") or "").strip()
+    if otype not in oauth_bootstrap.SUPPORTED_TYPES:
+        errors.append(
+            f"oauth.type must be one of {sorted(oauth_bootstrap.SUPPORTED_TYPES)}"
+        )
+        return errors
+    for key in ("client_secret_file", "token_file"):
+        if not (oauth.get(key) or "").strip():
+            errors.append(f"oauth.{key} is required for {otype} oauth")
+    scopes = oauth.get("scopes")
+    if not isinstance(scopes, list) or not [s for s in (scopes or []) if s]:
+        errors.append("oauth.scopes must be a non-empty list")
+    secret_file = (oauth.get("client_secret_file") or "").strip()
+    if secret_file and not Path(secret_file).is_file():
+        errors.append(
+            f"oauth.client_secret_file not found: {secret_file} — upload it via "
+            "the Files manager (e.g. tools/secrets/)"
+        )
+    return errors
+
+
 def _validate_provider(provider: dict[str, Any]) -> dict[str, Any]:
     errors: list[str] = []
     ptype = provider.get("type", "code")
+    errors.extend(_validate_oauth(provider))
 
     if ptype == "rest":
         errors.extend(_validate_rest(provider))
@@ -631,6 +677,12 @@ async def list_tools() -> list[dict]:
                 is_package = bool(_get_package_spec(spec))
                 is_repository = bool(_get_repository_spec(spec))
                 is_rest = bool(_get_rest_spec(spec))
+                oauth_cfg = spec.get("oauth") or {}
+                oauth_out = None
+                if oauth_cfg.get("type"):
+                    import oauth_bootstrap
+                    oauth_out = {"type": oauth_cfg.get("type"),
+                                 **oauth_bootstrap.token_status(oauth_cfg)}
                 out.append({
                     "name": path.stem,
                     "file": path.name,
@@ -644,6 +696,7 @@ async def list_tools() -> list[dict]:
                     "missing_secrets": missing_secrets,
                     "validation_errors": validation["errors"],
                     "documentation": spec.get("documentation") or "",
+                    "oauth": oauth_out,
                 })
             except Exception as exc:
                 out.append({"name": path.stem, "file": path.name, "error": str(exc)})
@@ -836,6 +889,44 @@ async def rest_authorize(request: Request) -> dict:
             traceback.print_exc()
             return {"ok": False, "error": str(exc)}
 
+    @app.post("/api/oauth-bootstrap")
+    async def oauth_bootstrap_endpoint(request: Request) -> dict:
+        """Begin (or restart) the consent flow declared by a provider's
+        top-level ``oauth:`` block (e.g. a Google token-file bootstrap).
+
+        Body: { name: <provider> }.  Builds the consent URL (offline access +
+        PKCE), publishes it to the pending-auth banner, and returns
+        ``{ok, auth_url, redirect_uri, token}`` for the UI to open.
+        """
+        body = await request.json()
+        name = (body.get("name") or "").strip()
+        _guard_name(name)
+        path = _config_dir / f"{name}.yaml"
+        if not path.exists():
+            raise HTTPException(404, f"Provider '{name}' not found")
+        spec = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+        import oauth_bootstrap
+        oauth_cfg = oauth_bootstrap.get_oauth_config(spec)
+        if oauth_cfg is None:
+            raise HTTPException(400, "Provider has no oauth block")
+        if (oauth_cfg.get("type") or "").strip() not in oauth_bootstrap.SUPPORTED_TYPES:
+            raise HTTPException(
+                400,
+                f"Unsupported oauth.type (supported: {sorted(oauth_bootstrap.SUPPORTED_TYPES)})",
+            )
+        try:
+            from rest_provider import oauth_redirect_uri
+            auth_url = oauth_bootstrap.begin_authorization(name, oauth_cfg)
+            return {
+                "ok": True,
+                "auth_url": auth_url,
+                "redirect_uri": oauth_redirect_uri(),
+                "token": oauth_bootstrap.token_status(oauth_cfg),
+            }
+        except Exception as exc:
+            traceback.print_exc()
+            return {"ok": False, "error": str(exc)}
+
     @app.get("/oauth/callback")
     async def oauth_callback(
         code: str = "", state: str = "", error: str = ""
@@ -1637,6 +1728,24 @@ async def index():
           <div id="rest-auth-status" class="mt-2 fn-status"></div>
         </div>
 
+        <!-- OAuth bootstrap box (providers with a top-level oauth: block) -->
+        <div class="section-box" id="oauth-box" style="display:none">
+          <div class="section-title">
+            🔐 OAuth Token Bootstrap
+            <button class="btn btn-sm btn-outline-warning py-0" id="oauth-bootstrap-btn"
+              onclick="authorizeOAuthProvider()"
+              title="Run the browser consent flow to mint / refresh the token file">🔐 Authorize</button>
+          </div>
+          <div id="oauth-summary" style="font-size:.875em"></div>
+          <div class="text-muted mt-2" style="font-size:.8em">
+            Declared by the <code>oauth:</code> block in this provider's YAML. After you approve in the
+            browser, the token file is written automatically — Desktop ("installed") Google clients accept
+            the localhost redirect without registration; "web" clients must have the redirect URI below
+            registered in the Google Cloud Console.
+          </div>
+          <div id="oauth-auth-status" class="mt-2 fn-status"></div>
+        </div>
+
         <!-- Code box (code providers) -->
         <div class="section-box" id="code-box" style="display:none">
           <div class="section-title">🐍 Python Code</div>
@@ -2207,6 +2316,7 @@ async def index():
       providersMeta[p.name] = {
         missing_secrets: p.missing_secrets || [],
         validation_errors: p.validation_errors || [],
+        oauth: p.oauth || null,
       };
     });
     el.innerHTML = providers.map(p => {
@@ -2218,8 +2328,11 @@ async def index():
       const errBadge = errs.length
         ? `<span class="badge-err" title="${esc(errs.join(' · '))}">✗ ${errs.length} config error${errs.length > 1 ? 's' : ''}</span>`
         : '';
-      const alertRow = (warnBadge || errBadge)
-        ? `<div class="d-flex gap-1 flex-wrap mt-1">${warnBadge}${errBadge}</div>`
+      const oauthBadge = (p.oauth && !p.oauth.has_refresh_token)
+        ? `<span class="badge-warn" title="OAuth token missing — open the provider and click Authorize">🔐 authorize</span>`
+        : '';
+      const alertRow = (warnBadge || errBadge || oauthBadge)
+        ? `<div class="d-flex gap-1 flex-wrap mt-1">${warnBadge}${errBadge}${oauthBadge}</div>`
         : '';
       const isRepo = p.is_repository || p.provider_type === 'repository';
       const isPkg = p.is_package && !isRepo;
@@ -2418,11 +2531,58 @@ async def index():
     setTimeout(() => codeEditor.refresh(), 50);
   }
 
+  renderOauthSummary(p);
+
   renderRequirements(p.requirements || []);
   renderSetupCommands(p.setup_commands || []);
   renderTools(p.tools || [], nameDriven);
 }
 
+// ── OAuth bootstrap (top-level oauth: block) ─────────────────────────────────
+
+function renderOauthSummary(p) {
+  const cfg = p.oauth || {};
+  const box = document.getElementById('oauth-box');
+  if (!cfg.type) { box.style.display = 'none'; return; }
+  box.style.display = '';
+  document.getElementById('oauth-auth-status').textContent = '';
+  const meta = (providersMeta[p.name] || {}).oauth || {};
+  const tokenLine = meta.has_refresh_token
+    ? `<span style="color:var(--green)">✓ token present (refresh ok)${meta.expiry ? ' — expires ' + esc(meta.expiry) : ''}</span>`
+    : `<span style="color:var(--yellow)">✗ no usable token — click Authorize</span>`;
+  const rows = [
+    ['Type', esc(cfg.type)],
+    ['Client secret', `<code>${esc(cfg.client_secret_file || '')}</code>`],
+    ['Token file', `<code>${esc(cfg.token_file || '')}</code>`],
+    ['Scopes', (cfg.scopes || []).map(s => `<code>${esc(s)}</code>`).join('<br>') || '(none)'],
+    ['Status', tokenLine],
+    ['Redirect URI', `<code>${esc(window.location.origin)}/oauth/callback</code>`],
+  ];
+  document.getElementById('oauth-summary').innerHTML = rows.map(([k, v]) =>
+    `<div class="d-flex gap-2 mb-1"><span class="text-muted" style="flex:0 0 110px">${k}</span><span style="min-width:0;word-break:break-all">${v}</span></div>`
+  ).join('');
+}
+
+async function authorizeOAuthProvider() {
+  if (!currentName) return;
+  const status = document.getElementById('oauth-auth-status');
+  status.className = 'fn-status busy';
+  status.textContent = 'Starting authorization…';
+  try {
+    const r = await api('POST', '/api/oauth-bootstrap', {name: currentName});
+    if (!r.ok) throw new Error(r.error || 'authorization failed');
+    window.open(r.auth_url, '_blank', 'noopener');
+    status.className = 'fn-status ok';
+    status.innerHTML = `Opened the consent page. After approving, the token file is written automatically. ` +
+      `<a href="${esc(r.auth_url)}" target="_blank" rel="noopener">Re-open</a>`;
+    // Refresh the list (and this summary) once the callback has likely landed.
+    setTimeout(async () => { await loadList(); if (currentProvider) renderOauthSummary(currentProvider); }, 4000);
+  } catch(e) {
+    status.className = 'fn-status error';
+    status.textContent = e.message || 'authorization failed';
+  }
+}
+
 function updateRestBaseUrl(val) {
   ensureProvider();
   if (!currentProvider.rest) currentProvider.rest = {};
diff --git a/oauth_bootstrap.py b/oauth_bootstrap.py
new file mode 100644
index 0000000..8a43b4d
--- /dev/null
+++ b/oauth_bootstrap.py
@@ -0,0 +1,277 @@
+"""
+Provider-declared OAuth bootstrap — mint user-consent token files from the UI.
+
+A provider YAML may carry a top-level ``oauth:`` block describing a one-time
+browser consent flow whose result is a token *file* the provider's own code
+reads (as opposed to the REST providers' header-injection auth, which caches
+tokens under ``.rest-auth``)::
+
+    oauth:
+      type: google
+      client_secret_file: /app/tools/secrets/client_secret.json
+      token_file: /app/tools/secrets/gmail_token.json
+      scopes:
+        - https://www.googleapis.com/auth/gmail.settings.basic
+      # optional: prompt (default "consent"), login_hint
+
+Currently only ``type: google`` is supported.  The flow reuses the existing
+authorization_code machinery in ``rest_provider``: in-flight attempts register
+in ``AuthCodeTokenStore._pending_flows`` (tagged ``kind: "google"`` so the
+shared ``GET /oauth/callback`` route can dispatch back here), and the
+authorization URL publishes into ``pending_rest_auth`` so the UI banner shows
+a clickable link with no frontend polling changes.
+
+The written token file matches ``google.oauth2.credentials.Credentials.to_json()``,
+so provider code can load it with ``Credentials.from_authorized_user_file()``
+and the google client libraries handle refresh at call time.  The authorize
+URL always requests ``access_type=offline`` and (by default) ``prompt=consent``
+— Google only issues a refresh_token on consent, not on silent re-approval.
+
+Redirect URI: the approving browser is sent to ``{OAUTH_REDIRECT_BASE}/oauth/callback``
+(see ``rest_provider.oauth_redirect_uri`` / MCPPROXY_OAUTH_REDIRECT_BASE).
+Google Desktop ("installed") clients accept any http://localhost:<port>
+loopback without registration; "web" clients must have the exact URI
+registered in the Google Cloud Console.
+"""
+
+import datetime
+import hashlib
+import json
+import secrets as _secrets
+import time
+import traceback
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlencode
+
+import httpx
+
+from rest_provider import (
+    HTTP_TIMEOUT,
+    AuthCodeTokenStore,
+    _b64url,
+    oauth_redirect_uri,
+    pending_rest_auth,
+)
+
+GOOGLE_AUTH_URI = "https://accounts.google.com/o/oauth2/auth"
+GOOGLE_TOKEN_URI = "https://oauth2.googleapis.com/token"
+
+SUPPORTED_TYPES = {"google"}
+
+
+def get_oauth_config(spec: dict[str, Any]) -> dict[str, Any] | None:
+    """Return the provider's top-level ``oauth:`` block (with a type), or None."""
+    cfg = spec.get("oauth") or {}
+    return cfg if cfg.get("type") else None
+
+
+def load_client_secret(path: str | Path) -> dict[str, str]:
+    """Parse a Google ``client_secret.json`` (``installed`` or ``web`` client).
+
+    Returns ``{client_id, client_secret, auth_uri, token_uri}``; raises
+    ``ValueError`` with an actionable message on a missing/unreadable file.
+    """
+    p = Path(path)
+    if not p.is_file():
+        raise ValueError(
+            f"client_secret_file not found: {p} — download it from the Google "
+            "Cloud Console and upload it via the Files manager (e.g. tools/secrets/)"
+        )
+    try:
+        raw = json.loads(p.read_text(encoding="utf-8"))
+    except Exception as exc:
+        raise ValueError(f"client_secret_file {p} is not valid JSON: {exc}")
+    key = "installed" if "installed" in raw else "web" if "web" in raw else None
+    if key is None:
+        raise ValueError(
+            f"client_secret_file {p} has neither an 'installed' nor a 'web' "
+            "section — is it really a Google OAuth client secret file?"
+        )
+    section = raw[key] or {}
+    client_id = (section.get("client_id") or "").strip()
+    if not client_id:
+        raise ValueError(f"client_secret_file {p} is missing client_id")
+    return {
+        "client_id": client_id,
+        "client_secret": (section.get("client_secret") or "").strip(),
+        "auth_uri": (section.get("auth_uri") or GOOGLE_AUTH_URI).strip(),
+        "token_uri": (section.get("token_uri") or GOOGLE_TOKEN_URI).strip(),
+    }
+
+
+def token_status(oauth_cfg: dict[str, Any]) -> dict[str, Any]:
+    """Inspect the configured token_file.  Never raises."""
+    token_file = (oauth_cfg.get("token_file") or "").strip()
+    status = {
+        "token_file": token_file,
+        "present": False,
+        "has_refresh_token": False,
+        "expiry": None,
+    }
+    try:
+        data = json.loads(Path(token_file).read_text(encoding="utf-8"))
+        status["present"] = True
+        status["has_refresh_token"] = bool(data.get("refresh_token"))
+        status["expiry"] = data.get("expiry")
+    except Exception:
+        pass
+    return status
+
+
+# ---------------------------------------------------------------------------
+# Begin / complete (dispatch tables keyed by oauth type / flow kind)
+# ---------------------------------------------------------------------------
+
+def begin_authorization(provider: str, oauth_cfg: dict[str, Any]) -> str:
+    """Build the consent URL for the provider's oauth block and publish it."""
+    otype = (oauth_cfg.get("type") or "").strip()
+    begin = _BEGINNERS.get(otype)
+    if begin is None:
+        raise ValueError(
+            f"Unsupported oauth.type {otype!r} (supported: {sorted(SUPPORTED_TYPES)})"
+        )
+    return begin(provider, oauth_cfg)
+
+
+async def complete_authorization(flow: dict[str, Any], code: str) -> str:
+    """Finish a non-REST flow popped from ``AuthCodeTokenStore._pending_flows``."""
+    kind = flow.get("kind", "")
+    complete = _COMPLETERS.get(kind)
+    if complete is None:
+        raise RuntimeError(f"Unknown authorization flow kind {kind!r}")
+    return await complete(flow, code)
+
+
+def _begin_google(provider: str, oauth_cfg: dict[str, Any]) -> str:
+    client = load_client_secret(oauth_cfg.get("client_secret_file") or "")
+    scopes = [s for s in (oauth_cfg.get("scopes") or []) if s]
+    code_verifier = _b64url(_secrets.token_bytes(48))
+    code_challenge = _b64url(hashlib.sha256(code_verifier.encode("ascii")).digest())
+    state = _b64url(_secrets.token_bytes(24))
+    redirect_uri = oauth_redirect_uri()
+    params = {
+        "response_type": "code",
+        "client_id": client["client_id"],
+        "redirect_uri": redirect_uri,
+        "state": state,
+        "code_challenge": code_challenge,
+        "code_challenge_method": "S256",
+        "scope": " ".join(scopes),
+        # offline + consent are what make Google return a refresh_token.
+        "access_type": "offline",
+        "prompt": (oauth_cfg.get("prompt") or "consent").strip(),
+    }
+    login_hint = (oauth_cfg.get("login_hint") or "").strip()
+    if login_hint:
+        params["login_hint"] = login_hint
+    auth_url = f"{client['auth_uri']}?{urlencode(params)}"
+
+    AuthCodeTokenStore._prune_flows()
+    AuthCodeTokenStore._pending_flows[state] = {
+        "kind": "google",
+        "provider": provider,
+        "client_id": client["client_id"],
+        "client_secret": client["client_secret"],
+        "token_uri": client["token_uri"],
+        "token_file": (oauth_cfg.get("token_file") or "").strip(),
+        "scopes": scopes,
+        "code_verifier": code_verifier,
+        "redirect_uri": redirect_uri,
+        "created": time.time(),
+    }
+    pending_rest_auth[provider] = auth_url
+    print(
+        f"[mcpproxy] authorization required for provider '{provider}' — visit: {auth_url}",
+        flush=True,
+    )
+    return auth_url
+
+
+async def _complete_google(flow: dict[str, Any], code: str) -> str:
+    data = {
+        "grant_type": "authorization_code",
+        "code": code,
+        "redirect_uri": flow["redirect_uri"],
+        "client_id": flow["client_id"],
+        "code_verifier": flow["code_verifier"],
+    }
+    if flow.get("client_secret"):
+        data["client_secret"] = flow["client_secret"]
+    async with httpx.AsyncClient(timeout=HTTP_TIMEOUT) as client:
+        resp = await client.post(flow["token_uri"], data=data)
+        resp.raise_for_status()
+        payload = resp.json()
+
+    access = payload.get("access_token")
+    if not access:
+        raise RuntimeError(f"Token endpoint {flow['token_uri']} returned no access_token")
+
+    token_file = Path(flow["token_file"])
+    refresh = payload.get("refresh_token")
+    if not refresh:
+        # Google omits the refresh_token on silent re-approval; an earlier
+        # token file may still hold a valid one we can carry forward.
+        try:
+            refresh = json.loads(token_file.read_text(encoding="utf-8")).get("refresh_token")
+        except Exception:
+            refresh = None
+    if not refresh:
+        raise RuntimeError(
+            "Google returned no refresh_token. This usually means consent was "
+            "granted previously without prompt=consent — revoke the app's access "
+            "at https://myaccount.google.com/permissions and authorize again."
+        )
+
+    # Granted scopes (space-separated in the response) may differ from requested.
+    scope_str = (payload.get("scope") or "").strip()
+    scopes = scope_str.split() if scope_str else list(flow.get("scopes") or [])
+    expires_in = float(payload.get("expires_in", 3600))
+    expiry = datetime.datetime.fromtimestamp(
+        time.time() + expires_in, tz=datetime.timezone.utc
+    ).replace(tzinfo=None)  # naive UTC — the format Credentials.to_json() uses
+
+    # Exactly the shape google.oauth2.credentials.Credentials.to_json() emits,
+    # so from_authorized_user_file() loads it and refreshes transparently.
+    record = {
+        "token": access,
+        "refresh_token": refresh,
+        "token_uri": flow["token_uri"],
+        "client_id": flow["client_id"],
+        "client_secret": flow.get("client_secret") or "",
+        "scopes": scopes,
+        "universe_domain": "googleapis.com",
+        "account": "",
+        "expiry": expiry.isoformat(timespec="microseconds") + "Z",
+    }
+    token_file.parent.mkdir(parents=True, exist_ok=True)
+    token_file.write_text(json.dumps(record, indent=2), encoding="utf-8")
+    print(f"[mcpproxy] OAuth token written for provider '{flow['provider']}': {token_file}")
+
+    pending_rest_auth.pop(flow["provider"], None)
+    return access
+
+
+_BEGINNERS = {"google": _begin_google}
+_COMPLETERS = {"google": _complete_google}
+
+
+# ---------------------------------------------------------------------------
+# Startup warm-up
+# ---------------------------------------------------------------------------
+
+async def warm_provider(provider: str, oauth_cfg: dict[str, Any]) -> None:
+    """Surface the consent URL at startup when no usable token exists.
+
+    Best-effort: a refresh_token on disk counts as ready (the google libs
+    refresh at call time); anything else publishes the banner URL.  Never raises.
+    """
+    try:
+        status = token_status(oauth_cfg)
+        if status["has_refresh_token"]:
+            print(f"[mcpproxy] OAuth token ready for provider: {provider}")
+            return
+        begin_authorization(provider, oauth_cfg)
+    except Exception as exc:  # noqa: BLE001 — warm-up must not break startup
+        print(f"[mcpproxy] OAuth warm-up for provider '{provider}' did not complete: {exc}")
+        traceback.print_exc()
diff --git a/rest_provider.py b/rest_provider.py
index af7b515..0a8b039 100644
--- a/rest_provider.py
+++ b/rest_provider.py
@@ -345,6 +345,11 @@ async def complete_authorization(cls, state: str, code: str) -> str:
         flow = cls._pending_flows.pop(state, None)
         if flow is None:
             raise RuntimeError("Unknown or expired authorization state")
+        if flow.get("kind", "rest") != "rest":
+            # Provider-declared bootstrap flows (oauth: block, e.g. Google
+            # token files) share this registry/callback but complete elsewhere.
+            from oauth_bootstrap import complete_authorization as _complete_external
+            return await _complete_external(flow, code)
         auth = flow["auth"]
         data = {
             "grant_type": "authorization_code",
diff --git a/server.py b/server.py
index 340f1dd..a97328c 100755
--- a/server.py
+++ b/server.py
@@ -657,38 +657,29 @@ def register_builtin_tools() -> None:
 # at call time rather than preventing the whole server from coming up.
 
 def bootstrap_provider(provider_spec: dict[str, Any]) -> None:
-    """Register one provider and run its setup, in whichever order works.
+    """Run a provider's setup, then register it.  Never raises.
 
-    Registration normally runs first so a slow or failing build never blocks
-    the tools from being advertised.  But a code provider whose code block
-    imports its declared ``requirements`` at module level cannot exec until
-    they are pip-installed — so when registration fails we run setup and
-    retry once before giving up.  Never raises.
+    Setup (pip requirements / build / setup_commands) runs first because a
+    code provider whose code block imports its declared ``requirements`` at
+    module level cannot exec until they are installed.  A setup failure does
+    not block registration — the tools are still advertised and surface the
+    error at call time instead of keeping the whole server down.
     """
     source_path = provider_spec.get("_config_path", "<unknown>")
-    try:
-        register_provider(provider_spec)
-    except Exception as exc:
-        print(
-            f"register_provider failed for {source_path} ({exc}) — "
-            "running requirements/setup and retrying once"
-        )
-        try:
-            run_provider_setup(provider_spec)
-            register_provider(provider_spec)
-        except Exception as exc2:
-            print(f"Skipping provider {source_path} — register_provider failed: {exc2}")
-            traceback.print_exc()
-        return
     try:
         run_provider_setup(provider_spec)
     except Exception as exc:
         print(
             f"Provider {source_path}: setup failed ({exc}). "
-            "Tools are registered but their subprocess may not work until the "
+            "Tools will still be registered but may not work until the "
             "build / requirements / setup_commands are fixed (see the editor)."
         )
         traceback.print_exc()
+    try:
+        register_provider(provider_spec)
+    except Exception as exc:
+        print(f"Skipping provider {source_path} — register_provider failed: {exc}")
+        traceback.print_exc()
 
 
 for provider_spec in load_provider_specs(CONFIG_DIR):
@@ -803,6 +794,43 @@ async def _warm_all() -> None:
         traceback.print_exc()
 
 
+def _oauth_bootstrap_providers() -> list[tuple[str, dict[str, Any]]]:
+    """Return (provider_name, oauth_cfg) for every provider with an oauth: block."""
+    out: list[tuple[str, dict[str, Any]]] = []
+    for spec in load_provider_specs(CONFIG_DIR):
+        oauth_cfg = spec.get("oauth") or {}
+        if oauth_cfg.get("type"):
+            name = Path(spec.get("_config_path", "")).stem or "oauth"
+            out.append((name, oauth_cfg))
+    return out
+
+
+def _warm_oauth_providers() -> None:
+    """Check provider-declared OAuth token files once at startup.
+
+    A token file with a refresh_token counts as ready (the provider's own
+    client libraries refresh at call time).  Otherwise the consent URL is
+    published to the pending-auth banner so the user can authorize from the
+    UI before the first failed tool call.  Disable with MCPPROXY_WARM_REMOTE=0.
+    """
+    providers = _oauth_bootstrap_providers()
+    if not providers:
+        return
+    import asyncio
+
+    import oauth_bootstrap
+
+    async def _warm_all() -> None:
+        for name, oauth_cfg in providers:
+            await oauth_bootstrap.warm_provider(name, oauth_cfg)
+
+    try:
+        asyncio.run(_warm_all())
+    except Exception as exc:  # noqa: BLE001
+        print(f"_warm_oauth_providers error: {exc}")
+        traceback.print_exc()
+
+
 # ---------------------------------------------------------------------------
 # Entry point
 # ---------------------------------------------------------------------------
@@ -831,6 +859,10 @@ def _run_ui() -> None:
                 target=_warm_rest_providers, daemon=True, name="rest-warmup"
             )
             rest_warm_thread.start()
+            oauth_warm_thread = threading.Thread(
+                target=_warm_oauth_providers, daemon=True, name="oauth-warmup"
+            )
+            oauth_warm_thread.start()
         mcp.run(transport="streamable-http", host=MCP_HOST, port=MCP_PORT)
     except Exception as exc:
         print(f"main error: {exc}")
diff --git a/tests/test_frontend.py b/tests/test_frontend.py
index 4a6f39e..2cee9d6 100644
--- a/tests/test_frontend.py
+++ b/tests/test_frontend.py
@@ -1692,3 +1692,165 @@ def test_index_contains_files_and_tooltester_ui(self, client):
         for needle in ("files-modal", "tooltest-modal", "openFiles()", "openToolTester()",
                        "filesUpload", "ttInvoke"):
             assert needle in html, needle
+
+
+# ---------------------------------------------------------------------------
+# OAuth bootstrap (provider-declared oauth: block)
+# ---------------------------------------------------------------------------
+
+def _oauth_provider_yaml(tools_dir: Path, tmp_path: Path, name: str = "gmailish") -> dict:
+    cs = tmp_path / "client_secret.json"
+    cs.write_text(json.dumps({"installed": {
+        "client_id": "cid.apps.googleusercontent.com", "client_secret": "s",
+    }}))
+    spec = {
+        "code": "async def ping(context):\n    return 1\n",
+        "tools": [{"name": "ping", "function": "ping", "description": "Ping",
+                   "input_schema": {"type": "object", "properties": {}, "required": []}}],
+        "oauth": {
+            "type": "google",
+            "client_secret_file": str(cs),
+            "token_file": str(tmp_path / "secrets" / "token.json"),
+            "scopes": ["https://www.googleapis.com/auth/gmail.labels"],
+        },
+    }
+    (tools_dir / f"{name}.yaml").write_text(yaml.safe_dump(spec))
+    return spec
+
+
+@pytest.fixture(autouse=True)
+def _clear_oauth_flow_state():
+    import rest_provider
+    from rest_provider import AuthCodeTokenStore
+    rest_provider.pending_rest_auth.clear()
+    AuthCodeTokenStore._pending_flows.clear()
+    yield
+    rest_provider.pending_rest_auth.clear()
+    AuthCodeTokenStore._pending_flows.clear()
+
+
+class TestOauthBootstrap:
+    def test_begin_flow_happy_path(self, client, tools_dir, tmp_path):
+        _oauth_provider_yaml(tools_dir, tmp_path)
+        r = client.post("/api/oauth-bootstrap", json={"name": "gmailish"})
+        assert r.status_code == 200, r.text
+        data = r.json()
+        assert data["ok"] is True
+        assert "access_type=offline" in data["auth_url"]
+        assert "prompt=consent" in data["auth_url"]
+        assert data["redirect_uri"].endswith("/oauth/callback")
+        assert data["token"]["present"] is False
+        # published to the banner channel
+        import rest_provider
+        assert "gmailish" in rest_provider.pending_rest_auth
+
+    def test_unknown_provider_404(self, client):
+        r = client.post("/api/oauth-bootstrap", json={"name": "nope"})
+        assert r.status_code == 404
+
+    def test_provider_without_oauth_block_400(self, client, tools_dir):
+        (tools_dir / "plain.yaml").write_text(yaml.safe_dump({
+            "code": "async def f(context):\n    return 1\n",
+            "tools": [{"name": "f", "function": "f", "description": "x",
+                       "input_schema": {"type": "object", "properties": {}}}],
+        }))
+        r = client.post("/api/oauth-bootstrap", json={"name": "plain"})
+        assert r.status_code == 400
+
+    def test_missing_client_secret_returns_error(self, client, tools_dir, tmp_path):
+        spec = _oauth_provider_yaml(tools_dir, tmp_path)
+        spec["oauth"]["client_secret_file"] = str(tmp_path / "missing.json")
+        (tools_dir / "gmailish.yaml").write_text(yaml.safe_dump(spec))
+        r = client.post("/api/oauth-bootstrap", json={"name": "gmailish"})
+        assert r.status_code == 200
+        data = r.json()
+        assert data["ok"] is False
+        assert "not found" in data["error"]
+
+    def test_list_tools_exposes_token_state(self, client, tools_dir, tmp_path):
+        spec = _oauth_provider_yaml(tools_dir, tmp_path)
+        entry = next(p for p in client.get("/api/tools").json() if p["name"] == "gmailish")
+        assert entry["oauth"]["type"] == "google"
+        assert entry["oauth"]["has_refresh_token"] is False
+
+        token_file = Path(spec["oauth"]["token_file"])
+        token_file.parent.mkdir(parents=True)
+        token_file.write_text(json.dumps({"refresh_token": "rt", "expiry": "2030-01-01T00:00:00Z"}))
+        entry = next(p for p in client.get("/api/tools").json() if p["name"] == "gmailish")
+        assert entry["oauth"]["has_refresh_token"] is True
+        # providers without an oauth block expose null
+        (tools_dir / "plain.yaml").write_text(yaml.safe_dump({"tools": []}))
+        entry = next(p for p in client.get("/api/tools").json() if p["name"] == "plain")
+        assert entry["oauth"] is None
+
+    def test_structured_roundtrip_preserves_oauth(self, client, tools_dir, tmp_path):
+        _oauth_provider_yaml(tools_dir, tmp_path)
+        got = client.get("/api/tools/gmailish").json()
+        assert got["oauth"]["type"] == "google"
+        assert got["oauth"]["scopes"] == ["https://www.googleapis.com/auth/gmail.labels"]
+        # write it back through the editor path and re-read
+        r = client.put("/api/tools/gmailish", json={"provider": got})
+        assert r.status_code == 200, r.text
+        spec = yaml.safe_load((tools_dir / "gmailish.yaml").read_text())
+        assert spec["oauth"]["type"] == "google"
+        assert spec["oauth"]["client_secret_file"] == got["oauth"]["client_secret_file"]
+        assert spec["oauth"]["token_file"] == got["oauth"]["token_file"]
+        assert spec["oauth"]["scopes"] == got["oauth"]["scopes"]
+
+    def test_validation_errors(self, tmp_path):
+        from frontend.app import _validate_oauth
+        cs = tmp_path / "cs.json"
+        cs.write_text("{}")
+        base = {"oauth": {"type": "google", "client_secret_file": str(cs),
+                          "token_file": "/x/token.json", "scopes": ["a"]}}
+        assert _validate_oauth(base) == []
+        assert _validate_oauth({"oauth": {}}) == []  # no block → no errors
+
+        errs = _validate_oauth({"oauth": {"type": "github"}})
+        assert any("oauth.type" in e for e in errs)
+
+        errs = _validate_oauth({"oauth": {"type": "google"}})
+        assert any("client_secret_file" in e for e in errs)
+        assert any("token_file" in e for e in errs)
+        assert any("scopes" in e for e in errs)
+
+        missing = dict(base["oauth"], client_secret_file=str(tmp_path / "nope.json"))
+        errs = _validate_oauth({"oauth": missing})
+        assert any("not found" in e for e in errs)
+
+    def test_callback_completes_google_flow_and_writes_token(
+        self, client, tools_dir, tmp_path, monkeypatch
+    ):
+        import oauth_bootstrap
+        from rest_provider import AuthCodeTokenStore
+
+        spec = _oauth_provider_yaml(tools_dir, tmp_path)
+        r = client.post("/api/oauth-bootstrap", json={"name": "gmailish"})
+        assert r.json()["ok"] is True
+        state = next(iter(AuthCodeTokenStore._pending_flows))
+
+        class _Resp:
+            status_code = 200
+            def json(self):
+                return {"access_token": "at", "refresh_token": "rt", "expires_in": 3600}
+            def raise_for_status(self):
+                pass
+
+        class _Client:
+            def __init__(self, **kw): pass
+            async def __aenter__(self): return self
+            async def __aexit__(self, *exc): return False
+            async def post(self, url, data=None, **kw): return _Resp()
+
+        monkeypatch.setattr(oauth_bootstrap.httpx, "AsyncClient", _Client)
+        r = client.get(f"/oauth/callback?code=thecode&state={state}")
+        assert r.status_code == 200
+        assert "Authorization complete" in r.text
+        record = json.loads(Path(spec["oauth"]["token_file"]).read_text())
+        assert record["refresh_token"] == "rt"
+        assert record["client_id"] == "cid.apps.googleusercontent.com"
+
+    def test_html_contains_oauth_ui(self, client):
+        html = client.get("/").text
+        assert "oauth-bootstrap-btn" in html
+        assert "/api/oauth-bootstrap" in html
diff --git a/tests/test_oauth_bootstrap.py b/tests/test_oauth_bootstrap.py
new file mode 100644
index 0000000..fe1d423
--- /dev/null
+++ b/tests/test_oauth_bootstrap.py
@@ -0,0 +1,343 @@
+"""Unit tests for oauth_bootstrap — provider-declared Google OAuth bootstrap.
+
+HTTP is faked by patching ``oauth_bootstrap.httpx`` with a recording stub
+(same pattern as tests/test_rest_provider.py), so no network is touched.
+"""
+import asyncio
+import json
+from pathlib import Path
+from unittest.mock import AsyncMock, patch
+from urllib.parse import parse_qs, urlparse
+
+import pytest
+
+import oauth_bootstrap
+import rest_provider
+from oauth_bootstrap import (
+    begin_authorization,
+    complete_authorization,
+    load_client_secret,
+    token_status,
+    warm_provider,
+)
+from rest_provider import AuthCodeTokenStore
+
+
+class FakeResponse:
+    def __init__(self, status_code=200, json_data=None):
+        self.status_code = status_code
+        self._json = json_data
+
+    def json(self):
+        return self._json
+
+    def raise_for_status(self):
+        if self.status_code >= 400:
+            raise RuntimeError(f"HTTP {self.status_code}")
+
+
+class FakeAsyncClient:
+    def __init__(self, recorder, **kwargs):
+        self._recorder = recorder
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *exc):
+        return False
+
+    async def post(self, url, data=None, **kwargs):
+        self._recorder["calls"].append({"method": "POST", "url": url, "data": data})
+        return self._recorder["responses"].pop(0)
+
+
+@pytest.fixture()
+def http_recorder(monkeypatch):
+    recorder = {"calls": [], "responses": []}
+    monkeypatch.setattr(
+        oauth_bootstrap.httpx, "AsyncClient", lambda **kw: FakeAsyncClient(recorder, **kw)
+    )
+    return recorder
+
+
+@pytest.fixture(autouse=True)
+def _clear_flow_state():
+    rest_provider.pending_rest_auth.clear()
+    AuthCodeTokenStore._pending_flows.clear()
+    yield
+    rest_provider.pending_rest_auth.clear()
+    AuthCodeTokenStore._pending_flows.clear()
+
+
+@pytest.fixture()
+def client_secret_file(tmp_path: Path) -> Path:
+    path = tmp_path / "client_secret.json"
+    path.write_text(json.dumps({
+        "installed": {
+            "client_id": "abc.apps.googleusercontent.com",
+            "client_secret": "shhh",
+            "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+            "token_uri": "https://oauth2.googleapis.com/token",
+        }
+    }))
+    return path
+
+
+@pytest.fixture()
+def oauth_cfg(client_secret_file: Path, tmp_path: Path) -> dict:
+    return {
+        "type": "google",
+        "client_secret_file": str(client_secret_file),
+        "token_file": str(tmp_path / "secrets" / "gmail_token.json"),
+        "scopes": [
+            "https://www.googleapis.com/auth/gmail.settings.basic",
+            "https://www.googleapis.com/auth/gmail.labels",
+        ],
+    }
+
+
+# ---------------------------------------------------------------------------
+# load_client_secret
+# ---------------------------------------------------------------------------
+
+class TestLoadClientSecret:
+    def test_installed_key(self, client_secret_file):
+        out = load_client_secret(client_secret_file)
+        assert out["client_id"] == "abc.apps.googleusercontent.com"
+        assert out["client_secret"] == "shhh"
+        assert out["token_uri"] == "https://oauth2.googleapis.com/token"
+
+    def test_web_key_with_defaults(self, tmp_path):
+        path = tmp_path / "cs.json"
+        path.write_text(json.dumps({"web": {"client_id": "web-id", "client_secret": "s"}}))
+        out = load_client_secret(path)
+        assert out["client_id"] == "web-id"
+        assert out["auth_uri"] == oauth_bootstrap.GOOGLE_AUTH_URI
+        assert out["token_uri"] == oauth_bootstrap.GOOGLE_TOKEN_URI
+
+    def test_missing_file(self, tmp_path):
+        with pytest.raises(ValueError, match="not found"):
+            load_client_secret(tmp_path / "nope.json")
+
+    def test_garbage_json(self, tmp_path):
+        path = tmp_path / "cs.json"
+        path.write_text("{not json")
+        with pytest.raises(ValueError, match="not valid JSON"):
+            load_client_secret(path)
+
+    def test_neither_key(self, tmp_path):
+        path = tmp_path / "cs.json"
+        path.write_text(json.dumps({"other": {}}))
+        with pytest.raises(ValueError, match="installed"):
+            load_client_secret(path)
+
+    def test_missing_client_id(self, tmp_path):
+        path = tmp_path / "cs.json"
+        path.write_text(json.dumps({"installed": {"client_secret": "s"}}))
+        with pytest.raises(ValueError, match="client_id"):
+            load_client_secret(path)
+
+
+# ---------------------------------------------------------------------------
+# begin_authorization
+# ---------------------------------------------------------------------------
+
+class TestBeginGoogle:
+    def test_url_params_and_flow_registration(self, oauth_cfg):
+        url = begin_authorization("gmail-filters", oauth_cfg)
+        parsed = urlparse(url)
+        assert parsed.netloc == "accounts.google.com"
+        q = parse_qs(parsed.query)
+        assert q["access_type"] == ["offline"]
+        assert q["prompt"] == ["consent"]
+        assert q["code_challenge_method"] == ["S256"]
+        assert q["client_id"] == ["abc.apps.googleusercontent.com"]
+        assert q["scope"][0].split() == oauth_cfg["scopes"]
+        assert q["redirect_uri"][0].endswith("/oauth/callback")
+
+        state = q["state"][0]
+        flow = AuthCodeTokenStore._pending_flows[state]
+        assert flow["kind"] == "google"
+        assert flow["provider"] == "gmail-filters"
+        assert flow["token_file"] == oauth_cfg["token_file"]
+        assert rest_provider.pending_rest_auth["gmail-filters"] == url
+
+    def test_prompt_and_login_hint_overrides(self, oauth_cfg):
+        oauth_cfg["prompt"] = "select_account"
+        oauth_cfg["login_hint"] = "me@example.com"
+        url = begin_authorization("p", oauth_cfg)
+        q = parse_qs(urlparse(url).query)
+        assert q["prompt"] == ["select_account"]
+        assert q["login_hint"] == ["me@example.com"]
+
+    def test_unsupported_type(self):
+        with pytest.raises(ValueError, match="Unsupported oauth.type"):
+            begin_authorization("p", {"type": "github"})
+
+    def test_missing_client_secret_file_surfaces(self, oauth_cfg):
+        oauth_cfg["client_secret_file"] = "/does/not/exist.json"
+        with pytest.raises(ValueError, match="not found"):
+            begin_authorization("p", oauth_cfg)
+
+
+# ---------------------------------------------------------------------------
+# complete_authorization (google) — token exchange + token file
+# ---------------------------------------------------------------------------
+
+def _begin_and_get_flow(oauth_cfg, provider="gmail-filters"):
+    url = begin_authorization(provider, oauth_cfg)
+    state = parse_qs(urlparse(url).query)["state"][0]
+    return state, AuthCodeTokenStore._pending_flows[state]
+
+
+class TestCompleteGoogle:
+    def test_exchange_and_token_file(self, oauth_cfg, http_recorder):
+        state, flow = _begin_and_get_flow(oauth_cfg)
+        http_recorder["responses"].append(FakeResponse(json_data={
+            "access_token": "at-123",
+            "refresh_token": "rt-456",
+            "expires_in": 3600,
+            "scope": " ".join(oauth_cfg["scopes"]),
+        }))
+        access = asyncio.run(complete_authorization(flow, "the-code"))
+        assert access == "at-123"
+
+        call = http_recorder["calls"][0]
+        assert call["url"] == "https://oauth2.googleapis.com/token"
+        assert call["data"]["grant_type"] == "authorization_code"
+        assert call["data"]["code"] == "the-code"
+        assert call["data"]["client_id"] == "abc.apps.googleusercontent.com"
+        assert call["data"]["client_secret"] == "shhh"
+        assert call["data"]["code_verifier"] == flow["code_verifier"]
+        assert call["data"]["redirect_uri"].endswith("/oauth/callback")
+
+        record = json.loads(Path(oauth_cfg["token_file"]).read_text())
+        assert record["token"] == "at-123"
+        assert record["refresh_token"] == "rt-456"
+        assert record["token_uri"] == "https://oauth2.googleapis.com/token"
+        assert record["client_id"] == "abc.apps.googleusercontent.com"
+        assert record["client_secret"] == "shhh"
+        assert record["scopes"] == oauth_cfg["scopes"]
+        assert record["universe_domain"] == "googleapis.com"
+        assert record["expiry"].endswith("Z")
+        # pending banner entry cleared
+        assert "gmail-filters" not in rest_provider.pending_rest_auth
+
+    def test_token_file_loads_with_google_auth(self, oauth_cfg, http_recorder):
+        creds_mod = pytest.importorskip("google.oauth2.credentials")
+        _, flow = _begin_and_get_flow(oauth_cfg)
+        http_recorder["responses"].append(FakeResponse(json_data={
+            "access_token": "at", "refresh_token": "rt", "expires_in": 3600,
+        }))
+        asyncio.run(complete_authorization(flow, "c"))
+        creds = creds_mod.Credentials.from_authorized_user_file(oauth_cfg["token_file"])
+        assert creds.refresh_token == "rt"
+        assert creds.client_id == "abc.apps.googleusercontent.com"
+
+    def test_no_refresh_token_raises_with_consent_hint(self, oauth_cfg, http_recorder):
+        _, flow = _begin_and_get_flow(oauth_cfg)
+        http_recorder["responses"].append(FakeResponse(json_data={"access_token": "at"}))
+        with pytest.raises(RuntimeError, match="prompt=consent"):
+            asyncio.run(complete_authorization(flow, "c"))
+
+    def test_no_refresh_token_salvaged_from_prior_file(self, oauth_cfg, http_recorder):
+        prior = Path(oauth_cfg["token_file"])
+        prior.parent.mkdir(parents=True)
+        prior.write_text(json.dumps({"refresh_token": "rt-old"}))
+        _, flow = _begin_and_get_flow(oauth_cfg)
+        http_recorder["responses"].append(FakeResponse(json_data={"access_token": "at-new"}))
+        asyncio.run(complete_authorization(flow, "c"))
+        record = json.loads(prior.read_text())
+        assert record["token"] == "at-new"
+        assert record["refresh_token"] == "rt-old"
+
+    def test_unknown_kind(self):
+        with pytest.raises(RuntimeError, match="Unknown authorization flow kind"):
+            asyncio.run(complete_authorization({"kind": "mystery"}, "c"))
+
+
+# ---------------------------------------------------------------------------
+# Dispatch through AuthCodeTokenStore.complete_authorization (shared callback)
+# ---------------------------------------------------------------------------
+
+class TestCallbackDispatch:
+    def test_google_flow_routed_to_oauth_bootstrap(self, oauth_cfg):
+        state, _ = _begin_and_get_flow(oauth_cfg)
+        with patch("oauth_bootstrap.complete_authorization",
+                   new=AsyncMock(return_value="at")) as mock_complete:
+            out = asyncio.run(AuthCodeTokenStore.complete_authorization(state, "code-1"))
+        assert out == "at"
+        mock_complete.assert_awaited_once()
+        flow_arg, code_arg = mock_complete.await_args.args
+        assert flow_arg["kind"] == "google"
+        assert code_arg == "code-1"
+        # the flow is consumed
+        assert state not in AuthCodeTokenStore._pending_flows
+
+    def test_rest_flow_still_uses_old_path(self, monkeypatch, tmp_path):
+        # Regression: a flow without a "kind" follows the original REST exchange.
+        monkeypatch.setenv("CID", "client-id")
+        monkeypatch.setattr(rest_provider, "REST_AUTH_DIR", tmp_path)
+        store = AuthCodeTokenStore("restp", {
+            "client_id_env": "CID",
+            "authorize_url": "https://auth.example/authorize",
+            "token_url": "https://auth.example/token",
+        })
+        url = store.begin_authorization()
+        state = parse_qs(urlparse(url).query)["state"][0]
+
+        recorder = {"calls": [], "responses": [FakeResponse(json_data={
+            "access_token": "rest-at", "refresh_token": "rest-rt", "expires_in": 60,
+        })]}
+        monkeypatch.setattr(
+            rest_provider.httpx, "AsyncClient", lambda **kw: FakeAsyncClient(recorder, **kw)
+        )
+        out = asyncio.run(AuthCodeTokenStore.complete_authorization(state, "c"))
+        assert out == "rest-at"
+        assert recorder["calls"][0]["url"] == "https://auth.example/token"
+
+
+# ---------------------------------------------------------------------------
+# token_status / warm_provider
+# ---------------------------------------------------------------------------
+
+class TestTokenStatus:
+    def test_missing_file(self, oauth_cfg):
+        s = token_status(oauth_cfg)
+        assert s == {"token_file": oauth_cfg["token_file"], "present": False,
+                     "has_refresh_token": False, "expiry": None}
+
+    def test_file_without_refresh_token(self, oauth_cfg):
+        p = Path(oauth_cfg["token_file"])
+        p.parent.mkdir(parents=True)
+        p.write_text(json.dumps({"token": "at"}))
+        s = token_status(oauth_cfg)
+        assert s["present"] is True and s["has_refresh_token"] is False
+
+    def test_good_file(self, oauth_cfg):
+        p = Path(oauth_cfg["token_file"])
+        p.parent.mkdir(parents=True)
+        p.write_text(json.dumps({"refresh_token": "rt", "expiry": "2030-01-01T00:00:00Z"}))
+        s = token_status(oauth_cfg)
+        assert s["has_refresh_token"] is True
+        assert s["expiry"] == "2030-01-01T00:00:00Z"
+
+
+class TestWarmProvider:
+    def test_publishes_url_when_no_token(self, oauth_cfg):
+        asyncio.run(warm_provider("gmail-filters", oauth_cfg))
+        assert "gmail-filters" in rest_provider.pending_rest_auth
+
+    def test_noop_when_refresh_token_present(self, oauth_cfg):
+        p = Path(oauth_cfg["token_file"])
+        p.parent.mkdir(parents=True)
+        p.write_text(json.dumps({"refresh_token": "rt"}))
+        asyncio.run(warm_provider("gmail-filters", oauth_cfg))
+        assert "gmail-filters" not in rest_provider.pending_rest_auth
+
+    def test_never_raises_on_bad_config(self):
+        asyncio.run(warm_provider("p", {"type": "google",
+                                        "client_secret_file": "/missing.json",
+                                        "token_file": "/also/missing.json"}))
+        # bad config logs but must not raise or publish
+        assert "p" not in rest_provider.pending_rest_auth
diff --git a/tests/test_server.py b/tests/test_server.py
index 50ed863..e9066be 100644
--- a/tests/test_server.py
+++ b/tests/test_server.py
@@ -5,6 +5,7 @@
 import so zero tools are registered and no processes are started.
 """
 import inspect
+import json
 import os
 import textwrap
 from pathlib import Path
@@ -1145,7 +1146,7 @@ def test_timeout_constant_overridable_via_env(self, monkeypatch):
 
 
 # ---------------------------------------------------------------------------
-# bootstrap_provider — register/setup ordering and the missing-import retry
+# bootstrap_provider — setup runs before registration
 # ---------------------------------------------------------------------------
 
 from server import bootstrap_provider
@@ -1154,35 +1155,30 @@ def test_timeout_constant_overridable_via_env(self, monkeypatch):
 class TestBootstrapProvider:
     SPEC = {"_config_path": "/app/tools/demo.yaml"}
 
-    def test_happy_path_registers_then_runs_setup(self):
-        with patch("server.register_provider") as mock_reg, \
-             patch("server.run_provider_setup") as mock_setup:
+    def test_happy_path_runs_setup_then_registers(self):
+        order = []
+        with patch("server.register_provider",
+                   side_effect=lambda s: order.append("register")) as mock_reg, \
+             patch("server.run_provider_setup",
+                   side_effect=lambda s: order.append("setup")) as mock_setup:
             bootstrap_provider(self.SPEC)
         mock_reg.assert_called_once_with(self.SPEC)
         mock_setup.assert_called_once_with(self.SPEC)
+        # Setup first, so code blocks can import their declared requirements.
+        assert order == ["setup", "register"]
 
-    def test_setup_failure_does_not_raise_after_registration(self):
+    def test_setup_failure_still_registers(self):
         with patch("server.register_provider") as mock_reg, \
              patch("server.run_provider_setup", side_effect=RuntimeError("build failed")):
             bootstrap_provider(self.SPEC)  # must not raise
-        mock_reg.assert_called_once()
-
-    def test_register_failure_runs_setup_and_retries(self):
-        # A code provider importing its declared requirements at module level
-        # fails to exec before pip install — setup must run, then retry.
-        with patch("server.register_provider",
-                   side_effect=[ModuleNotFoundError("No module named 'google'"), None]) as mock_reg, \
-             patch("server.run_provider_setup") as mock_setup:
-            bootstrap_provider(self.SPEC)
-        assert mock_reg.call_count == 2
-        mock_setup.assert_called_once_with(self.SPEC)
+        mock_reg.assert_called_once_with(self.SPEC)
 
-    def test_register_failure_twice_skips_without_raising(self):
+    def test_register_failure_skips_without_raising(self):
         with patch("server.register_provider",
                    side_effect=ModuleNotFoundError("No module named 'google'")) as mock_reg, \
              patch("server.run_provider_setup") as mock_setup:
             bootstrap_provider(self.SPEC)  # must not raise
-        assert mock_reg.call_count == 2
+        mock_reg.assert_called_once()
         mock_setup.assert_called_once()
 
     def test_register_and_setup_failure_skips_without_raising(self):
@@ -1190,7 +1186,7 @@ def test_register_and_setup_failure_skips_without_raising(self):
                    side_effect=ModuleNotFoundError("No module named 'google'")) as mock_reg, \
              patch("server.run_provider_setup", side_effect=RuntimeError("pip failed")):
             bootstrap_provider(self.SPEC)  # must not raise
-        mock_reg.assert_called_once()  # retry never reached when setup fails
+        mock_reg.assert_called_once()
 
     def test_end_to_end_code_provider_with_missing_module(self, tmp_path):
         """Real exec path: code imports a module that 'pip install' makes available."""
@@ -1220,3 +1216,67 @@ def fake_pip(*args, **kwargs):
             tool_registry.clear()
             sys.path.remove(str(tmp_path))
             sys.modules.pop("fake_google_pkg", None)
+
+
+# ---------------------------------------------------------------------------
+# OAuth bootstrap warm-up
+# ---------------------------------------------------------------------------
+
+from server import _oauth_bootstrap_providers, _warm_oauth_providers
+
+
+class TestOauthWarmup:
+    def _write_provider(self, config_dir: Path, tmp_path: Path) -> dict:
+        cs = tmp_path / "client_secret.json"
+        cs.write_text(json.dumps({"installed": {"client_id": "cid", "client_secret": "s"}}))
+        spec = {
+            "code": "async def ping(context):\n    return 1\n",
+            "tools": [{"name": "ping", "function": "ping", "description": "",
+                       "input_schema": {"type": "object", "properties": {}}}],
+            "oauth": {
+                "type": "google",
+                "client_secret_file": str(cs),
+                "token_file": str(tmp_path / "token.json"),
+                "scopes": ["https://www.googleapis.com/auth/gmail.labels"],
+            },
+        }
+        (config_dir / "gmailish.yaml").write_text(yaml.safe_dump(spec))
+        return spec
+
+    def test_discovery_finds_oauth_block(self, tmp_path: Path, monkeypatch):
+        config_dir = tmp_path / "tools"
+        config_dir.mkdir()
+        self._write_provider(config_dir, tmp_path)
+        (config_dir / "plain.yaml").write_text(yaml.safe_dump({"tools": []}))
+        monkeypatch.setattr("server.CONFIG_DIR", config_dir)
+        found = _oauth_bootstrap_providers()
+        assert [(n, c["type"]) for n, c in found] == [("gmailish", "google")]
+
+    def test_warmup_publishes_url_when_token_missing(self, tmp_path: Path, monkeypatch):
+        import rest_provider
+        config_dir = tmp_path / "tools"
+        config_dir.mkdir()
+        self._write_provider(config_dir, tmp_path)
+        monkeypatch.setattr("server.CONFIG_DIR", config_dir)
+        rest_provider.pending_rest_auth.clear()
+        try:
+            _warm_oauth_providers()
+            assert "gmailish" in rest_provider.pending_rest_auth
+            assert "access_type=offline" in rest_provider.pending_rest_auth["gmailish"]
+        finally:
+            rest_provider.pending_rest_auth.clear()
+            rest_provider.AuthCodeTokenStore._pending_flows.clear()
+
+    def test_warmup_noop_when_refresh_token_present(self, tmp_path: Path, monkeypatch):
+        import rest_provider
+        config_dir = tmp_path / "tools"
+        config_dir.mkdir()
+        self._write_provider(config_dir, tmp_path)
+        (tmp_path / "token.json").write_text(json.dumps({"refresh_token": "rt"}))
+        monkeypatch.setattr("server.CONFIG_DIR", config_dir)
+        rest_provider.pending_rest_auth.clear()
+        try:
+            _warm_oauth_providers()
+            assert "gmailish" not in rest_provider.pending_rest_auth
+        finally:
+            rest_provider.pending_rest_auth.clear()

From 42526738bb7739e3da3b02b40db05fc2f03294d5 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 12 Jun 2026 11:31:56 +0000
Subject: [PATCH 2/2] Document the Files manager, Tool tester, and /v1/tools
 endpoints in the README

The file manager and tool tester shipped without README coverage, and
the OpenAI-compatible /v1/tools endpoints were only mentioned as a port
label. Adds Web UI subsections for both features (including the
MCPPROXY_MAX_UPLOAD_BYTES cap and the restart-to-populate registry
note) and documents the GET /v1/tools + POST /v1/tools/{name}/invoke
endpoints they build on.

https://claude.ai/code/session_01WnK1rtXGHDCNpsycAvxFqC
---
 README.md | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/README.md b/README.md
index 09906cf..9f4913d 100755
--- a/README.md
+++ b/README.md
@@ -125,6 +125,43 @@ The **🔑 Secrets** button (also available in the wizard's final step) reads al
 entries from the selected provider, shows which variables are already set in `.env`, and lets
 you fill in or update missing values — all without leaving the browser.
 
+### Files manager
+
+The **📁 Files** navbar button opens a file browser over the volume-mounted directories
+(`tools`, `files`, and `repos` — i.e. `/app/tools`, `/app/files`, `/app/repos` in the
+container). From the browser you can:
+
+- **Browse** with a root selector and clickable breadcrumb navigation
+- **📁 New folder** — create subdirectories (e.g. `tools/secrets/`)
+- **⬆ Upload** — drop one or more files into the current directory (e.g. a Google
+  `client_secret.json` for the [OAuth bootstrap](#oauth-token-file-bootstrap-oauth-block))
+- **Download** any file by clicking it
+- **🗑 Delete** files and directories (non-empty directories ask before deleting recursively)
+
+All paths are validated against the whitelisted roots (directory-traversal and
+symlink-escape attempts are rejected), and uploads stream to disk with a size cap
+(`MCPPROXY_MAX_UPLOAD_BYTES`, default 50 MB).
+
+### Tool tester
+
+The **🧪 Test Tools** navbar button lists every registered tool, grouped by provider,
+with a filter box. Selecting a tool generates an argument form straight from its JSON
+input schema — enums become dropdowns, booleans checkboxes, numbers/strings typed
+inputs, and objects/arrays a raw-JSON textarea — with required/optional badges,
+descriptions, and defaults pre-filled. **▶ Invoke** runs the tool and pretty-prints the
+result (with error styling on failure), so you can exercise a provider end-to-end
+without connecting an LLM client.
+
+The registry is populated at server startup, so after creating or editing a provider,
+restart and reopen the dialog (an empty list shows a one-click restart hint).
+
+Under the hood the tester uses the **OpenAI-compatible tools endpoints** on the UI port,
+which any OpenAI-style caller (e.g. OpenWebUI tool servers) can also use directly:
+
+- `GET /v1/tools` — every registered tool in OpenAI function-calling schema format
+- `POST /v1/tools/{tool_name}/invoke` — call a tool with `{"arguments": {...}}`;
+  returns `{"type": "tool_result", "content": [...], "is_error": bool}`
+
 ### Setup Commands
 
 Each provider has a **Setup Commands** list (editable in the editor panel, saved to YAML).