adloop 0.9.0__tar.gz → 0.10.0__tar.gz

{adloop-0.9.0 → adloop-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.9.0
+Version: 0.10.0
 Summary: The AI command center for Google Ads, GA4, and tracking code.
 Keywords: mcp,google-ads,google-analytics,ga4,cursor,marketing
 Author: Daniel Klose
@@ -196,12 +196,11 @@ AdLoop manages real ad spend, so safety is not optional.
 
 ## Setup
 
-> **⚠️ Built-in OAuth credentials are temporarily unavailable while Google verification is pending.**
-> Google limits unverified OAuth apps to 100 users, and AdLoop has reached that cap. New users will see a **"This app is blocked"** error if they pick the built-in option in the wizard.
+> **AdLoop uses your own (free) Google Cloud project for OAuth.** The `adloop init` wizard walks you through it — a one-time setup of about 5 minutes, with no shared user caps and no waiting on anyone's verification review. AdLoop does not ship built-in OAuth credentials.
 >
-> **What this means for you:** until Google completes verification, **bring your own Google Cloud project** — it takes ~5 minutes, has no user cap, and the `adloop init` wizard guides you through it. Status updates: [Discussion #13](https://github.com/kLOsk/adloop/discussions/13).
+> **Prefer zero setup?** [**AdLoop Cloud**](https://getadloop.com) is the hosted version: connect Google in two clicks — no Cloud project, no developer token, EU-hosted.
 >
-> *(Existing users whose tokens were already issued before the cap continue to work — only first-time sign-ins are blocked.)*
+> *(Upgrading from ≤0.9 with built-in credentials? Those sign-ins were retired in 0.10 — run `adloop init` once to switch to your own project.)*
 
 ### Install
 
@@ -223,7 +222,7 @@ uv run adloop init
 
 ### What `adloop init` does
 
-The wizard defaults to the "bring your own Google Cloud project" path while verification is pending. It walks you through:
+The wizard walks you through:
 
 1. **Google Cloud setup** — creates a project, enables the three APIs, generates an OAuth client (see [Custom Google Cloud Project Setup](#custom-google-cloud-project-setup) below for the exact steps the wizard refers you to)
 2. **Developer token** — from your Google Ads MCC ([API Center](https://ads.google.com/aw/apicenter))
@@ -233,8 +232,6 @@ The wizard defaults to the "bring your own Google Cloud project" path while veri
 6. **Safety defaults** — budget cap and dry-run preference
 7. **Editor config snippets** — prints MCP configuration for both Cursor and Claude Code
 
-The wizard does still offer AdLoop's built-in credentials as a non-default option for existing users whose tokens predate the cap. Picking that option for a brand-new Google account will fail at the consent screen — the wizard warns you about this before you choose.
-
 ### Requirements
 
 - Python 3.11+
@@ -243,7 +240,7 @@ The wizard does still offer AdLoop's built-in credentials as a non-default optio
 
 ### Google Ads Developer Token
 
-A developer token is **always required** — even when using AdLoop's built-in OAuth credentials. The built-in credentials handle Google sign-in; the developer token is a separate key that grants API access to your Google Ads data.
+A developer token is **always required**. Your OAuth client handles Google sign-in; the developer token is a separate key that grants API access to your Google Ads data.
 
 1. **Create an MCC** (free) at [ads.google.com/home/tools/manager-accounts](https://ads.google.com/home/tools/manager-accounts/) if you don't have one. Link your regular Google Ads account to it.
 2. In the MCC, go to **Tools & Settings → API Center**
@@ -265,7 +262,7 @@ Running on a server without a browser (VMs, Docker, SSH)? The wizard automatical
 
 ### Custom Google Cloud Project Setup
 
-This is the default path while built-in credentials are blocked by Google's 100-user cap. The wizard refers to these steps — do them in your browser before running `adloop init` (or while it waits at the OAuth prompt).
+The wizard refers to these steps — do them in your browser before running `adloop init` (or while it waits at the OAuth prompt).
 
 #### Step 1 — Google Cloud Project
 
@@ -358,7 +355,7 @@ All configuration lives in `~/.adloop/config.yaml`. See [`config.yaml.example`](
 | Section | Key | Default | Description |
 |---------|-----|---------|-------------|
 | `google` | `project_id` | *(empty)* | Google Cloud project ID (only needed with custom credentials) |
-| `google` | `credentials_path` | *(empty — uses built-in)* | Path to OAuth client JSON or service account key. Leave empty to use AdLoop's built-in credentials. |
+| `google` | `credentials_path` | *(empty)* | Path to OAuth client JSON or service account key. Empty = `~/.adloop/credentials.json`, else Application Default Credentials. |
 | `google` | `token_path` | `~/.adloop/token.json` | Where to store the OAuth token (auto-created) |
 | `ga4` | `property_id` | — | Your GA4 property ID (auto-discovered by `adloop init`) |
 | `ads` | `developer_token` | — | Your Google Ads API developer token |
@@ -375,7 +372,7 @@ src/adloop/
 ├── __init__.py        # Entry point — routes 'adloop init' to wizard, otherwise starts MCP server
 ├── server.py          # FastMCP server — 43 tool registrations with safety annotations
 ├── config.py          # Config loader (~/.adloop/config.yaml)
-├── auth.py            # OAuth 2.0 flow (bundled + custom credentials, headless fallback) + service accounts
+├── auth.py            # OAuth 2.0 flow (user-supplied credentials, headless fallback) + service accounts
 ├── cli.py             # Interactive 'adloop init' setup wizard
 ├── crossref.py        # Cross-reference tools (GA4 + Ads combined analysis)
 ├── tracking.py        # Tracking validation + code generation tools
@@ -411,7 +408,7 @@ What's been shipped and what's next:
 - ~~Claude Code support~~ ✓ — `CLAUDE.md`, `.mcp.json`, `.claude/rules/`, `.claude/commands/`, CLI wizard snippets
 - **Claude Desktop one-click install** — `adloop install claude-desktop` (and/or a `.dxt` extension bundle) that writes the AdLoop MCP entry into `claude_desktop_config.json` automatically, so Claude Desktop + Cowork users don't have to hand-edit JSON
 - ~~PyPI package~~ ✓ — `pip install adloop`
-- ~~Bundled OAuth credentials~~ ✓ — no Google Cloud project required (**currently blocked at 100-user cap** pending Google verification; `adloop init` defaults to the [Custom Google Cloud Project Setup](#custom-google-cloud-project-setup) path until verification completes)
+- **[AdLoop Cloud](https://getadloop.com)** — the hosted version: no Google Cloud project, no developer token, connect Google in two clicks (EU-hosted, GDPR-first)
 - ~~Headless server support~~ ✓ — manual URL copy-paste flow for servers without a browser
 - ~~Behavioral eval suites~~ ✓ — 28 prompt-and-expectation tests covering read, write, tracking, and planning workflows
 - **Community launch** — HN, Indie Hackers, r/cursor, Twitter

{adloop-0.9.0 → adloop-0.10.0}/README.md

@@ -172,12 +172,11 @@ AdLoop manages real ad spend, so safety is not optional.
 
 ## Setup
 
-> **⚠️ Built-in OAuth credentials are temporarily unavailable while Google verification is pending.**
-> Google limits unverified OAuth apps to 100 users, and AdLoop has reached that cap. New users will see a **"This app is blocked"** error if they pick the built-in option in the wizard.
+> **AdLoop uses your own (free) Google Cloud project for OAuth.** The `adloop init` wizard walks you through it — a one-time setup of about 5 minutes, with no shared user caps and no waiting on anyone's verification review. AdLoop does not ship built-in OAuth credentials.
 >
-> **What this means for you:** until Google completes verification, **bring your own Google Cloud project** — it takes ~5 minutes, has no user cap, and the `adloop init` wizard guides you through it. Status updates: [Discussion #13](https://github.com/kLOsk/adloop/discussions/13).
+> **Prefer zero setup?** [**AdLoop Cloud**](https://getadloop.com) is the hosted version: connect Google in two clicks — no Cloud project, no developer token, EU-hosted.
 >
-> *(Existing users whose tokens were already issued before the cap continue to work — only first-time sign-ins are blocked.)*
+> *(Upgrading from ≤0.9 with built-in credentials? Those sign-ins were retired in 0.10 — run `adloop init` once to switch to your own project.)*
 
 ### Install
 
@@ -199,7 +198,7 @@ uv run adloop init
 
 ### What `adloop init` does
 
-The wizard defaults to the "bring your own Google Cloud project" path while verification is pending. It walks you through:
+The wizard walks you through:
 
 1. **Google Cloud setup** — creates a project, enables the three APIs, generates an OAuth client (see [Custom Google Cloud Project Setup](#custom-google-cloud-project-setup) below for the exact steps the wizard refers you to)
 2. **Developer token** — from your Google Ads MCC ([API Center](https://ads.google.com/aw/apicenter))
@@ -209,8 +208,6 @@ The wizard defaults to the "bring your own Google Cloud project" path while veri
 6. **Safety defaults** — budget cap and dry-run preference
 7. **Editor config snippets** — prints MCP configuration for both Cursor and Claude Code
 
-The wizard does still offer AdLoop's built-in credentials as a non-default option for existing users whose tokens predate the cap. Picking that option for a brand-new Google account will fail at the consent screen — the wizard warns you about this before you choose.
-
 ### Requirements
 
 - Python 3.11+
@@ -219,7 +216,7 @@ The wizard does still offer AdLoop's built-in credentials as a non-default optio
 
 ### Google Ads Developer Token
 
-A developer token is **always required** — even when using AdLoop's built-in OAuth credentials. The built-in credentials handle Google sign-in; the developer token is a separate key that grants API access to your Google Ads data.
+A developer token is **always required**. Your OAuth client handles Google sign-in; the developer token is a separate key that grants API access to your Google Ads data.
 
 1. **Create an MCC** (free) at [ads.google.com/home/tools/manager-accounts](https://ads.google.com/home/tools/manager-accounts/) if you don't have one. Link your regular Google Ads account to it.
 2. In the MCC, go to **Tools & Settings → API Center**
@@ -241,7 +238,7 @@ Running on a server without a browser (VMs, Docker, SSH)? The wizard automatical
 
 ### Custom Google Cloud Project Setup
 
-This is the default path while built-in credentials are blocked by Google's 100-user cap. The wizard refers to these steps — do them in your browser before running `adloop init` (or while it waits at the OAuth prompt).
+The wizard refers to these steps — do them in your browser before running `adloop init` (or while it waits at the OAuth prompt).
 
 #### Step 1 — Google Cloud Project
 
@@ -334,7 +331,7 @@ All configuration lives in `~/.adloop/config.yaml`. See [`config.yaml.example`](
 | Section | Key | Default | Description |
 |---------|-----|---------|-------------|
 | `google` | `project_id` | *(empty)* | Google Cloud project ID (only needed with custom credentials) |
-| `google` | `credentials_path` | *(empty — uses built-in)* | Path to OAuth client JSON or service account key. Leave empty to use AdLoop's built-in credentials. |
+| `google` | `credentials_path` | *(empty)* | Path to OAuth client JSON or service account key. Empty = `~/.adloop/credentials.json`, else Application Default Credentials. |
 | `google` | `token_path` | `~/.adloop/token.json` | Where to store the OAuth token (auto-created) |
 | `ga4` | `property_id` | — | Your GA4 property ID (auto-discovered by `adloop init`) |
 | `ads` | `developer_token` | — | Your Google Ads API developer token |
@@ -351,7 +348,7 @@ src/adloop/
 ├── __init__.py        # Entry point — routes 'adloop init' to wizard, otherwise starts MCP server
 ├── server.py          # FastMCP server — 43 tool registrations with safety annotations
 ├── config.py          # Config loader (~/.adloop/config.yaml)
-├── auth.py            # OAuth 2.0 flow (bundled + custom credentials, headless fallback) + service accounts
+├── auth.py            # OAuth 2.0 flow (user-supplied credentials, headless fallback) + service accounts
 ├── cli.py             # Interactive 'adloop init' setup wizard
 ├── crossref.py        # Cross-reference tools (GA4 + Ads combined analysis)
 ├── tracking.py        # Tracking validation + code generation tools
@@ -387,7 +384,7 @@ What's been shipped and what's next:
 - ~~Claude Code support~~ ✓ — `CLAUDE.md`, `.mcp.json`, `.claude/rules/`, `.claude/commands/`, CLI wizard snippets
 - **Claude Desktop one-click install** — `adloop install claude-desktop` (and/or a `.dxt` extension bundle) that writes the AdLoop MCP entry into `claude_desktop_config.json` automatically, so Claude Desktop + Cowork users don't have to hand-edit JSON
 - ~~PyPI package~~ ✓ — `pip install adloop`
-- ~~Bundled OAuth credentials~~ ✓ — no Google Cloud project required (**currently blocked at 100-user cap** pending Google verification; `adloop init` defaults to the [Custom Google Cloud Project Setup](#custom-google-cloud-project-setup) path until verification completes)
+- **[AdLoop Cloud](https://getadloop.com)** — the hosted version: no Google Cloud project, no developer token, connect Google in two clicks (EU-hosted, GDPR-first)
 - ~~Headless server support~~ ✓ — manual URL copy-paste flow for servers without a browser
 - ~~Behavioral eval suites~~ ✓ — 28 prompt-and-expectation tests covering read, write, tracking, and planning workflows
 - **Community launch** — HN, Indie Hackers, r/cursor, Twitter

{adloop-0.9.0 → adloop-0.10.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "adloop"
-version = "0.9.0"
+version = "0.10.0"
 description = "The AI command center for Google Ads, GA4, and tracking code."
 readme = "README.md"
 authors = [

{adloop-0.9.0 → adloop-0.10.0}/src/adloop/__init__.py

@@ -42,6 +42,15 @@ def main() -> None:
             sys.exit(130)
         return
 
+    # Process-global side effects (signal handlers, heartbeat thread, and
+    # the stdio cancellation-race monkeypatch) are deliberately installed
+    # here — in the stdio entry point — rather than at adloop.server import
+    # time, so embedding the server in an ASGI app stays side-effect-free.
+    from adloop import _mcp_patches, diagnostics
+
+    diagnostics.install()
+    _mcp_patches.install()
+
     from adloop.server import mcp
 
     mcp.run()

{adloop-0.9.0 → adloop-0.10.0}/src/adloop/ads/gaql.py

@@ -89,7 +89,29 @@ _GAQL_ERROR_HINTS = {
 
 
 def _parse_gaql_error(exc: Exception) -> str:
-    """Extract a human-readable message from Google Ads gRPC errors."""
+    """Extract a human-readable message from Google Ads gRPC errors.
+
+    Prefers the structured ``failure.errors[]`` a GoogleAdsException
+    carries — Google's own message names the exact field/clause at
+    fault (e.g. PROHIBITED_FIELD_IN_SELECT_CLAUSE with the field name),
+    which is far more actionable than a generic hint. Known error codes
+    still get the hint appended as a suffix.
+    """
+    failure = getattr(exc, "failure", None)
+    errors = getattr(failure, "errors", None) if failure is not None else None
+    if errors:
+        parts = []
+        for err in errors:
+            code = str(getattr(err, "error_code", "") or "").strip()
+            message = str(getattr(err, "message", "") or "").strip()
+            parts.append(" — ".join(p for p in (code, message) if p))
+        detail = " | ".join(p for p in parts if p)
+        if detail:
+            for known, hint in _GAQL_ERROR_HINTS.items():
+                if known in detail:
+                    return f"{detail} (hint: {hint})"
+            return detail
+
     raw = str(exc)
     for code, hint in _GAQL_ERROR_HINTS.items():
         if code in raw:
@@ -137,6 +159,21 @@ def _to_python(obj: object) -> object:
     # AdTextAsset and similar message types
     if hasattr(obj, "text") and isinstance(getattr(obj, "text", None), str):
         return obj.text
+    # Nested proto-plus messages (targeting settings, criteria, ...) —
+    # serialize to a dict instead of collapsing to their str() repr.
+    try:
+        import proto
+
+        if isinstance(obj, proto.Message):
+            return type(obj).to_dict(
+                obj, preserving_proto_field_name=True, use_integers_for_enums=False
+            )
+    except ImportError:
+        pass
+    if hasattr(obj, "DESCRIPTOR"):
+        from google.protobuf.json_format import MessageToDict
+
+        return MessageToDict(obj, preserving_proto_field_name=True)
     return str(obj)
 
 

{adloop-0.9.0 → adloop-0.10.0}/src/adloop/ads/write.py

@@ -71,6 +71,79 @@ def _normalize_rsa_assets(items: list) -> list[dict]:
 # ---------------------------------------------------------------------------
 
 
+def _ssrf_error(url: str) -> str | None:
+    """Reject URLs that would make the validation fetch reach non-public hosts.
+
+    User-supplied URLs are fetched from the machine running AdLoop; on a
+    hosted multi-tenant server that request originates inside our network,
+    so private/loopback/link-local/metadata targets must be refused. Ads
+    pointing at such addresses could never serve anyway. Returns an error
+    string, or None if the URL looks safe to fetch.
+
+    Note: the fetch re-resolves DNS after this check, so a hostile DNS
+    server could still rebind between check and fetch — acceptable here
+    because the fetch result is only an up/down signal, never returned
+    to the caller.
+    """
+    import ipaddress
+    import socket
+    from urllib.parse import urlparse
+
+    try:
+        parsed = urlparse(url)
+    except ValueError as e:
+        return f"unparseable URL: {e}"
+
+    if parsed.scheme not in ("http", "https"):
+        return f"unsupported URL scheme '{parsed.scheme}' (only http/https)"
+
+    host = parsed.hostname
+    if not host:
+        return "URL has no hostname"
+
+    try:
+        addresses = [ipaddress.ip_address(host)]
+    except ValueError:
+        try:
+            addr_info = socket.getaddrinfo(host, None)
+        except OSError as e:
+            return f"hostname does not resolve: {e}"
+        addresses = [
+            ipaddress.ip_address(info[4][0]) for info in addr_info
+        ]
+
+    for addr in addresses:
+        if (
+            addr.is_private
+            or addr.is_loopback
+            or addr.is_link_local
+            or addr.is_multicast
+            or addr.is_reserved
+            or addr.is_unspecified
+        ):
+            return (
+                f"URL resolves to a non-public address ({addr}) — "
+                "refusing to fetch"
+            )
+
+    return None
+
+
+def _build_public_only_opener():
+    """Return a urllib opener that re-checks every redirect hop for SSRF."""
+    import urllib.error
+    import urllib.request
+
+    class _PublicOnlyRedirectHandler(urllib.request.HTTPRedirectHandler):
+        def redirect_request(self, req, fp, code, msg, headers, newurl):
+            err = _ssrf_error(newurl)
+            if err is not None:
+                raise urllib.error.URLError(f"redirect blocked: {err}")
+            return super().redirect_request(req, fp, code, msg, headers, newurl)
+
+    return urllib.request.build_opener(_PublicOnlyRedirectHandler)
+
+
 def _validate_urls(urls: list[str], timeout: int = 10) -> dict[str, str | None]:
     """Check that each URL returns a 2xx/3xx status.
 
@@ -79,14 +152,20 @@ def _validate_urls(urls: list[str], timeout: int = 10) -> dict[str, str | None]:
     import urllib.request
     import urllib.error
 
+    opener = _build_public_only_opener()
+
     results = {}
     for url in urls:
         if not url:
             continue
+        ssrf = _ssrf_error(url)
+        if ssrf is not None:
+            results[url] = ssrf
+            continue
         try:
             req = urllib.request.Request(url, method="HEAD")
             req.add_header("User-Agent", "AdLoop-URLCheck/1.0")
-            resp = urllib.request.urlopen(req, timeout=timeout)
+            resp = opener.open(req, timeout=timeout)
             if resp.status >= 400:
                 results[url] = f"HTTP {resp.status}"
             else:
@@ -97,7 +176,7 @@ def _validate_urls(urls: list[str], timeout: int = 10) -> dict[str, str | None]:
                 try:
                     req = urllib.request.Request(url, method="GET")
                     req.add_header("User-Agent", "AdLoop-URLCheck/1.0")
-                    resp = urllib.request.urlopen(req, timeout=timeout)
+                    resp = opener.open(req, timeout=timeout)
                     if resp.status >= 400:
                         results[url] = f"HTTP {resp.status}"
                     else:
@@ -1221,9 +1300,19 @@ def draft_image_assets(
     image_paths: list[str] | None = None,
 ) -> dict:
     """Draft campaign image assets from local files."""
+    from adloop.runtime import deployment_mode
     from adloop.safety.guards import SafetyViolation, check_blocked_operation
     from adloop.safety.preview import ChangePlan, store_plan
 
+    if deployment_mode() == "server":
+        return {
+            "error": (
+                "draft_image_assets reads image files from the local "
+                "filesystem and is not available on the hosted server. "
+                "Use the self-hosted AdLoop MCP server for image assets."
+            )
+        }
+
     try:
         check_blocked_operation("create_image_assets", config.safety)
     except SafetyViolation as e:
@@ -3146,11 +3235,14 @@ def _apply_attach_shared_set_to_campaigns(
         css.shared_set = shared_set_resource
         operations.append(op)
 
-    response = css_service.mutate_campaign_shared_sets(
-        customer_id=cid,
-        operations=operations,
-        partial_failure=True,
-    )
+    # CampaignSharedSetService.mutate_campaign_shared_sets does NOT accept a
+    # flattened ``partial_failure`` kwarg (unlike GoogleAdsService.mutate);
+    # it must be set on the request object.
+    request = client.get_type("MutateCampaignSharedSetsRequest")
+    request.customer_id = cid
+    request.operations.extend(operations)
+    request.partial_failure = True
+    response = css_service.mutate_campaign_shared_sets(request=request)
 
     pf_error = getattr(response, "partial_failure_error", None)
     per_op_errors = _parse_partial_failure_per_op(client, pf_error)
@@ -3213,11 +3305,13 @@ def _apply_detach_shared_set_from_campaigns(
         )
         operations.append(op)
 
-    response = css_service.mutate_campaign_shared_sets(
-        customer_id=cid,
-        operations=operations,
-        partial_failure=True,
-    )
+    # partial_failure must be set on the request object — the flattened
+    # kwarg is not supported by CampaignSharedSetService (see attach above).
+    request = client.get_type("MutateCampaignSharedSetsRequest")
+    request.customer_id = cid
+    request.operations.extend(operations)
+    request.partial_failure = True
+    response = css_service.mutate_campaign_shared_sets(request=request)
 
     pf_error = getattr(response, "partial_failure_error", None)
     per_op_errors = _parse_partial_failure_per_op(client, pf_error)

{adloop-0.9.0 → adloop-0.10.0}/src/adloop/auth.py

@@ -1,10 +1,19 @@
-"""Google API authentication — OAuth 2.0 and service account support."""
+"""Google API authentication — OAuth 2.0 and service account support.
+
+Credential acquisition is pluggable: :class:`LocalFileCredentialsProvider`
+implements the OSS behavior (credentials.json chain, ``~/.adloop/token.json``,
+interactive browser flow), and a hosted deployment swaps in its own provider
+via :func:`set_credentials_provider` (e.g. tokens from an encrypted database,
+refreshed out-of-band). All client construction goes through the module-level
+:func:`get_ga4_credentials` / :func:`get_ads_credentials`, which delegate to
+the active provider.
+"""
 
 from __future__ import annotations
 
-import importlib.resources
+import sys
 from pathlib import Path
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Protocol
 
 if TYPE_CHECKING:
     from google.auth.credentials import Credentials
@@ -30,62 +39,85 @@ _ADS_SCOPES = [
 ]
 
 
-def _get_credentials_path(config: AdLoopConfig) -> Path | None:
-    """Resolve OAuth client credentials using a priority chain.
+class CredentialsProvider(Protocol):
+    """Source of authenticated Google credentials for the current context."""
 
-    1. User-provided credentials_path in config (if non-empty and file exists)
-    2. ~/.adloop/credentials.json (if file exists — legacy or manually placed)
-    3. Bundled credentials shipped with the package
-    4. None (caller falls back to Application Default Credentials)
+    def ga4_credentials(self, config: AdLoopConfig) -> Credentials: ...
+
+    def ads_credentials(self, config: AdLoopConfig) -> Credentials: ...
+
+
+class LocalFileCredentialsProvider:
+    """OSS default: local credential files + interactive OAuth.
+
+    Refuses to run in server mode — falling back to the operator's own
+    ``~/.adloop`` tokens in a multi-tenant process would silently serve
+    one tenant's request with another identity's credentials.
     """
-    if config.google.credentials_path:
-        user_path = Path(config.google.credentials_path).expanduser()
-        if user_path.exists():
-            return user_path
 
-    local_path = Path("~/.adloop/credentials.json").expanduser()
-    if local_path.exists():
-        return local_path
+    def _guard_local_only(self) -> None:
+        from adloop.runtime import deployment_mode
 
-    try:
-        ref = importlib.resources.files("adloop").joinpath("bundled_credentials.json")
-        with importlib.resources.as_file(ref) as bundled:
-            if bundled.exists():
-                return Path(bundled)
-    except (FileNotFoundError, TypeError):
-        pass
+        if deployment_mode() == "server":
+            raise RuntimeError(
+                "LocalFileCredentialsProvider cannot be used in server mode. "
+                "The hosted deployment must install its own provider via "
+                "adloop.auth.set_credentials_provider() at startup."
+            )
 
-    return None
+    def ga4_credentials(self, config: AdLoopConfig) -> Credentials:
+        self._guard_local_only()
+        return _local_credentials(config, _GA4_SCOPES)
 
+    def ads_credentials(self, config: AdLoopConfig) -> Credentials:
+        self._guard_local_only()
+        return _local_credentials(config, _ADS_SCOPES)
 
-def get_ga4_credentials(config: AdLoopConfig) -> Credentials:
-    """Return authenticated credentials for GA4 APIs."""
-    creds_path = _get_credentials_path(config)
 
-    if creds_path is not None:
-        import json
+_active_provider: CredentialsProvider = LocalFileCredentialsProvider()
 
-        with open(creds_path) as f:
-            creds_info = json.load(f)
 
-        if creds_info.get("type") == "service_account":
-            from google.oauth2 import service_account
+def set_credentials_provider(provider: CredentialsProvider) -> None:
+    """Swap the credentials provider (hosted deployments call this once)."""
+    global _active_provider
+    _active_provider = provider
 
-            return service_account.Credentials.from_service_account_file(
-                str(creds_path),
-                scopes=_GA4_SCOPES,
-            )
 
-        return _oauth_flow(config, creds_path)
+def get_credentials_provider() -> CredentialsProvider:
+    return _active_provider
 
-    import google.auth
 
-    credentials, _ = google.auth.default(scopes=_GA4_SCOPES)
-    return credentials
+def get_ga4_credentials(config: AdLoopConfig) -> Credentials:
+    """Return authenticated credentials for GA4 APIs."""
+    return _active_provider.ga4_credentials(config)
 
 
 def get_ads_credentials(config: AdLoopConfig) -> Credentials:
     """Return authenticated credentials for Google Ads API."""
+    return _active_provider.ads_credentials(config)
+
+
+def _get_credentials_path(config: AdLoopConfig) -> Path | None:
+    """Resolve OAuth client credentials using a priority chain.
+
+    1. User-provided credentials_path in config (if non-empty and file exists)
+    2. ~/.adloop/credentials.json (if file exists — the wizard's default spot)
+    3. None (caller falls back to Application Default Credentials)
+    """
+    if config.google.credentials_path:
+        user_path = Path(config.google.credentials_path).expanduser()
+        if user_path.exists():
+            return user_path
+
+    local_path = Path("~/.adloop/credentials.json").expanduser()
+    if local_path.exists():
+        return local_path
+
+    return None
+
+
+def _local_credentials(config: AdLoopConfig, scopes: list[str]) -> Credentials:
+    """Resolve credentials from local files (service account or OAuth)."""
     creds_path = _get_credentials_path(config)
 
     if creds_path is not None:
@@ -99,14 +131,22 @@ def get_ads_credentials(config: AdLoopConfig) -> Credentials:
 
             return service_account.Credentials.from_service_account_file(
                 str(creds_path),
-                scopes=_ADS_SCOPES,
+                scopes=scopes,
             )
 
         return _oauth_flow(config, creds_path)
 
     import google.auth
 
-    credentials, _ = google.auth.default(scopes=_ADS_SCOPES)
+    try:
+        credentials, _ = google.auth.default(scopes=scopes)
+    except Exception as exc:
+        raise RuntimeError(
+            "No Google OAuth credentials found. Run `adloop init` to set up "
+            "your own Google Cloud project, or place your OAuth client JSON "
+            "at ~/.adloop/credentials.json. Prefer zero setup? AdLoop Cloud "
+            "handles credentials for you: https://getadloop.com"
+        ) from exc
     return credentials
 
 
@@ -119,7 +159,9 @@ def _oauth_flow(
     GA4 and Ads auth sharing the same token_path.
 
     Falls back to a manual copy-paste flow when no browser is available
-    (headless servers, Docker containers, SSH sessions).
+    (headless servers, Docker containers, SSH sessions) — but only when
+    attached to a real terminal; under a stdio MCP server stdin/stdout
+    belong to the JSON-RPC stream and must not be touched.
     """
     from google.auth.transport.requests import Request
     from google.oauth2.credentials import Credentials as OAuthCredentials
@@ -172,13 +214,36 @@ def _oauth_flow(
     return creds
 
 
+def _is_interactive_terminal() -> bool:
+    """True when stdin AND stdout are real TTYs (a human at a terminal).
+
+    Under a stdio MCP server both are pipes carrying JSON-RPC frames —
+    printing prompts or reading input there corrupts the protocol stream.
+    """
+    try:
+        return sys.stdin.isatty() and sys.stdout.isatty()
+    except (AttributeError, ValueError):
+        return False
+
+
 def _run_oauth_with_fallback(flow: object) -> Credentials:
     """Try browser-based OAuth; fall back to manual URL copy-paste for headless."""
+    interactive = _is_interactive_terminal()
     try:
-        return flow.run_local_server(port=0)  # type: ignore[union-attr]
+        # Suppress the library's stdout prompt unless a human terminal is
+        # attached — under stdio transport, stdout is the JSON-RPC stream.
+        kwargs = {} if interactive else {"authorization_prompt_message": ""}
+        return flow.run_local_server(port=0, **kwargs)  # type: ignore[union-attr]
     except Exception:
         pass
 
+    if not interactive:
+        raise RuntimeError(
+            "OAuth authorization is required but no browser could be opened "
+            "and no interactive terminal is attached. Run 'adloop init' in a "
+            "terminal to complete authorization, then retry."
+        )
+
     auth_url, _ = flow.authorization_url(prompt="consent")  # type: ignore[union-attr]
     print()
     print("  No browser detected — using manual authorization.")