Surf Connector

For Surf on Mac · Surf requires macOS 14 or later

Protocol 8 is the version number, and it is the only one worth comparing. Three places tell you what you already have, and they should all say the same thing:

• The program itself: /usr/local/lib/surf/surf-connector --version prints surf-connector protocol 8.
• Surf: Settings › Claude (or … → Add-Ons) shows the protocol Surf speaks and the one it has on this Mac, side by side. From Surf 1.12 for Mac it also raises a bar under the toolbar at launch when they differ, so you are told without having to go and look.
• This page: the number on the button above is what the download contains. If it is higher than what you have, this is the newer one.

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 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, 189 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 — the walkthroughs are below.
5. Quit that assistant completely and open it again. Sessions already running will not see Surf.

Already have it? This one is newer, and the difference is not cosmetic. Install it over the top — same steps, and 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 an ordinary MCP server, and nothing in it is specific to Claude — any tool that speaks MCP can drive Surf, with the same refusals, the same switch and the same per-session tabs. Surf’s own buttons write the config file Claude uses, so for anything else you add one entry to that tool’s own configuration. Below is a walkthrough for each.

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.

{
  "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, Claude 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, go back and forward, open and close its own tabs, and resize the Surf window. 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 Claude 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 Claude usually works 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

f69669f44b8d770659ffe40a6c2cee8060454a7e1c4a973f0b5a9ab70e8b3483

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

Remove it

Delete /usr/local/lib/surf/ and remove the surf entry from your Claude configuration. 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.

Not affiliated with Anthropic

Surf and the Surf Connector are made by MW Supply Limited. Claude is a product of Anthropic, which does not sponsor or endorse Surf. You need your own Claude software and your own account; Surf has neither and never sees yours.