Surf Connector

For Surf on Mac · Surf requires macOS 14 or later · Guide updated 15 October 2026

Give your assistant a browser to work in. A compatible local MCP client can read and act in its own Surf tabs while you continue browsing.

"surf": {
  "command": "/usr/local/lib/surf/surf-connector",
  "env": { "SURF_CONNECTOR_NO_UPDATE_CHECK": "1" }
}

/usr/local/lib/surf/surf-connector --identity

Why it is a separate download

Claude talks to other programs over a standard called MCP, which means starting a small program of its own. An app from the Mac App Store is not the right thing to be writing programs onto your disk for something else to run, so we ship this one separately, signed with Developer ID and notarized by Apple in its own installer. It is also why Surf asks you to point at it rather than guessing where it is: a guess that is wrong produces a setup that looks finished and quietly does nothing.

Install it

1. Download SurfConnector.pkg — protocol 8, 226 KB — and open it. macOS checks Apple's notarization before it runs.
2. Open Surf, then the … menu → Add-Ons.
3. Press Choose the Connector… and pick the program the installer placed at
   /usr/local/lib/surf/surf-connector.
   The open panel starts there. If you put the program somewhere else — ~/.local/bin is the usual choice when you would rather not type an administrator password — press ⌘⇧G in the panel and type that path instead. Surf records whatever you pick; it never guesses.
4. Follow the setup for whichever assistant you use — choose your assistant below.
5. Quit that assistant completely and open it again. Sessions already running will not see Surf.

Already have it? Verify it before reinstalling. Surf 1.14 for Mac, build 138 and later, requests remembered read-only access to check the selected connector after you relaunch Surf. If you chose it in an earlier build, press Verify Installed Connector… in Settings › AI Assistants or Add-Ons › AI Assistants when prompted, and select the already installed surf-connector. This is a one-time permission step when access is missing, not another installation. Verification only reads the selected file, never writes it, does not request parent-folder permission and does not run the connector to inspect it.

Up to date — no update needed means the readable selected file matches the latest download or, when Surf cannot read that file, a currently connected session does. Surf identifies the evidence it used. Download Again is optional. Older sessions get a separate instruction to restart their Surf connection or start a new session; they do not hide another current session. An older session or saved history alone does not prove the installed file needs an update. When Surf cannot verify the file or a current connection, it says so. Failed or disabled update checks remain explicit.

With update checks enabled and a connector on record, Surf checks at launch, when you open AI Assistants in Settings or Add-Ons, after you choose a connector, and when you turn checks back on. Check Now also requests a fresh comparison. You can turn these requests off in Settings › AI Assistants. The comparison uses the static connector.json described above; your installed build stays on your Mac.

If your build differs from the latest download, install it over the top — your existing setup is kept. The change that matters most in protocol 8 is not something an older connector cannot do — it is something it describes wrongly. An older connector tells the assistant it can only see the tabs it opened, and leaves it to conclude that it is browsing in a sandbox of its own. It is not. Every tab it opens is an ordinary Surf tab using your ordinary cookies, so a site you are signed into is signed in for it, and a sign-in or a sign-out it performs is one your own browsing keeps afterwards. An assistant holding the older description will switch an account or sign out of one believing it is tidying up after itself; this one is told whose browser it is in, on every reply. Alongside it: it is now told when closing its own tab moved which tab you are looking at, rather than asking you about something you did not do; the key names it may send are the ones Surf actually accepts, and pressing a shifted key now types the shifted character; and a full-page capture reports the coordinates it was really taken in, which is the difference between a click that lands and one several hundred pixels adrift. Surf says so in Add-Ons when a connected session is running an older connector, and tells the session directly on every reply — the assistant is the one that needs to know, and it never looks at a panel. As above, quit the assistant and open it again afterwards, or it will keep using the copy it already started.

Set it up in your assistant

The connector is a local MCP server for compatible assistant clients, with the same refusals, the same switch and the same per-session tabs. Surf 1.14 for Mac provides a ChatGPT & Codex choice in Settings › AI Assistants, with connector-path, Codex-command and TOML copy buttons. On earlier versions, configure your assistant separately using the instructions below. You need Surf Pro, the connector installed and selected in Surf, and automation enabled in Settings › AI Assistants or … → Add-Ons (named Claude in earlier Surf versions).

The three facts every tool needs

Whatever the tool calls its config file, it is asking for the same three things.

1. The program to run: /usr/local/lib/surf/surf-connector
   If you installed the connector somewhere else, use that path instead — this is only where the installer puts it. (Newer versions of Surf can copy it for you: … menu → Add-Ons → Copy Connector Path.)
2. No arguments, and a local / stdio server — not a URL, not a remote server. The connector is a program the tool launches, not a website it calls.
3. A generous request timeout: 60 seconds. This is the one that will bite you, and it is a setting rather than a bug — see below.

One more thing worth doing if your tool offers it: give the server a working directory pointing at the project you are on. Surf names each connected session after that folder and the tool — my-project · opencode — and that name is what labels its tabs in the tab strip. Without it, two sessions look identical.

codex mcp add surf -- /usr/local/lib/surf/surf-connector

[mcp_servers.surf]
command = "/usr/local/lib/surf/surf-connector"
tool_timeout_sec = 60

{
  "mcpServers": {
    "surf": {
      "command": "/usr/local/lib/surf/surf-connector"
    }
  }
}

{
  "mcp": {
    "surf": {
      "type": "local",
      "command": ["/usr/local/lib/surf/surf-connector"],
      "enabled": true,
      "timeout": 60000
    }
  }
}

{
  "context_servers": {
    "surf": {
      "command": "/usr/local/lib/surf/surf-connector",
      "args": [],
      "env": {}
    }
  }
}

