Connect without a control port.
headless-mcp is a stdio JSON-RPC MCP adapter over the same local Unix socket used by the CLI. It creates no TCP listener. Start the local browser host first, then configure a remote agent to run it through SSH:
01 / Project configuration
Use the checked-in launcher.
Add this configuration at the project root. The launcher selects the repository runtime and exposes the normal CLI argument list as one MCP tool.
{
"mcpServers": {
"headless": {
"command": "./.agents/skills/headless-computer-use/scripts/headless-mcp.sh",
"args": [],
"env": {}
}
}
}02 / Remote agent
Tunnel stdio, not DevTools.
The single MCP tool mirrors the remote CLI command surface, including stop and session close. Its discovery metadata is therefore explicitly non-read-only, destructive, non-idempotent, and open-world; clients should confirm mutating calls according to their policy. These annotations are hints, not a substitute for the host's socket, validation, and navigation boundaries.
ssh your-host headless start
ssh your-host headless-mcpThe tool can stop the host and close sessions. MCP annotations mark it mutating, destructive, non-idempotent, and open-world so clients can apply their own confirmation policy.