mcp: add solve_captcha + get_egress_info tools (26 -> 28); proxy/captcha env vars

Sync the MCP server and docs with the framework: two new tools and the egress/captcha
configuration.

- mcp/server.py: solve_captcha(url) — detect + solve reCAPTCHA/hCaptcha/Turnstile (needs
  CAPTCHA_API_KEY); get_egress_info() — report proxy/region + the real public IP so
  residential egress can be verified.
- mcp/README + README: 26 -> 28 tools; document the new tools and env vars
  (TILION_PROXY, TILION_REGION, CAPTCHA_API_KEY, CAPTCHA_PROVIDER).

Note: fetch_protected_page auto-solves captchas when CAPTCHA_API_KEY is set. Proxy routing
requires an engine build that honors --proxy-server; get_egress_info verifies it took effect.

Author: arham766

README.md

@@ -10,7 +10,7 @@ Stealth Chromium engine
 [![Chromium](https://img.shields.io/badge/chromium-151.0.7908.0-4285F4?logo=googlechrome&logoColor=white)](CHROMIUM_VERSION) [![pip](https://img.shields.io/badge/pip-3776AB?logo=pypi&logoColor=white)](https://pypi.org/project/tilion-fortress/) [![npm](https://img.shields.io/badge/npm-CB3837?logo=npm&logoColor=white)](https://www.npmjs.com/package/tilion-fortress) [![Docker pulls](https://img.shields.io/docker/pulls/tilion/fortress?logo=docker&logoColor=white&label=pulls)](https://hub.docker.com/r/tilion/fortress)<br/>
 [![CreepJS](https://img.shields.io/badge/CreepJS-0%25%20headless-2ea44f)](docs/GAUNTLET_RESULTS.md) [![Runtime.enable leak](https://img.shields.io/badge/Runtime.enable-no%20leak-2ea44f)](docs/GAUNTLET_RESULTS.md)<br/>
 [![Copy for agent](https://img.shields.io/badge/Copy%20for%20agent-24292f?logo=readme&logoColor=white)](https://raw.githubusercontent.com/tiliondev/fortress/main/AGENTS.md) [![llms.txt](https://img.shields.io/badge/llms.txt-24292f?logo=readme&logoColor=white)](https://raw.githubusercontent.com/tiliondev/fortress/main/llms.txt)<br/>
-[![MCP server](https://img.shields.io/badge/MCP-fortress%20·%2026%20tools-6E56CF?logo=modelcontextprotocol&logoColor=white)](mcp/) [![npm tilion-mcp](https://img.shields.io/npm/v/tilion-mcp?logo=npm&logoColor=white&label=npx%20tilion-mcp&color=CB3837)](https://www.npmjs.com/package/tilion-mcp)
+[![MCP server](https://img.shields.io/badge/MCP-fortress%20·%2028%20tools-6E56CF?logo=modelcontextprotocol&logoColor=white)](mcp/) [![npm tilion-mcp](https://img.shields.io/npm/v/tilion-mcp?logo=npm&logoColor=white&label=npx%20tilion-mcp&color=CB3837)](https://www.npmjs.com/package/tilion-mcp)
 
 **Fortress is a stealth Chromium engine that stops your scrapers and browser agents from getting blocked, with one line of code change.** Bot detectors flag automation by reading the browser fingerprint; Fortress corrects that fingerprint inside Chromium's C++, so the browser presents as an ordinary Chrome install. Scrapers finish their runs, agents reach the pages they were sent to, and CreepJS, Sannysoft, BrowserScan, and live Cloudflare Turnstile all read it as human. Point your existing Playwright or Puppeteer at Fortress over CDP, and nothing else in your code changes.
 
@@ -94,7 +94,7 @@ pip install -U tilion-fortress       # or:  docker run --rm -p 9222:9222 tilion/
 | | |
 |---|---|
 | **[What it is](#what-it-is)** · **[Quick start](#quick-start)** | what it is, install, first script, AI-agent setup |
-| **[The Fortress MCP](#the-fortress-mcp--stealth-browsing-as-agent-tools)** | 26 stealth-browser tools for AI agents (Beta) |
+| **[The Fortress MCP](#the-fortress-mcp--stealth-browsing-as-agent-tools)** | 28 stealth-browser tools for AI agents (Beta) |
 | **[Why patch the engine, not the page](#why-patch-the-engine-not-the-page)** | the self-revealing-JS thesis + the three detection layers |
 | **[How Fortress compares](#how-fortress-compares)** | vs puppeteer-stealth · Camoufox · CloakBrowser · closed vendors |
 | **[Proof: live-detector results](#proof-live-detector-results)** | CreepJS / Sannysoft / BrowserScan / Cloudflare, with screenshots |
@@ -273,7 +273,7 @@ Full guide: https://github.com/tiliondev/fortress/blob/main/AGENTS.md
 
 ## The Fortress MCP — stealth browsing as agent tools &nbsp;<sub>Beta</sub>
 
-Raw CDP is for code you write. The **Fortress MCP** is for agents that call **tools**: a [Model Context Protocol](https://modelcontextprotocol.io) server that hands Claude, Cursor, or any MCP client a stealth browser, so the moment a fetch is blocked it just calls a tool and gets the page. **26 tools, local and free** — `fetch_protected_page`, `extract_page`, `crawl_site`, `recon_site_apis`, `search_web`, `run_browser_task`, `save_profile`, `get_stealth_cdp_endpoint`, and more.
+Raw CDP is for code you write. The **Fortress MCP** is for agents that call **tools**: a [Model Context Protocol](https://modelcontextprotocol.io) server that hands Claude, Cursor, or any MCP client a stealth browser, so the moment a fetch is blocked it just calls a tool and gets the page. **28 tools, local and free** — `fetch_protected_page`, `extract_page`, `crawl_site`, `recon_site_apis`, `search_web`, `run_browser_task`, `save_profile`, `get_stealth_cdp_endpoint`, and more.
 
 <p align="center"><img src="mcp/demo.gif" alt="Same site, same prompt: a vanilla browser is blocked by PerimeterX while an agent with the Fortress MCP returns clean JSON" width="760"/></p>
 
@@ -324,7 +324,7 @@ Then just ask your agent — *“get the price off this StockX page”* — and
 
 Tools are annotated (reads auto-approve, writes gate), **pre-warmed** on startup (~100 ms first call), concurrency-safe, and timeout- and SSRF-guarded. A hosted endpoint with **residential egress is coming soon**.
 
-→ Full 26-tool table, benchmarks, and the agent skill: **[`mcp/`](mcp/README.md)**
+→ Full 28-tool table, benchmarks, and the agent skill: **[`mcp/`](mcp/README.md)**
 
 ---
 

mcp/README.md

@@ -1,6 +1,6 @@
 # Fortress MCP — a stealth browser for AI agents
 
-> **Beta** · 26 tools · runs **local & free** · **hosted cloud coming soon**
+> **Beta** · 28 tools · runs **local & free** · **hosted cloud coming soon**
 
 An [MCP](https://modelcontextprotocol.io) server that gives any AI agent the **Fortress
 stealth engine** the moment it gets blocked. When a fetch hits Cloudflare, DataDome,
@@ -36,7 +36,7 @@ Fortress engine. The stealth Chromium downloads on first run and is cached local
 
 If `tilion-mcp` isn't on PATH, use `"command": "python", "args": ["-m", "tilion.mcp"]`.
 
-## The 26 tools
+## The 28 tools
 
 | Tool | What the agent uses it for |
 |---|---|
@@ -55,6 +55,8 @@ If `tilion-mcp` isn't on PATH, use `"command": "python", "args": ["-m", "tilion.
 | `get_cookies` · `save_profile` · `load_profile` | read cookies · persist/restore an authenticated session |
 | `list_tabs` · `close_tab` | manage open tabs |
 | `get_stealth_cdp_endpoint` | a CDP url to point your OWN browser-use / Playwright / Puppeteer at |
+| `solve_captcha` | detect + solve a reCAPTCHA/hCaptcha/Turnstile (needs `CAPTCHA_API_KEY`) |
+| `get_egress_info` | report proxy/region + the real public IP the target sees (verify residential egress) |
 
 Tools are **annotated** (`readOnlyHint` / `destructiveHint`) so clients auto-approve reads
 and gate writes. Every tool is **timeout- and SSRF-guarded**, caps its output, and returns a
@@ -84,6 +86,10 @@ Fingerprint suites: **Sannysoft all-green · CreepJS 0% headless · BrowserScan
 | `TILION_ALLOW_PRIVATE_EGRESS` | `0` | `1` to allow localhost / private IPs (SSRF guard off) |
 | `TILION_MCP_TOOL_TIMEOUT` | `120` | per-tool wall-clock cap (seconds) |
 | `TILION_BASE_URL` / `TILION_API_KEY` | — | hosted mode (**coming soon**) |
+| `TILION_PROXY` | — | egress proxy `http://user:pass@host:port` (residential/mobile) |
+| `TILION_REGION` | — | egress region hint (e.g. `us`) — aligns timezone/locale to the IP |
+| `CAPTCHA_API_KEY` | — | solver key; `fetch` then auto-solves + `solve_captcha` works |
+| `CAPTCHA_PROVIDER` | `2captcha` | `2captcha` \| `anticaptcha` \| `capsolver` |
 
 ## How it works
 

mcp/server.py

@@ -200,7 +200,17 @@ async def _t() -> Tilion:
             base_url = _env("BASE_URL")
             api_key = _env("API_KEY")
             headless = (_env("MCP_HEADLESS", "1") != "0")
-            inst = Tilion(headless=headless, base_url=base_url, api_key=api_key)
+            # Egress + captcha come from env so an agent host can configure a residential
+            # proxy and a captcha key without changing the tool surface. TILION_PROXY /
+            # TILION_REGION / CAPTCHA_API_KEY are read by the facade itself; pass any
+            # explicit ones through here too.
+            inst = Tilion(
+                headless=headless, base_url=base_url, api_key=api_key,
+                proxy=_env("PROXY"),                 # TILION_PROXY
+                region=_env("REGION"),               # TILION_REGION
+                captcha_api_key=os.environ.get("CAPTCHA_API_KEY"),
+                captcha_provider=os.environ.get("CAPTCHA_PROVIDER", "2captcha"),
+            )
             await inst.start()
             _tilion = inst
     return _tilion
@@ -580,6 +590,44 @@ async def close_tab(index: int) -> dict:
     return await t.close_tab(int(index))
 
 
+@mcp.tool(annotations=_WRITE)
+@_safe
+async def solve_captcha(url: str | None = None) -> dict:
+    """Detect and solve a CAPTCHA on the current page (or a freshly-navigated `url`).
+
+    Use when a page is gated by reCAPTCHA/hCaptcha/Turnstile. Requires a solver key in the
+    server env (`CAPTCHA_API_KEY`, provider `CAPTCHA_PROVIDER` = 2captcha|anticaptcha|
+    capsolver). Returns {detected, kind, solvable, solved}. `fetch_protected_page` already
+    auto-solves when a key is set; use this for an explicit retry on an interactive page.
+    """
+    if url:
+        await _check_url(url)
+    t = await _t()
+    return await t.solve_captcha(url)
+
+
+@mcp.tool(annotations=_READ)
+@_safe
+async def get_egress_info() -> dict:
+    """Report the current egress config: whether a proxy/region is set and the public IP
+    the target actually sees. Use to confirm residential egress is active before hitting a
+    hard target (a datacenter IP gets pre-classified as a bot regardless of fingerprint).
+    Configure via env: TILION_PROXY=http://user:pass@host:port, TILION_REGION=us.
+    """
+    t = await _t()
+    info = {"proxy_configured": t._proxy is not None,
+            "proxy_type": getattr(t._proxy, "type", None),
+            "region": t._region,
+            "captcha_solver": bool(t._captcha_api_key)}
+    try:
+        r = await t.fetch("https://api.ipify.org?format=json", timeout_ms=20000)
+        import json as _json
+        info["public_ip"] = _json.loads(r.get("text", "{}") or "{}").get("ip")
+    except Exception:
+        info["public_ip"] = None
+    return info
+
+
 @mcp.tool(annotations=_READ)
 @_safe
 async def get_stealth_cdp_endpoint() -> dict:
@@ -611,7 +659,7 @@ def main() -> None:
     # Banner to STDERR only — stdout is the MCP stdio transport and must stay clean.
     print(
         "Tilion Fortress Stealth-Browser MCP  [Beta]\n"
-        "  26 tools | local & free | hosted cloud (residential egress) coming soon\n"
+        "  28 tools | local & free | hosted cloud (residential egress) coming soon\n"
         "  docs: DOCUMENTATION.md - more coming; benchmarks in the README\n"
         "  listening on stdio...",
         file=sys.stderr, flush=True,