How to use unsurf from an AI agent

Unsurf gives agents two complementary control planes:

local browser MCP for the real authenticated browser on the user’s machine
hosted MCP for shared scout/search/plan surfaces

Connect the local browser

{
  "mcpServers": {
    "unsurf-local": { "command": "unsurf-local-mcp" }
  }
}

Use:

unsurf_local_sessions
unsurf_local_execute

This is the right path for dashboards, apps behind login, and any task where the active user session matters.

Connect hosted Unsurf

MCP config

{
  "mcpServers": {
    "unsurf": {
      "type": "streamable-http",
      "url": "https://unsurf-api.coey.dev/mcp"
    }
  }
}

Use hosted MCP for:

scout
worker
heal
trace search / planning surfaces

Agent decision tree

Need the user's existing login?
  → local browser MCP

Need proof of what happened?
  → record or loop

Need a repeated direct HTTP seam?
  → scout → worker → heal

Prompt guidance

When the user's browser session matters, use unsurf-local first.
When the task should be reviewable, record it.
When success is visual, use loop with a yes/no North Star.
When the site exposes a stable API worth reusing, scout it and replay with worker.