Obscura MCP Server — Give Your AI Agent a Browser

When AI Needs a Browser

LLMs have knowledge cutoffs, cannot access private systems, and cannot perform actions. MCP (Model Context Protocol) gives AI the ability to call tools, and Obscura's MCP server gives AI a browser.

Once configured, AI can:

• Open web pages and read content
• Fill forms and log in
• Click buttons and links
• Extract page content and links
• Manage cookies and session state

Start the MCP Server

Two transport modes:

# stdio mode (default, for Claude Desktop local integration)
obscura mcp
 
# HTTP mode (remote or container deployment)
obscura mcp --http --port 8080
 
# With stealth
obscura mcp --stealth
 
# With proxy
obscura mcp --stealth --proxy http://proxy.16yun.cn:8888

HTTP transport binds to 127.0.0.1 by default. When a container or sidecar deployment needs external access, bind all interfaces with --host 0.0.0.0:

obscura mcp --http --host 0.0.0.0 --port 3000

Claude Desktop Configuration

{
  "mcpServers": {
    "obscura": {
      "command": "/path/to/obscura",
      "args": ["mcp", "--stealth"]
    }
  }
}

Config location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

Claude Code:

claude mcp add obscura /path/to/obscura mcp

After restarting the client, the Obscura browser tools appear in the available tool list.

Browser Tools Overview

The Obscura MCP server exposes 30+ browser tools covering navigation, reading, interaction, waiting, JS execution, cookies, and tab management. Understanding how the tools divide labor is the foundation for composing complex workflows — MCP tools are fine-grained, and the AI strings them together in a "navigate → read/interact → wait → read again" rhythm.

Navigation

Page Reading

Interaction

Wait and JavaScript

Cookie and Storage

Tab Management

Example: AI Auto-Search

An AI agent workflow:

1. browser_navigate → Open search engine
2. browser_fill → Enter keywords
3. browser_press_key → Press Enter
4. browser_wait_for → Wait for results
5. browser_snapshot → Read results summary
6. browser_click → Click interesting link
7. browser_markdown → Extract page as Markdown
8. browser_network_requests → Inspect API calls

This flow shows the core value of MCP: every step is the AI making its own decision after observing the previous step's result. A scripted Puppeteer cannot do this — it executes predetermined logic and breaks when the page structure changes. An AI agent can read browser_snapshot, understand "this page is a CAPTCHA" or "the results are empty", and decide for itself whether to retry or take a different path.

Session State Management

MCP tools operate on the current browser session, just like CDP mode. A few things to keep in mind:

• Navigate first. browser_snapshot, browser_click, and browser_extract all act on the current page, so the first step of a workflow is almost always browser_navigate.
• Auth state is persistable. Export Cookie + localStorage with browser_storage_state and restore it next session with browser_set_storage_state, so you do not re-login every time. Combined with the --storage-dir startup flag, state is also persisted to disk across processes.
• Parallel tabs. browser_tab_new plus browser_tab_switch lets the AI move between pages, which suits "look something up on site A, fill a form on site B" cross-site workflows.

HTTP Security

Two layers of protection for HTTP transport.

Origin allowlist:

OBSCURA_MCP_ALLOWED_ORIGINS="https://app.16yun.cn" \
  obscura mcp --http --host 0.0.0.0 --port 3000

When set, only browser pages with a listed Origin can reach the MCP endpoint. Native MCP clients send no Origin and are always allowed. Unset (the default) keeps the permissive behavior. This layer mainly stops malicious web pages from cross-origin POSTing to a loopback MCP port.

Body cap: 16 MB max per request, preventing memory exhaustion from oversized unauthenticated calls.

Whenever you expose the HTTP transport beyond loopback, set the allowlist and put it behind an authenticating reverse proxy or network isolation.

With Stealth and Proxy

obscura mcp \
  --stealth \
  --proxy http://user:pass@proxy.16yun.cn:8888 \
  --user-agent "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ..."

Every browser action the AI agent takes goes through Stealth anti-detection and the proxy exit. For scraping-style tasks this layer is indispensable — an MCP session without Stealth is easily flagged as automated traffic by a target site's passive detection.

Above Traditional Browser Automation

Comparing a Puppeteer script with an MCP AI agent:

One trade-off to weigh: the AI agent's non-determinism means the same input can produce different step paths. For reproducible batch jobs, deterministic scripts (CDP or CLI) remain the better fit; MCP shines for one-off, exploratory, or structure-unknown work.

Summary

The Obscura MCP server is the standard bridge between AI agents and the web. 30+ tools cover all basic browser automation operations, and combined with Stealth and proxy configuration, an AI agent can browse, extract, and act like a real user. It is best suited for exploratory, high-fault-tolerance, structure-uncertain tasks; for deterministic batch processing, the CLI and CDP remain the safer choice.