# Tools, MCP servers and connectors

> Give agents tools by connecting an MCP server or adding a custom tool, choose how agents sign in, and turn a server off when you do not want it.

Source: https://docs.whorl.work/agents/tools

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](/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](/agents/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.

1. 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.

2. On the **They can use** line, choose **Add tool**, then **Connect an MCP server**.

3. Enter the **Server URL**, taken from the service's own documentation. Do not guess it.

4. Enter a **Server name**, for example Linear.

5. 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.                                                                                                                       |

6. 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](/agents/secrets) 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](/reference/cli), 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.

## Related

- [Agents and setup](/agents/setup)
- [Secrets](/agents/secrets)
- [Plugins](/agents/plugins)
- [Microsoft 365](/microsoft-365)