MCP Tools

VulpineOS provides a Model Context Protocol  (MCP) server that exposes browser automation as tool calls. OpenClaw agents use these tools to browse — every action goes through Camoufox.

./vulpineos --mcp-server

Available Tools (12)

vulpine_snapshot

Get a token-optimized DOM snapshot (Phase 3). The primary tool agents use to understand the page — returns >50% fewer tokens than raw HTML. Interactive elements include @ref identifiers for click/type by reference.

{
  "name": "vulpine_snapshot",
  "arguments": { "sessionId": "sess-1", "viewportOnly": true }
}

Returns compressed DOM with element refs:

{"v":1,"title":"Example","url":"https://example.com","nodes":[
  [0,"doc","Example"],
  [1,"a","Home",{"hr":"/"},"@0"],
  [1,"btn","Sign Up",null,"@1"]
]}

vulpine_click_ref

Click an element by its @ref from the snapshot. Resolves the element’s position, scrolls it into view, and dispatches mouse events.

{
  "name": "vulpine_click_ref",
  "arguments": { "sessionId": "sess-1", "ref": "@1" }
}

vulpine_type_ref

Focus an element by its @ref and type text into it.

{
  "name": "vulpine_type_ref",
  "arguments": { "sessionId": "sess-1", "ref": "@0", "text": "hello world" }
}

vulpine_hover_ref

Hover over an element by its @ref.

{
  "name": "vulpine_hover_ref",
  "arguments": { "sessionId": "sess-1", "ref": "@2" }
}

vulpine_navigate

Navigate to a URL.

{
  "name": "vulpine_navigate",
  "arguments": { "sessionId": "sess-1", "url": "https://example.com" }
}

vulpine_click

Click at specific pixel coordinates.

{
  "name": "vulpine_click",
  "arguments": { "sessionId": "sess-1", "x": 400, "y": 300 }
}

vulpine_type

Type text into the currently focused element.

{
  "name": "vulpine_type",
  "arguments": { "sessionId": "sess-1", "text": "search query" }
}

vulpine_screenshot

Capture a page screenshot (returns base64 PNG).

{
  "name": "vulpine_screenshot",
  "arguments": { "sessionId": "sess-1" }
}

vulpine_scroll

Scroll the page by a specified amount.

{
  "name": "vulpine_scroll",
  "arguments": { "sessionId": "sess-1", "deltaY": 500 }
}

vulpine_new_context

Create a new isolated browser context with its own cookies, storage, and fingerprint.

{
  "name": "vulpine_new_context",
  "arguments": {}
}

vulpine_close_context

Close a browser context and release its resources.

{
  "name": "vulpine_close_context",
  "arguments": { "contextId": "ctx-a8f2" }
}

vulpine_get_ax_tree

Get the raw accessibility tree (injection-filtered). Use vulpine_snapshot for token efficiency — this is for compatibility.

{
  "name": "vulpine_get_ax_tree",
  "arguments": { "sessionId": "sess-1" }
}

Ref-Based Workflow

The recommended agent workflow:

1. Call vulpine_snapshot to get the page DOM with @ref identifiers
2. Agent reads the snapshot and decides which element to interact with
3. Call vulpine_click_ref or vulpine_type_ref with the @ref — no coordinates needed
4. Call vulpine_snapshot again to see the result

This is more reliable than coordinate-based clicking because refs resolve to the actual DOM element, scroll it into view, and compute the center point automatically.

OpenClaw Integration

VulpineOS auto-generates ~/.openclaw-vulpine/openclaw.json. When foxbridge is available, it sets browser.cdpUrl so OpenClaw uses its native CDP browser tools through Camoufox:

{
  "browser": {
    "enabled": true,
    "cdpUrl": "ws://localhost:9222"
  }
}