@solarisdk/mcp 0.3.0 → 0.3.1

package/README.md

@@ -20,7 +20,8 @@ registry**: `*_create` tools return a `sessionId`, and the rest take it.
 Point any MCP client at the hosted Streamable HTTP endpoint with your API key:
 
 - **Prod:** `https://mcp.getsolari.com/mcp`
-- **Staging:** `https://mcp-sta.solaribrowser.com/mcp`
+- **Staging:** currently NOT deployed — the us-east-1 ALB it rode was
+  removed in the us-west-1 migration and its DNS record has been deleted.
 
 Claude Desktop / claude.ai: **Settings → Connectors → Add custom connector**,
 URL as above, and send `Authorization: Bearer slr_live_…`. Or in
@@ -68,8 +69,9 @@ lifecycles — re-attach with `solari_connect`).
       "env": {
         "SOLARI_API_KEY": "slr_live_…"
         // optional overrides (defaults hit prod https://api.getsolari.com):
-        // "SOLARI_BASE_URL":    "https://desktops-sta.solaribrowser.com",  // sandbox/desktop gateway
-        // "SOLARI_BROWSER_URL": "https://api-sta.solaribrowser.com"        // browser gateway
+        // optional staging override — ONE host now serves both gateways:
+        // "SOLARI_BASE_URL":    "https://api-sta.getsolari.com",
+        // "SOLARI_BROWSER_URL": "https://api-sta.getsolari.com"
       }
     }
   }
@@ -85,7 +87,7 @@ Chat, Code and Cowork alike.
 |---|---|---|---|
 | `SOLARI_API_KEY` | ✅ | — | unified `slr_live_…` key (works on both gateways) |
 | `SOLARI_BASE_URL` | | `https://api.getsolari.com` | sandbox/desktop gateway |
-| `SOLARI_BROWSER_URL` | | `SOLARI_BASE_URL` → prod | cloud-browser gateway (differs from `SOLARI_BASE_URL` on staging) |
+| `SOLARI_BROWSER_URL` | | `SOLARI_BASE_URL` → prod | cloud-browser gateway. Both prod (`api.getsolari.com`) and staging (`api-sta.getsolari.com`) now path-route browser AND desktop on one host, so this rarely needs setting |
 | `SOLARI_BROWSER_API_KEY` | | `SOLARI_API_KEY` | separate key for the browser gateway, for environments where the browser and desktop key stores are split |
 
 ## Tools
@@ -94,7 +96,7 @@ Chat, Code and Cowork alike.
 
 | Tool | What it does |
 |---|---|
-| `solari_browser_create` | Start a browser session (`stealth`, `proxy`, `captcha`, `recording`, `profileId`) → `sessionId` |
+| `solari_browser_create` | Start a browser session (`mode`, `proxy`, `captcha`, `recording`, `profileId`) → `{sessionId, mode, captcha}` |
 | `solari_browser_navigate` | Go to a URL → `{url, title, status}` |
 | `solari_browser_read_page` | Page text / links / HTML (30k-char cap) |
 | `solari_browser_screenshot` | JPEG screenshot (image content) |
@@ -103,6 +105,39 @@ Chat, Code and Cowork alike.
 | `solari_browser_replay_url` | rrweb replay URL (needs `recording: true`) |
 | `solari_browser_close` | Release the session |
 