{
  "mcpServers": {
    "surf": {
      "command": "/usr/local/lib/surf/surf-connector",
      "args": []
    }
  }
}

{
  "servers": {
    "surf": {
      "type": "stdio",
      "command": "/usr/local/lib/surf/surf-connector"
    }
  }
}

Check it worked

1. In Surf, open … → Add-Ons and turn the Claude switch on. It starts off, and from Surf 1.12 for Mac it stays where you leave it — Automation › Stop Automation turns it off again from anywhere. (In Surf 1.11 and earlier it was off at every launch.)
2. Start your assistant fresh and ask it: “Use Surf, not Chrome, to open example.com and tell me the heading.”
3. Watch Surf. A tab opens, a coloured edge appears around the page, and a marker in the toolbar says how many tabs that session has.

Say Surf by name. If a Chrome extension is installed as well, “use the browser” is ambiguous and your assistant will usually reach for Chrome.

The Add-Ons panel lists every connected session by name, with its tab and request counts, so you can see the connection from Surf’s side without asking the assistant anything.

When it doesn’t

• The tool doesn’t list Surf at all. It did not reload its config. Quit it completely and start it again — a new window or a new chat is not a new session, and MCP servers are launched once at startup.
• “Server failed to start”. The path is wrong. Check the file is really there: ls -l /usr/local/lib/surf/surf-connector. If you installed it elsewhere, use that path.
• Requests time out, or the server looks like it crashed. The timeout is too short. Set 60 seconds. See the note above — this is the most common cause and the least obvious.
• “Surf isn’t running” or nothing connects. Surf itself must be open, with the Add-Ons switch on, and signed in to Surf Pro. The connector is free; the Surf side is not.
• It connects but refuses to type a password or card number. That is deliberate and cannot be turned off. So is never exposing private tabs.
• A session says a safeguard is missing. Add-Ons will tell you when a connected session is running an older connector than this version of Surf. Install the current one over the top and start the tool again.

What it can and cannot do

While you have the feature switched on, your connected assistant can read the address, visible text and elements of a page it is working with — including anything already typed into an ordinary form field on it — take a picture of it, and see the messages and network requests that page made. It can also click, type, scroll and drag, go back and forward, open and close its own tabs, and resize its working page. In Surf 1.14 for Mac, resizing a detached background tab changes only its viewport. Resizing a visible assistant-owned tab changes that tab’s window. Earlier Surf versions can resize the visible window during background work. It can cause a file to be saved to your Mac, the same way following a download link yourself would; each one is reported back by name and path. Surf hands anything over only when asked.

Surf refuses some things in its own code, whatever it is asked. Private tabs are never exposed. Password fields are never filled, and Surf refuses any field it recognises as a card, security code or one-time code. What you typed into one is never read either: it is left out of what the assistant is told, and Surf hides it for the moment a screenshot is taken, so it is not in the picture either. Recognising a card field depends on how the site marks it up, so treat it as a strong safeguard rather than a guarantee. A session can only touch tabs it opened, or a tab you have handed to it deliberately.

It browses as you, in your own browser. A tab a session opens is an ordinary Surf tab with your ordinary cookies — there is no separate, signed-out profile behind the feature. So a site you are signed into is a site the session is signed into: it can open your account there, read it, and act as you. That runs both ways — if a session signs in to a site, or signs out of one, that is what your own browsing finds the next time you go there. Tab ownership keeps a session out of your other tabs; it does not give it a browser of its own. Private tabs are the exception on both counts: they keep their own cookies in memory, and Surf never exposes them to a session at all.

You can see when it is happening. While a session is working, Surf draws a coloured edge around the page and shows a marker in the toolbar saying how many tabs that session has; clicking it takes you to the one being worked on. Each session gets its own colour, and the same colour marks its tabs in the tab strip. This matters because the assistant can work in a background tab — one you are not looking at — so the window itself has to tell you. Those signals need a window to appear in, though: Surf keeps running with its window closed so downloads finish, and nothing is drawn anywhere at that point. Automation › Stop Automation is in the menu bar the whole time, which is the switch to rely on.

What your assistant does with what it receives is between you and its provider — it will send that content on to be processed, and Surf can neither see nor limit that. A page's own text can also try to influence an assistant that is reading it. Surf is not immune to that, and no browser is. The feature does nothing until you switch it on for exactly these reasons, and Automation › Stop Automation is in the menu bar the whole time it is running so that turning it off never requires finding a settings pane.

Full detail is in the privacy policy, section 7.

Check what you downloaded

The installer is signed by MW Supply Limited and notarized by Apple, so macOS verifies it for you before it will open. The certificate reads Developer ID Installer: Matthew Wong (6RZ8YV42XZ) — that is us; Apple issues these in the account holder’s name. If you would rather check it yourself:

shasum -a 256 SurfConnector.pkg

9245fc1c077a066ab665d2f1f59a1223f37082135cc1aa68501f8bd087e694db

spctl --assess --type install -v SurfConnector.pkg should answer accepted · source=Notarized Developer ID.

Remove it

Remove the surf entry from each assistant you configured, then delete the connector from its installed location (/usr/local/lib/surf/ for the installer above). The installer adds nothing else and runs no scripts. While it is running the connector writes one small file inside Surf’s own storage — the port Surf should call it back on — and removes it again when it exits.

Independent of your assistant provider

Surf and the Surf Connector are made by MW Supply Limited. Claude is a product of Anthropic; ChatGPT and Codex are products of OpenAI. Neither company sponsors or endorses Surf. You use your own assistant software and account. Surf provides no AI account and does not receive your assistant account credentials.