# CloakBrowser-Agent [Health: Active]

**Category:** 📂 Browser Automation  
**Repository:** https://github.com/CloakHQ/CloakBrowser-Agent  
**GitHub Stars:** 5  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/cloakbrowser-agent

## Description
Jev-powered stealth browser agent. TypeSafe Jev decides each step in ~0.3 s, CloakBrowser carries it out like a human. MCP server, CLI and Python API.

## Tools
Capabilities this server exposes over MCP:

- **status** — `done`, `done_unverified` (the agent stopped as done, but a second check of the page disagreed: look before trusting it), `blocked` (no control can make progress, or the same action came up on the same page a 3rd time), `needs_input` (the goal lacks a value a field needs), `budget` (step limit reac…

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "cloakbrowser-agent": {
    "command": "uvx",
    "args": ["--from","cloakbrowser-agent","cloak-agent-mcp"],
    "env": {
      "TYPESAFE_API_KEY": "",
      "TEXT_MODEL_BASE_URL": "",
      "TEXT_MODEL_API_KEY": "",
      "TEXT_MODEL": ""
    }
  }
}
```

**Requires environment variables:** `TYPESAFE_API_KEY`, `TEXT_MODEL_BASE_URL`, `TEXT_MODEL_API_KEY`, `TEXT_MODEL` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What CloakBrowser-Agent does

CloakBrowser-Agent exposes a stealth browser agent through MCP, a command-line interface, and a Python package. It accepts a goal such as finding flights or completing a site workflow, then operates a CloakBrowser Chromium session until it reaches a result, cannot proceed, needs a missing value, or reaches its step budget.

The browser output includes the final URL and title, an identifier for the still-open tab, execution counts, and page content formatted as markdown. Each action includes the selected operation, target, model probabilities, and nearby alternatives. This makes uncertainty and failed progress visible to callers. The result can also include a completion check, stale-page retries, and a status such as `done`, `done_unverified`, `blocked`, `needs_input`, `budget`, or `error`.

## How it works

The agent repeatedly reads the controls currently reachable on the page, asks Jev which operation and element to use, and performs a human-like click, text entry, selection, scroll, wait, or completion action. It replans from the current page after each action instead of relying on site-specific selectors. Hidden, disabled, and covered controls are excluded from the choices, and the model selects from generated indices rather than writing selectors, coordinates, or scripts.

Text generation is limited to values needed for individual fields. A caller can provide secret values through environment-variable references, allowing login credentials to be typed without putting the password directly in the task request. When the agent decides that a goal is complete, a second check evaluates the page; disagreement produces `done_unverified` rather than an unqualified success. Repeated no-progress actions and repeated actions on the same page stop the loop as blocked.

## Setup and configuration

Install the package with:

```bash
pip install cloakbrowser-agent
```

The package provides `cloak-agent`, `cloak-agent-mcp`, and the `cloakbrowser` command. MCP clients can run the server through `uvx`, which fetches the package on demand. Python 3.10 or newer is required, and the browser binary downloads on first use. Node.js is not required.

Set `TYPESAFE_API_KEY` for Jev decisions. The text-generation path requires `TEXT_MODEL_BASE_URL`, `TEXT_MODEL_API_KEY`, and `TEXT_MODEL`; these point to an OpenAI-compatible provider and model. `TYPESAFE_MODEL`, `TEXT_MODEL_REASONING`, and `TEXT_MODEL_HEADERS` provide optional model configuration. A CloakBrowser license can be supplied with `CLOAKBROWSER_LICENSE_KEY`, or configured through `cloakbrowser login`. `CLOAKBROWSER_RELEASE_CHANNEL=preview` selects the Preview browser build when a license key is present.

Claude Code, Cursor, Claude Desktop, and other MCP clients can launch `cloak-agent-mcp` through a stdio configuration. The server can also be installed from a cloned repository with `pip install -e .`.

## Tools and capabilities

- `browse(goal, url?, tab_id?, secrets?)` runs a complete browser task.
- Starts from an optional URL and can continue using an existing tab identifier.
- Performs clicks, typing, selections, scrolling, waiting, and completion checks.
- Returns relevant sections of the final page as fenced untrusted markdown content.
- Emits per-step progress notifications while the call is running.
- Reports action probabilities, operation probabilities, runner-up choices, stale retries, and completion-check probabilities.
- Accepts `env:NAME` references in `secrets` for locally configured login values.

## Limitations and notes

Jev requires a TypeSafe API key, and field entry requires access to an OpenAI-compatible chat model. The free CloakBrowser license permits one browser session at a time; a paid key increases that limit. Without a license key, the older browser build is used.

A successful-looking stop is not always verified: `done_unverified` means the completion check disagreed with the agent's stopping decision. `blocked` can result when no available control advances the task or when the same action repeats on the same page. Goals that omit a value required by a field can return `needs_input`, while long tasks can end with `budget`.

_Full upstream README: https://allmcps.com/mcp/cloakbrowser-agent/readme_