Skip to main content
Forwarding connects a loopback port on the browser’s machine to a loopback service on the agent’s machine. Use it to preview an app running beside your agent without exposing that app on a public port.

​
Create a forward

  1. Start your service on the agent machine, for example on 127.0.0.1:3000.
  2. Call browser_create_forward with browserPort: 8080 and targetPort: 3000. Both hosts default to 127.0.0.1; ::1 is also supported when selected explicitly.
  3. Save the returned capability object to a private file readable only by you, then run this command on the agent machine:
Alternatively, supply the capability JSON through stdin with browser-mcp forward --stdin. Never paste it into a command argument, URL, or chat. On POSIX systems, capability files must have mode 0600. Windows file-permission protection is not supported; do not use capability files there.
  1. Use browser_list_forwards to confirm listener-ready, then open http://127.0.0.1:8080 in the connected browser.
listener-ready means the browser-side listener and both relay connections are ready. It does not prove that your target service is reachable. If the page fails, check that the service is running at the selected target address and port. The Browser MCP server must use HTTPS/WSS, even when the service being forwarded uses HTTP. The forwarding helper does not need Chrome or a display.

​
Stop and expiry

Call browser_stop_forward with the returned forward ID, or stop the local forwarding command. Forwards also close when the browser disconnects or pauses, a credential is revoked, or the lease expires. The default lifetime is five minutes. Set ttlMs between one second and fifteen minutes when creating the forward. There is no renewal or automatic reconnect; create a new forward when needed. Streams and HTTP requests are not replayed after a disconnect.

​
Limits and security

  • TCP and explicit loopback addresses only. No LAN targets, public listeners, UDP, SOCKS, Unix sockets, or destination DNS names.
  • An occupied browser port causes an error; existing listeners are not replaced.
  • Up to eight forwards per authenticated scope, 32 connections per forward, and 1 GiB transferred per forward. Idle TCP connections close after two minutes.
  • Loopback is not per-tab authorization: other local processes and potentially browser pages can access the listener. Forward only services you are authorized to expose to the connected browser.
  • The capability is a short-lived bearer credential. Treat it as a password. MCP structured results are not hidden from the model.
  • The relay can see forwarded bytes; this is not end-to-end encryption against the server operator.
See security and the tool reference for authorization and command details.