Custom tools

The built-in tools cover files, the personal stores on your Mac, web search, and a handful more. When none of them fit, you bring your own. Conifer speaks the Model Context Protocol (MCP), so a custom tool is an MCP server: a small local program that advertises a set of tools, and that the agent calls mid-turn the same way it calls read_file. You write the server. Conifer writes the rules it runs under.

What a custom tool is#

An MCP server is a process you name by its launch command. Conifer starts it, asks what tools it offers, and surfaces those tools to any agent you grant them to. The server can be a published package run through npx or uvx, or an absolute path to a binary you wrote this afternoon. To the agent, a custom tool is indistinguishable from a built-in: the model emits a structured call, the runtime checks it against the grant, runs it if the grant allows, and feeds the result back into the context.

Installing a server adds it to a local registry on your machine, nothing more. A server with no agent granted to it never starts. An agent you haven’t scoped any of its tools to gets none of them.

Add a server#

Open settings → MCP servers in the studio. Pick a curated entry for a one-click install, or add a custom one by hand: a name, the command, its arguments, and any environment variables it needs, such as an API token. Before it spawns anything, Conifer shows you the exact argv it will spawn, so the command you approve is the command that runs.

name     My local tool
command  npx
args     -y
         @my/mcp-server
env      API_KEY=...

The CLI speaks MCP too, if you’d rather script it: it can bridge an HTTP MCP server by its endpoint URL. Either way, the entry stays inert until a grant turns it on.

Scope it with a manifest#

A grant for a custom tool is a small capability manifest you author per server. It lists which of the server’s advertised tools the agent may call, and the exact resources those tools may touch. You write the manifest. The server never gets to widen it by advertising more.

Every field defaults to empty, so a freshly installed server grants nothing until you fill one in. Paths are absolute or home-relative; the broker rejects a relative path and treats a * as a literal character.

Leave a field empty and that door stays shut. A scraper tool with network_hosts set to one API and an empty write_paths can talk to that host and write nothing to disk. The same deny-by-default authority that gates the built-ins carries straight into the custom tool. The rule itself lives in the grant model.

How a granted tool is held to its grant#

Authentication says who the server is. The grant says what it may do. Two independent checks bound a custom tool, and neither one comes from the server.

The model can’t even ask

Only the tools you granted enter the constrained-decoding grammar and the system-prompt tool list. A tool you didn’t grant is not in the grammar at all, so the model cannot emit a syntactically valid call to it. See optimizing around the tool call.

The kernel won’t run an out-of-bounds call

Every call passes a broker chokepoint that authorizes it against your manifest before the server is contacted. A granted tool whose arguments reach a path or host you didn’t list is refused, and the server runs inside a kernel sandbox scoped to the same grant, so even a misbehaving one is denied by the OS.

Where the network boundary sits#

Conifer runs on your hardware and the server runs beside it, yet a custom tool can still reach off the machine when you let it. A tool that calls a remote API does so because you put that API in network_hosts, and the sandbox blocks every host you didn’t. The outbound call is logged like any other, so a tool that talks to the network never does it quietly. Read data boundaries for the line-by-line account of what leaves.

For the integrations Conifer ships and maintains, start with the connectors catalog. Reach for a custom tool when nothing there fits and you want the agent to do something specific to your work.