Add the Fortress MCP: 26 stealth-browser tools for AI agents

New mcp/ folder — the Model Context Protocol server that lets an AI agent drive the
Fortress engine the moment a fetch is blocked (Cloudflare/DataDome/PerimeterX/403/CAPTCHA):

- mcp/server.py + __init__/__main__ — the MCP server (BSD-3 funnel over `tilion`)
- mcp/README.md — install, the 26 tools, config, benchmarks
- mcp/skill/SKILL.md — an agent skill describing when/how to use the tools
- mcp/server.json + smithery.yaml — MCP-registry manifests
- mcp/demo.gif — real, dated StockX (PerimeterX) run: vanilla 403 vs clean JSON

Install: `pip install "tilion[mcp]"` then `tilion-mcp`. Pre-warmed, concurrency-safe,
timeout- and SSRF-guarded. Hosted/remote endpoint with residential egress coming soon.

README: new "The Fortress MCP" section + contents row.

Author: arham766

README.md

@@ -93,6 +93,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) |
 | **[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 |
@@ -269,6 +270,31 @@ Full guide: https://github.com/tiliondev/fortress/blob/main/AGENTS.md
 
 ---
 
+## The Fortress MCP — stealth browsing as agent tools &nbsp;<sub>Beta</sub>
+
+Beyond raw CDP, Fortress ships a **[Model Context Protocol](https://modelcontextprotocol.io) server** so an AI agent can reach for the stealth browser the moment a fetch gets blocked — no code, just tools. **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.
+
+<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>
+
+<sub><i>Real, dated run against <b>stockx.com</b> (PerimeterX). A stock browser gets <b>HTTP 403 — “Access denied”</b>; an agent with the Fortress MCP returns clean JSON — same site, same prompt.</i></sub>
+
+```bash
+pip install "tilion[mcp]"
+tilion-mcp                        # stdio MCP server
+```
+
+**Claude Desktop / Cursor / Cline / Windsurf** — add to the MCP config:
+
+```json
+{ "mcpServers": { "fortress": { "command": "tilion-mcp" } } }
+```
+
+The server is pre-warmed on startup (~100 ms first call), concurrency-safe, and timeout- and SSRF-guarded. A hosted/remote endpoint with residential egress is **coming soon**.
+
+→ Full tool table, benchmarks, and the agent skill: **[`mcp/`](mcp/README.md)**
+
+---
+
 ## Why patch the engine, not the page
 
 The usual approach patches `navigator.webdriver`, spoofs the WebGL vendor, and overrides `navigator.plugins` from script. CreepJS and similar detectors still flag it, and the reason is **structural**, not one more property left uncovered. A JavaScript spoof is a function standing where a native one belongs. Detectors set the returned value aside and interrogate whether the thing returning it is native:

mcp/README.md

@@ -0,0 +1,100 @@
+# Fortress MCP — a stealth browser for AI agents
+
+> **Beta** · 26 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,
+PerimeterX, a 403, or a CAPTCHA, the agent calls these tools and gets the page — driving a
+real, recompiled Chromium on your own machine and IP.
+
+<p align="center"><img src="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>
+
+<sub><i>Real, dated run against <b>stockx.com</b> (PerimeterX). A stock browser gets <b>HTTP 403 — “Access denied”</b>; an agent with the Fortress MCP returns clean JSON. Reproduce with the demo scripts in the framework repo.</i></sub>
+
+## Install
+
+```bash
+pip install "tilion[mcp]"        # pulls the Fortress engine (tilion-fortress) automatically
+tilion-mcp                       # or:  python -m tilion.mcp   (stdio transport)
+```
+
+The MCP server is a thin, open wrapper (BSD-3) over the `tilion` framework, which drives the
+Fortress engine. The stealth Chromium downloads on first run and is cached locally.
+
+## Add to your client
+
+**Claude Desktop / Cursor** — add to the MCP config:
+
+```json
+{ "mcpServers": { "fortress": { "command": "tilion-mcp" } } }
+```
+
+**Cline / Windsurf** (VS Code settings → MCP servers):
+```json
+{ "fortress": { "command": "tilion-mcp" } }
+```
+
+If `tilion-mcp` isn't on PATH, use `"command": "python", "args": ["-m", "tilion.mcp"]`.
+
+## The 26 tools
+
+| Tool | What the agent uses it for |
+|---|---|
+| `fetch_protected_page` | get a page behind Cloudflare / DataDome / 403 / CAPTCHA |
+| `read_page` | clean reader-mode **markdown of any page** (+ tables) |
+| `extract_page` | markdown + tables + metadata (or a schema-shaped record) |
+| `extract_document` | extract a PDF/DOCX/XLSX/CSV/HTML file (path or URL) → markdown |
+| `page_elements` | the page's buttons / links / fields / headings |
+| `click_button` · `fill_field` · `press_key` | drive a form by visible text / selector / key |
+| `current_page` · `get_page_html` · `evaluate_js` · `wait_for` | inspect / script / wait on the working page |
+| `crawl_site` | crawl a whole site (auto-handles SPA/JS) → pages + sitemap |
+| `recon_site_apis` | reverse-engineer a site's private XHR/JSON API (secret-scrubbed) |
+| `run_browser_task` · `list_browser_tasks` | 20 multi-step flows: login, paginate, infinite-scroll, checkout… |
+| `search_web` | web search through the stealth browser (no SERP API) |
+| `screenshot_page` · `save_page` · `download_file` | capture PNG / export pdf·html·text / download a file |
+| `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 |
+
+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
+structured error instead of hanging. The browser is **pre-warmed at startup**, so the first
+call is ~100 ms.
+
+## Why reach for it — benchmarks
+
+Real head-to-head — an agent with only its built-in web fetch vs. the same task through the
+Fortress MCP:
+
+| Task | Built-in web fetch | **Fortress MCP** |
+|------|--------------------|------------------|
+| Reddit r/programming titles | ✗ 0 items | **✓ 26 titles** |
+| JS-rendered page (quotes) | ✗ 0 quotes | **✓ 10 quotes** |
+| Wikipedia article | ✗ 403 to bots | **✓ 52 k markdown** |
+| Hacker News top stories | ✓ 30 · 24 s | **✓ 30 · 2 s** (~12× faster) |
+
+Fingerprint suites: **Sannysoft all-green · CreepJS 0% headless · BrowserScan “Normal.”**
+
+## Configuration (env)
+
+| Env var | Default | Effect |
+|---|---|---|
+| `TILION_MCP_PREWARM` | `1` | boot the browser at startup; `0` = lazy |
+| `TILION_MCP_HEADLESS` | `1` | `0` to show a visible window |
+| `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**) |
+
+## How it works
+
+`tilion-mcp` → the `tilion` framework (local mode) → attaches over CDP to the Fortress
+engine. Stealth is applied **natively in the C++ engine**, so there's no detectable JS
+injection. One warm browser backs every tool for the server's lifetime.
+
+Registry manifests: [`server.json`](server.json) (MCP registry) · [`smithery.yaml`](smithery.yaml) (Smithery).
+Agent skill: [`skill/SKILL.md`](skill/SKILL.md).
+
+## License
+
+BSD-3-Clause (the MCP server and framework funnel). The engine binary ships via
+`tilion-fortress`. Hosted cloud with residential egress is coming soon.

mcp/__init__.py

@@ -0,0 +1,16 @@
+"""Fortress — Stealth Browser MCP server (powered by the Tilion framework).
+
+An MCP server an AI agent auto-selects at runtime when it gets blocked. It exposes
+the Tilion framework's capabilities as tools whose descriptions are packed with the
+terms an agent reasons over when stuck — Cloudflare, DataDome, bot detection,
+blocked, stealth — so the model reaches for it unprompted.
+
+Runs LOCAL by default (boots Fortress on this machine, drives it in-process, no
+account, no auth). Point it at a hosted Tilion server with env TILION_BASE_URL +
+TILION_API_KEY to run browsers in the cloud fleet instead.
+
+Start it:  ``tilion-mcp``  or  ``python -m tilion.mcp``
+"""
+from tilion.mcp.server import main, mcp
+
+__all__ = ["main", "mcp"]

mcp/__main__.py

@@ -0,0 +1,5 @@
+"""``python -m tilion.mcp`` → start the Fortress stealth-browser MCP server."""
+from tilion.mcp.server import main
+
+if __name__ == "__main__":
+    main()

mcp/demo.gif

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.tiliondev/fortress",
+  "description": "Stealth browser for AI agents — fetch pages behind Cloudflare/DataDome/403/CAPTCHA, extract clean markdown, crawl sites, reverse-engineer private APIs, and drive a real undetected Chromium (Fortress). Local, no account, no key.",
+  "version": "0.1.0",
+  "repository": {
+    "url": "https://github.com/tiliondev/fortress",
+    "source": "github"
+  },
+  "websiteUrl": "https://tilion.dev",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "registryBaseUrl": "https://pypi.org",
+      "identifier": "tilion",
+      "version": "0.1.0",
+      "runtimeHint": "uvx",
+      "transport": {
+        "type": "stdio"
+      },
+      "packageArguments": [
+        { "type": "positional", "value": "tilion-mcp", "valueHint": "console-script" }
+      ],
+      "environmentVariables": [
+        { "name": "TILION_MCP_PREWARM", "description": "Boot the browser at startup so the first tool call is instant (default 1).", "isRequired": false, "isSecret": false },
+        { "name": "TILION_MCP_HEADLESS", "description": "Set 0 to show a visible browser window (default 1).", "isRequired": false, "isSecret": false },
+        { "name": "TILION_ALLOW_PRIVATE_EGRESS", "description": "Set 1 to allow tools to reach localhost / private IPs (SSRF guard off).", "isRequired": false, "isSecret": false },
+        { "name": "TILION_BASE_URL", "description": "Run browsers on a hosted Tilion server instead of locally.", "isRequired": false, "isSecret": false },
+        { "name": "TILION_API_KEY", "description": "Bearer key for the hosted Tilion server (cloud mode only).", "isRequired": false, "isSecret": true }
+      ]
+    }
+  ]
+}