Plugins

A plugin gives the agent tools it can use in an Agentic chat. Each plugin is an MCP server: a service that offers a set of tools, such as "search Google" or "read this page". You connect it once, choose what each tool may do, and the agent calls those tools when your question needs them.

Plugins work in Agentic chats only. In a Basic (Q&A) chat, the Plugins menu is greyed out with the hint "Plugins work in Agentic chats".

There are three kinds:

• By SurfSense. SurfSense's own plugins, such as Google Search, Web Crawl and YouTube. They need a SurfSense license.
• Third-party. Plugins from other publishers, listed in Browse once you allow them.
• Custom. Any remote MCP server you add by its URL.

Settings › PluginsCopy Anchor Link

Open Settings › Plugins. It has two tabs, Browse and Yours, and an Add custom plugin button beside them. It opens on Yours when you have a plugin connected, and on Browse otherwise.

• Browse lists what you can connect. By SurfSense comes first, each plugin with its logo, a short description and "License required". Third-party follows, with the Allow third-party plugins switch in its header.
• Yours is a table of the plugins you added, with Plugin, Type and Status columns. Type is By SurfSense, Third-party or Custom. Click a row to open the plugin's details.
• Search plugins, beside the tabs, searches both lists at once by name, description, author or tool name. Results show Yours first, then Available.

Click a plugin in Browse to open its page. It shows About, the plugin's Tools, and Details: Publisher, Authentication, Connects to, Added, and links to its homepage and privacy policy. You can read all of this before you connect anything.

Connect a pluginCopy Anchor Link

A toast says "Reddit connected", for example, or "Couldn’t connect Reddit" with the reason and Report issue. The plugin then appears in Yours with the status On.

From the chat, + › Plugins › Add plugin takes you to Browse plugins or Add custom plugin, and Manage plugins opens Settings › Plugins.

Statuses in YoursCopy Anchor Link

A plugin's detailsCopy Anchor Link

Click a plugin in Yours to open its details. At the top is one action, Connect or Disconnect, and a menu with more:

• Refresh tools asks the server for its tools again.
• Edit connection or Edit headers changes the keys you gave it.
• Change OAuth app, when you signed in with your own app.
• License settings, when your license was refused.
• Submit to the registry, on a custom plugin.
• Remove deletes the plugin, its key and its tool settings.

Disconnect drops the key or sign-in but keeps the plugin and its tool settings in Yours, so you can connect it again later.

Tool permissionsCopy Anchor Link

A plugin's details list its tools in two groups, Read-only and Can make changes. Each tool has three icons:

Each group has its own menu, Always allow, Needs approval or Blocked, to set every tool in it at once. It shows Custom when the tools differ.

Some choices are closed, and the icon's tooltip says why:

• SurfSense's read-only tools never ask. "Needs approval" is dimmed on them: "Not needed: this tool only reads". Every tool of SurfSense's own plugins only reads.
• A tool that doesn't say it's safe always asks. If the server doesn't mark a tool as read-only or harmless, "Always allowed" is dimmed: "Not available: the server doesn’t say this tool is safe".
• Other tools ask by default. A tool from a third-party or custom plugin asks before each use until you set it to Always allowed.

New and changed toolsCopy Anchor Link

Every tool a plugin offers when you connect it starts on. After that, SurfSense checks the plugin's tools before chats. A tool the server adds later starts off and is marked New. A tool whose description changes, or that becomes less safe, is switched off and marked Changed. The plugin's details say "Some tools are new or changed. They stay off until you allow them." Pick a permission for the tool to allow it.

The check covers a tool's description and how safe its server says it is. A server can still change what a tool does without changing either, so allow tools only from servers you trust.

Use plugins in a chatCopy Anchor Link

Plugins work in Agentic chats. The agent picks the right tool from your question, so most of the time you just ask.

• Mention a plugin. Type @ in the composer and pick a plugin, such as @youtube. The agent then uses that plugin for this message.
• Switch plugins on and off. + › Plugins lists your connected plugins, each with a switch. The switch "Applies to all Agentic chats", not only this one.
• Approve a step. When a tool needs approval, the chat shows "Allow this step to run?" with what the agent wants to send. Click Allow once or Deny. Chats waiting on you are marked "Waiting for your approval".
• Read a step. Each plugin call shows as a step named after the plugin and tool. Open it to see the whole result.
• Save to Sources. On a finished plugin step, Save to Sources keeps its result as a note in your Sources, so later chats can cite it. Saving the same step again updates that note.

When a plugin can't be used, the reply says so above its steps and carries on without it: for example "Couldn’t reach Notion", "Sign in to Notion again", "Notion needs more access" or "Amazon needs a SurfSense license".

Plugins and Add from the webCopy Anchor Link

+ › Add from the web… in Sources uses SurfSense's own plugins to search the web and pull links into your Sources, with no chat needed. You don't have to connect the plugins in Settings › Plugins for this. It needs a SurfSense license and plugins.surfsense.com allowed in Settings › Network. See Sources, and each SurfSense plugin page for which links it handles.

What a plugin can seeCopy Anchor Link

A plugin's server gets what the agent sends its tools, the keys, headers or sign-in you saved for that plugin, and your IP address. It can't open your files or Sources, but the agent may put text from the sources ticked for a chat into what it sends, such as a search query. Nothing a plugin returns goes into your Sources unless you save it.

Your keys, headers and sign-ins are stored encrypted on your computer. SurfSense adds them to each request itself, so the agent and the model aren't given them. A plugin's reply goes to the agent as it is, though, so if a server echoes a key back, such as in an error, the model and the chat see it.