Plasmate

What plasmate does

plasmate exposes a headless browser designed for agent workflows. Pages are processed into a Semantic Object Model (SOM), which represents content, regions, and interactive elements in structured JSON. This gives an agent a page-oriented representation to inspect and act on instead of requiring it to reason over the complete HTML document.

The engine runs JavaScript through V8 and supports a documented subset of the Chrome DevTools Protocol for compatible Puppeteer workflows. It also provides native MCP and AWP interfaces. SOM output size depends on the page, configuration, serialization, and tokenizer, so applications should measure the results they receive.

How it works

A stateless MCP call can fetch a URL and return SOM data, readable text, or deduplicated links. For interactive work, open_page creates a session and returns a session ID, SOM, and cache-restoration status. Later calls can navigate that session, inspect its state, act on elements by SOM ID, and close the session.

Available page actions include clicking, typing, selecting options, scrolling, toggling controls, and clearing fields. JavaScript evaluation operates in the page context. Cookie tools read, add, update, or remove cookies associated with a session. Screenshots are available when visual output is needed, with SOM fallback behavior.

The native executable can also serve CDP for Puppeteer clients or AWP through its respective protocols. Stateful workflows can be run from versioned, bounded plans; mutating steps require separate confirmations, while JavaScript evaluation and cookie writes require category opt-ins.

Setup and configuration

Install the native engine with the project’s shell installer or Cargo:

• curl -fsSL https://plasmate.app/install.sh | sh
• cargo install plasmate

The npm and PyPI packages provide client SDKs and do not install the native executable. Install the engine separately before adding either SDK to an application.

Start the MCP server over stdio with:

plasmate mcp

A Claude Desktop configuration uses the plasmate executable with mcp as its argument. Cursor, VS Code Copilot, and Windsurf use the same MCP server definition in their respective configuration files.

For Streamable HTTP, select the transport explicitly and provide a capability token:

PLASMATE_MCP_HTTP_TOKEN="$(openssl rand -hex 32)" plasmate mcp --transport http --host 127.0.0.1 --port 9272

Requests to the resulting /mcp endpoint must send the token as a Bearer authorization header. The endpoint returns HTTP 405 for GET requests rather than exposing an SSE notification stream.

Tools and capabilities

The MCP tool surface includes:

• Fetching SOM data, readable text, and deduplicated links
• Inspecting pages, taking screenshots, and checking cache or session state
• Opening, navigating, and closing stateful browser sessions
• Clicking, typing, selecting, scrolling, toggling, and clearing controls
• Evaluating JavaScript in a page context
• Reading, setting, and clearing session cookies
• Inspecting, exporting, clearing, and validating retained action traces
• Reviewing bounded ARD discovery signals and evaluating robots.txt policy

Element selectors can narrow returned content to areas such as the main region, sidebar, headings, or interactive elements. Action-oriented selectors can also build a compact menu of clickable, typable, selectable, toggleable, submit, or resettable controls.

Limitations and notes

The CDP implementation covers a documented subset intended for supported Puppeteer workflows, rather than claiming complete browser protocol coverage. SOM output is dependent on page and serialization details, so token reduction should be evaluated against the target sites and model tokenizer. HTTP deployments require explicit token authentication, and the server does not provide an SSE notification stream for GET requests.