Skip to content

Tools and connections

Familiar always has its own tools for time, memory and schedules. Open Connections in the header to add more and to see whether each one is ready.

The installed Familiar includes the web plugin with two tools:

  • web_search searches through Brave Search. It needs a Brave Search API key. Paste one into the Web search connection. Any Brave plan with Web Search works.
  • web_fetch reads a public web page as text. It needs no key. It doesn’t run the page’s JavaScript and doesn’t read PDFs or images.

Familiar sends the Brave key only to Brave’s search endpoint. Keys are write-only. Connections shows whether a key is set, never its value. Both tools refuse private and local network addresses.

Treat what these tools bring back as untrusted. A web page can contain text written to mislead the model.

Familiar can use tools from Model Context Protocol servers. Add one under Connections with a short name, such as home-assistant, and a transport:

  • HTTP: the server’s URL, with an optional bearer token. Familiar sends the token only to that server’s origin and path. Use https:// when the token crosses a network you don’t trust. HTTP servers can be on your private network.
  • Local command: a program and its arguments, such as uvx mcp-server-time. Familiar starts it on the computer it runs on.

Connections shows each server’s status, for example Ready, Needs a token or Failed, and can reconnect or remove it.

A connection’s tool can run as soon as a Familiar calls it, ask you first, or never run. By default, Familiar asks for tools that explicitly declare a destructive action. Tools without hints run by default. Check Ask first on any tool you want to approve manually.

When a tool asks, the reply shows Waiting for you with Approve and Decline, and you get a notification if they’re turned on. Declining tells the Familiar you said no. If you send the Familiar a new message instead, the question is declined and it reads your message.

An MCP server can also ask you something itself while a tool runs, such as “Start printing benchy.gcode?” or a short form. Its question shows the same way. Familiar shows yes or no, text, number and single-choice questions; anything else can only be declined.

Use Enabled to turn a tool off temporarily. It keeps its Ask first setting while disabled. For a tool whose server already asks for approval, you can uncheck Ask first to rely on the server’s question.

To give Familiar tools of your own, written in TypeScript, see Extend your Familiar.

In Connections, open an MCP server, expand a tool, and check Run in background for calls that can report back later. For example, a printer watch can keep waiting while its Familiar replies elsewhere, then report the result in the original room. Ask first still applies before the call starts. Keep tools foreground if the current reply needs their result. While a background call is active, Familiar declines server questions on that connection because it cannot reliably match them to a room turn.

A restart can interrupt an ordinary MCP request. Familiar reports the interruption without sending the request again. Removing the server stops its local background jobs and forgets its tool settings. The remote server may have already acted.