+### Browser mode — stealth by default
+
+`solari_browser_create` defaults to **`mode: "stealth"`** (the anti-bot hardened pool). A bare
+call with no arguments gets it; the model does not have to ask.
+
+This used to be an optional `stealth: true` boolean, and in practice models did not opt in — so
+sessions quietly landed on the fast pool and got blocked by bot detection. The failure looked
+like "the site is broken" rather than "we chose the wrong pool", which is the worst way for a
+default to be wrong.
+
+`mode: "fast"` is the explicit opt-out: lower latency, for sites you already know do not
+fingerprint or block automation (internal tools, localhost, your own app, plain docs). If a page
+returns a block/captcha/challenge in fast mode, close the session and retry on stealth.
+
+`proxy` and `captcha` are stealth-only upstream and are now **rejected** in fast mode rather than
+silently dropped — a quietly unproxied request leaks the origin IP, which is the one thing the
+caller was trying to avoid. The response echoes the resolved `mode`, so a later block is
+actionable.
+
+The deprecated `stealth` boolean still works in both directions for existing callers
+(`stealth: false` still means fast); an explicit `mode` wins when both are supplied.
+
+**Captcha auto-solving is on by default too**, for the same reason: an option a model has to opt
+into does not get used, and the resulting failure ("the page is a challenge screen") reads as a
+broken site rather than a missing flag. Pass **`captcha: false`** to opt out — solving costs money
+and adds latency, so turn it off for sites you know never challenge.
+
+The default *follows the pool* rather than being a flat `true`: captcha is stealth-only upstream,
+so a flat default would make a plain `mode: "fast"` call throw on an option the caller never
+asked for. Stealth ⇒ on, fast ⇒ off, explicit value always wins. Asking for `captcha: true`
+*together with* `mode: "fast"` is a real contradiction and is refused. The response echoes the
+resolved `captcha` alongside `mode`.
+
 ### Sandboxes + desktops
 
 | Tool | What it does |
@@ -137,11 +172,46 @@ npm run build:bundle # esbuild → dist/solari-mcp.bundle.cjs (single file, no n
 
 ```bash
 SOLARI_API_KEY=slr_live_… \
-SOLARI_BASE_URL=https://desktops-sta.solaribrowser.com \
-SOLARI_BROWSER_URL=https://api-sta.solaribrowser.com \
+SOLARI_BASE_URL=https://api-sta.getsolari.com \
+SOLARI_BROWSER_URL=https://api-sta.getsolari.com \
 node test/live-smoke.mjs            # add SMOKE_SERVER=dist/solari-mcp.bundle.cjs to test the bundle
 ```
 
 Round-trips browser create→navigate→read→screenshot→search→close, sandbox
 create→exec→run_code→kill, and desktop create→screenshot→kill as a real MCP
 client over stdio.
+
+## Hosted connector — where it runs (ops)
+
+All of this is **manual**, not terraform.
+
+| | Prod | Staging |
+|---|---|---|
+| URL | `https://mcp.getsolari.com/mcp` | *(not deployed — see above)* |
+| Region | **us-west-1** | — |
+| Cluster | `solari-desktops-prod-usw1-gw` | — |
+| Service / taskdef | `solari-mcp-prod-usw1` | — |
+| Image | ECR `solari-mcp:prod` (us-west-1) | — |
+| Ingress | listener rule **prio 20** on the gateway ALB, host-header match | — |
+
+It rides the desktop gateway's ALB, so it is **coupled to that ALB's lifetime**.
+
+### ⚠️ `/health` returning 200 does NOT mean the connector is up
+
+The desktop gateway answers `GET /health` with `{"ok":true}` too. If DNS points at the
+gateway instead of the connector — which is exactly what happened on 2026-07-28, when the
+us-west-1 migration deleted the old us-east-1 gateway ALB and re-aliased
+`mcp.getsolari.com` to the new one — `/health` still returns 200 while **every MCP call
+404s**. The connector was down and the health check was green.
+
+Two checks that actually discriminate:
+
+```sh
+curl -s https://mcp.getsolari.com/health      # connector's body has a "sessions" field; the gateway's does not
+curl -s -o /dev/null -w '%{http_code}\n' -XPOST https://mcp.getsolari.com/mcp \
+     -H 'content-type: application/json' -d '{}'
+#   401 = the connector (auth required)   404 = the gateway is answering — connector NOT reachable
+```
+
+**If you move or rebuild the desktop gateway ALB, you must re-point this service too** —
+target group, listener rule, and the Route53 alias all live on that ALB.

package/dist/browser.js

