Tools, MCP servers and connectors
Tools are how agents act outside a conversation: read a CRM, file a ticket, price a quote. There are three kinds.
- Connectors are Whorl's link to a whole platform. Microsoft 365 comes first. People connect them in Settings → Company → Integrations. See Microsoft 365.
- MCP servers give agents another service's tools, such as Linear. Anyone can add one at a layer they can change.
- Custom tools are small programs for an exact step with typed input and output.
Tools show on the They can use line of the Agents card. See Agents and setup.
Connect an MCP server
Whorl connects only to remote servers over HTTPS. A server that has to run on your own computer must be hosted somewhere first.
-
Open the Agents card for the layer that should have the tools: the company for everyone, a Space for its members, or Settings → Agents for yourself.
-
On the They can use line, choose Add tool, then Connect an MCP server.
-
Enter the Server URL, taken from the service's own documentation. Do not guess it.
-
Enter a Server name, for example Linear.
-
Under How agents sign in, choose how agents prove who they are:
Choice Use it when My account The service uses a sign-in (OAuth). Each person signs in once, and agents act with that person's own account. A key The service gives you a key. Paste it in Paste the key. Whorl stores it encrypted and sends it with every request. Nobody can read it back. No sign-in The server asks for none. -
Choose Connect.
Agents can call the server's tools on their next run. The server's page shows its Connection state: Ready, Needs a key or Needs your sign-in. For a server that signs in with each person's account, choose Sign in and finish in the browser window that opens. Sign out ends it.
If a server shows Invalid URL, Host not allowed or Unsupported, check the address.
Turn a server off
A server belongs to the layer that defined it, and only people who can change that layer can remove it (Remove server). Removing a server deletes its saved key and agents stop using it.
If the company marks a server so that members can turn it off, you can choose Turn it off for me, and Turn it back on later. It only changes what your own agents use.
A server defined at a closer layer replaces a server with the same name from an outer layer. A personal server cannot switch off a company or Space server.
Custom tools
A custom tool is a small program that runs in the Thread's Environment. It takes and returns structured data that Whorl checks, and it can use a secret without ever seeing its value. Use one when a step must come out exactly the same each time, such as totalling a quote with your discount rules.
Custom tools are files in a layer's tools folder: a description that tells agents when to use it, and the code. To write one, see The whorl command, which scaffolds, tests and saves tools.
A tool is the right choice when the code can run in TypeScript. When the service already publishes an MCP server, use that instead.