Connect an MCP client

An MCP client can run the installed beaconctl tool as a local stdio server. The browser starts automatically on the first browser tool call; initialization and tool discovery work while the app is stopped.

Configure the client

For an app installed in /Applications, add this entry to a client that uses an mcpServers configuration:

{
  "mcpServers": {
    "beacon": {
      "command": "/Applications/Beacon.app/Contents/MacOS/beaconctl",
      "args": ["mcp"]
    }
  }
}

If the app is in ~/Applications, replace the command with its full absolute path. The exact configuration location depends on your MCP client. No separate Node.js installation is needed.

Use the browser tools

Tool	Purpose
`browser_info`	Discover methods and current engine limitations
`browser_command`	Call a method with its `method` name and `params` object

Call space.create with a task name to join the shared browser space. Use its returned spaceId and agentPageId in subsequent page commands, especially when tasks run concurrently. Observe a snapshot before choosing a reference or selector, then verify the result of each action.

Stop sending browser actions when a person takes over. The MCP tools enforce the same task-control boundary as the CLI.

Custom connection settings

Put connection options before mcp in the argument array. For example:

{
  "command": "/Applications/Beacon.app/Contents/MacOS/beaconctl",
  "args": ["--port", "9226", "--token-file", "/absolute/path/agent-token", "mcp"]
}

The client normally reads the private token from the app's local data directory. Do not paste it into MCP configuration. For token paths and endpoint behavior, read CLI and local API.