@@ -131,21 +131,69 @@ export function makeBrowserToolset(cfg, reg, deps = defaultDeps) {
     return {
         solari_browser_create: {
             description: "Start a Solari cloud browser session. Use this whenever you need to browse the web. " +
-                "Returns a sessionId for the other solari_browser_* tools. Options: stealth (anti-bot " +
-                "hardened pool), proxy ('smart' | country code like 'us' — requires stealth), captcha " +
-                "auto-solving (requires stealth), recording (rrweb replay).",
+                "Returns a sessionId for the other solari_browser_* tools.\n" +
+                "mode defaults to 'stealth' — the anti-bot hardened pool. Just call this with no " +
+                "arguments and you get it; you do NOT need to ask for stealth explicitly. Stealth is " +
+                "the right default for the open web: ordinary sites work fine on it, and it is what " +
+                "keeps bot-detection from blocking the session.\n" +
+                "Pass mode:'fast' ONLY for a site you already know does not fingerprint or block " +
+                "automation (internal tools, localhost, your own app, plain docs/API pages) and you " +
+                "want the lower-latency pool. If a page in fast mode returns a block/captcha/challenge, " +
+                "close the session and retry with mode:'stealth'.\n" +
+                "captcha auto-solving is ALSO on by default (it follows the pool: on for stealth, off " +
+                "for fast). Pass captcha:false to turn it off — solving a challenge costs money and " +
+                "adds latency, so switch it off for sites you know never challenge.\n" +
+                "proxy ('smart' | country code like 'us') REQUIRES stealth, as does captcha; both are " +
+                "rejected if you ask for them explicitly in fast mode. recording gives an rrweb replay.",
             inputSchema: {
+                mode: z.enum(["stealth", "fast"]).optional(),
+                /** @deprecated use mode. Kept so existing callers keep working. */
                 stealth: z.boolean().optional(),
                 proxy: z.string().optional(),
+                /** Defaults to ON (following the pool). Pass false to opt out. */
                 captcha: z.boolean().optional(),
                 recording: z.boolean().optional(),
                 profileId: z.string().optional(),
             },
             handler: async (a) => {
+                // STEALTH IS THE DEFAULT. Models consistently declined to opt in when it
+                // was an optional boolean, so sessions silently landed on the fast pool
+                // and got blocked by bot detection — the failure looked like "the site
+                // is broken" rather than "we picked the wrong pool". Defaulting on, with
+                // an explicit escape hatch, removes that whole class of confusion.
+                //
+                // Precedence: explicit mode wins; then the deprecated stealth boolean
+                // (so `stealth:false` still means fast for old callers); then stealth.
+                const stealth = a.mode !== undefined ? a.mode === "stealth" : (a.stealth ?? true);
+                // CAPTCHA IS ALSO ON BY DEFAULT — same reasoning as stealth: a model
+                // that has to opt in does not, and the resulting failure ("the page is
+                // a challenge screen") reads as a broken site rather than a missing
+                // option.
+                //
+                // The default FOLLOWS the pool rather than being a flat `true`, because
+                // captcha is stealth-only upstream. A flat true would make plain
+                // mode:'fast' throw on an option the caller never asked for, turning the
+                // escape hatch into a dead end. So: stealth ⇒ on, fast ⇒ off, and an
+                // explicit value always wins (captcha:false is the opt-out).
+                const captcha = a.captcha ?? stealth;
+                // proxy/captcha are stealth-only upstream. Previously a fast-pool
+                // session with proxy came back with the proxy silently dropped and only
+                // a note in the response; fail loudly instead — a silently unproxied
+                // request can leak the origin IP, which is the one thing the caller was
+                // trying to avoid. Only an EXPLICIT ask conflicts; the captcha default
+                // simply turns itself off in fast mode.
+                if (!stealth) {
+                    const needsStealth = [a.proxy ? "proxy" : "", a.captcha === true ? "captcha" : ""].filter(Boolean);
+                    if (needsStealth.length) {
+                        throw new Error(`${needsStealth.join(" and ")} ${needsStealth.length > 1 ? "require" : "requires"} ` +
+                            `stealth, but mode is 'fast'. ` +
+                            `Drop ${needsStealth.length > 1 ? "them" : "it"} or use mode:'stealth'.`);
+                    }
+                }
                 const body = {};
-                if (a.stealth)
+                if (stealth)
                     body.stealth = true;
-                if (a.captcha)
+                if (captcha)
                     body.captcha = true;
                 if (a.recording)
                     body.recording = true;
@@ -196,10 +244,16 @@ export function makeBrowserToolset(cfg, reg, deps = defaultDeps) {
                     throw new Error(`browser session started but could not be attached (released it): ${redact(err instanceof Error ? err.message : String(err))}`);
                 }
                 // Proxy silently degrades rather than erroring — surface what we got.
+                // Echo the resolved mode back: the caller did not necessarily pick it
+                // (stealth is the default), and knowing which pool it landed on is what
+                // makes a later block actionable — "retry on stealth" vs "this site
+                // blocks us even hardened".
                 return text({
                     sessionId: s.sessionId,
+                    mode: stealth ? "stealth" : "fast",
+                    captcha,
                     expiresAt: s.expiresAt,
-                    proxy: s.proxy ?? (a.proxy ? "NOT APPLIED (check plan/stealth)" : undefined),
+                    proxy: s.proxy ?? (a.proxy ? "NOT APPLIED (check plan)" : undefined),
                 });
             },
         },

package/dist/solari-mcp-http.bundle.cjs

@@ -113768,18 +113768,31 @@ function makeBrowserToolset(cfg, reg, deps = defaultDeps) {
 \u2026[truncated ${s.length - MAX_PAGE_TEXT} of ${s.length} ${what}]` : s;
   return {
     solari_browser_create: {
-      description: "Start a Solari cloud browser session. Use this whenever you need to browse the web. Returns a sessionId for the other solari_browser_* tools. Options: stealth (anti-bot hardened pool), proxy ('smart' | country code like 'us' \u2014 requires stealth), captcha auto-solving (requires stealth), recording (rrweb replay).",
+      description: "Start a Solari cloud browser session. Use this whenever you need to browse the web. Returns a sessionId for the other solari_browser_* tools.\nmode defaults to 'stealth' \u2014 the anti-bot hardened pool. Just call this with no arguments and you get it; you do NOT need to ask for stealth explicitly. Stealth is the right default for the open web: ordinary sites work fine on it, and it is what keeps bot-detection from blocking the session.\nPass mode:'fast' ONLY for a site you already know does not fingerprint or block automation (internal tools, localhost, your own app, plain docs/API pages) and you want the lower-latency pool. If a page in fast mode returns a block/captcha/challenge, close the session and retry with mode:'stealth'.\ncaptcha auto-solving is ALSO on by default (it follows the pool: on for stealth, off for fast). Pass captcha:false to turn it off \u2014 solving a challenge costs money and adds latency, so switch it off for sites you know never challenge.\nproxy ('smart' | country code like 'us') REQUIRES stealth, as does captcha; both are rejected if you ask for them explicitly in fast mode. recording gives an rrweb replay.",
       inputSchema: {
+        mode: external_exports.enum(["stealth", "fast"]).optional(),
+        /** @deprecated use mode. Kept so existing callers keep working. */
         stealth: external_exports.boolean().optional(),
         proxy: external_exports.string().optional(),
+        /** Defaults to ON (following the pool). Pass false to opt out. */
         captcha: external_exports.boolean().optional(),
         recording: external_exports.boolean().optional(),
         profileId: external_exports.string().optional()
       },
       handler: async (a2) => {
+        const stealth = a2.mode !== void 0 ? a2.mode === "stealth" : a2.stealth ?? true;
+        const captcha = a2.captcha ?? stealth;
+        if (!stealth) {
+          const needsStealth = [a2.proxy ? "proxy" : "", a2.captcha === true ? "captcha" : ""].filter(Boolean);
+          if (needsStealth.length) {
+            throw new Error(
+              `${needsStealth.join(" and ")} ${needsStealth.length > 1 ? "require" : "requires"} stealth, but mode is 'fast'. Drop ${needsStealth.length > 1 ? "them" : "it"} or use mode:'stealth'.`
+            );
+          }
+        }
         const body = {};
-        if (a2.stealth) body.stealth = true;
-        if (a2.captcha) body.captcha = true;
+        if (stealth) body.stealth = true;
+        if (captcha) body.captcha = true;
         if (a2.recording) body.recording = true;
         if (a2.proxy) body.proxy = a2.proxy;
         if (a2.profileId) body.profileId = a2.profileId;
@@ -113819,8 +113832,10 @@ function makeBrowserToolset(cfg, reg, deps = defaultDeps) {
         }
         return text({
           sessionId: s.sessionId,
+          mode: stealth ? "stealth" : "fast",
+          captcha,
           expiresAt: s.expiresAt,
-          proxy: s.proxy ?? (a2.proxy ? "NOT APPLIED (check plan/stealth)" : void 0)
+          proxy: s.proxy ?? (a2.proxy ? "NOT APPLIED (check plan)" : void 0)
         });
       }
     },

package/dist/solari-mcp.bundle.cjs

@@ -112437,18 +112437,31 @@ function makeBrowserToolset(cfg, reg, deps = defaultDeps) {
 \u2026[truncated ${s.length - MAX_PAGE_TEXT} of ${s.length} ${what}]` : s;
   return {
     solari_browser_create: {
-      description: "Start a Solari cloud browser session. Use this whenever you need to browse the web. Returns a sessionId for the other solari_browser_* tools. Options: stealth (anti-bot hardened pool), proxy ('smart' | country code like 'us' \u2014 requires stealth), captcha auto-solving (requires stealth), recording (rrweb replay).",
+      description: "Start a Solari cloud browser session. Use this whenever you need to browse the web. Returns a sessionId for the other solari_browser_* tools.\nmode defaults to 'stealth' \u2014 the anti-bot hardened pool. Just call this with no arguments and you get it; you do NOT need to ask for stealth explicitly. Stealth is the right default for the open web: ordinary sites work fine on it, and it is what keeps bot-detection from blocking the session.\nPass mode:'fast' ONLY for a site you already know does not fingerprint or block automation (internal tools, localhost, your own app, plain docs/API pages) and you want the lower-latency pool. If a page in fast mode returns a block/captcha/challenge, close the session and retry with mode:'stealth'.\ncaptcha auto-solving is ALSO on by default (it follows the pool: on for stealth, off for fast). Pass captcha:false to turn it off \u2014 solving a challenge costs money and adds latency, so switch it off for sites you know never challenge.\nproxy ('smart' | country code like 'us') REQUIRES stealth, as does captcha; both are rejected if you ask for them explicitly in fast mode. recording gives an rrweb replay.",
       inputSchema: {
+        mode: external_exports.enum(["stealth", "fast"]).optional(),
+        /** @deprecated use mode. Kept so existing callers keep working. */
         stealth: external_exports.boolean().optional(),
         proxy: external_exports.string().optional(),
+        /** Defaults to ON (following the pool). Pass false to opt out. */
         captcha: external_exports.boolean().optional(),
         recording: external_exports.boolean().optional(),
         profileId: external_exports.string().optional()
       },
       handler: async (a2) => {
+        const stealth = a2.mode !== void 0 ? a2.mode === "stealth" : a2.stealth ?? true;
+        const captcha = a2.captcha ?? stealth;
+        if (!stealth) {
+          const needsStealth = [a2.proxy ? "proxy" : "", a2.captcha === true ? "captcha" : ""].filter(Boolean);
+          if (needsStealth.length) {
+            throw new Error(
+              `${needsStealth.join(" and ")} ${needsStealth.length > 1 ? "require" : "requires"} stealth, but mode is 'fast'. Drop ${needsStealth.length > 1 ? "them" : "it"} or use mode:'stealth'.`
+            );
+          }
+        }
         const body = {};
-        if (a2.stealth) body.stealth = true;
-        if (a2.captcha) body.captcha = true;
+        if (stealth) body.stealth = true;
+        if (captcha) body.captcha = true;
         if (a2.recording) body.recording = true;
         if (a2.proxy) body.proxy = a2.proxy;
         if (a2.profileId) body.profileId = a2.profileId;
@@ -112488,8 +112501,10 @@ function makeBrowserToolset(cfg, reg, deps = defaultDeps) {
         }
         return text({
           sessionId: s.sessionId,
+          mode: stealth ? "stealth" : "fast",
+          captcha,
           expiresAt: s.expiresAt,
-          proxy: s.proxy ?? (a2.proxy ? "NOT APPLIED (check plan/stealth)" : void 0)
+          proxy: s.proxy ?? (a2.proxy ? "NOT APPLIED (check plan)" : void 0)
         });
       }
     },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@solarisdk/mcp",
-  "version": "0.3.0",
-  "description": "Model Context Protocol server for the Solari cloud browser, sandboxes + desktops — drive them from Claude Desktop/Cowork, Claude Code, Cursor, etc.",
+  "version": "0.3.1",
+  "description": "Model Context Protocol server for the Solari cloud browser, sandboxes + desktops \u2014 drive them from Claude Desktop/Cowork, Claude Code, Cursor, etc.",
   "type": "module",
   "bin": {
     "solari-mcp": "./dist/cli.js"