---
title: Connectors and skills
description: Give the agent more tools with connectors, playbooks with skills, and both together with plugins.
canonical_url: https://lookout.itoowasinarcadia.com/docs/connectors-and-skills
type: guide
section: Use Lookout
last_updated: 2026-10-22
related:
  - https://lookout.itoowasinarcadia.com/docs/rules
  - https://lookout.itoowasinarcadia.com/docs/agents
  - https://lookout.itoowasinarcadia.com/docs/other-apps
  - https://lookout.itoowasinarcadia.com/docs/settings
---

> Every page of these docs: https://lookout.itoowasinarcadia.com/llms.txt

# Connectors and skills

Give the agent more tools with connectors, playbooks with skills, and both together with plugins.

Three things extend the agent, each with its page in Settings (`⌘,`):

- A **connector** is an MCP server, a local command or a remote URL, whose tools the agent can call.
- A **skill** is a playbook in a `SKILL.md` file. The agent sees each skill's one-line description and reads the file
  when a task fits it.
- A **plugin** is a folder that bundles skills and connectors.

Connectors and skills apply **Everywhere** (every project) or in one project. Pick which in the scope menu at the top
of each page. When a project's connector has the same ID as one of yours, or its skill the same name, the project's
wins there and yours shows **Overridden**.

## Link an official connector

**Settings › Connectors** opens on its official connectors, each a tile over the connectors you added. An official
connector signs in with its host's own account, such as a Google account for Gmail, instead of a key you paste.

1. Open the tile and check what it **Can** and **Can't** do.
2. Click **Add**. The host's sign-in opens in your browser, and the page shows **Waiting for** the host with
   **Cancel** until you finish.
3. Pick the account and allow access. The account shows **Connected**.

Click **Link another account** for each account more. Each account is a connector of its own, so its tools keep
their own names. An account the host stops accepting shows **Needs sign-in**: click **Sign in again**. **Unlink**,
in the account's menu, signs Lookout out of it at the host and on every device.

Gmail's data never reaches a model whose provider may train on it. In a chat on such a model, Gmail shows **Off for
this model** in the connectors chip. Where the provider lets you turn training off, turn it off there, then click
**Training is off at** the provider in the chip, once. A chat that already read mail won't send it to such a model.

## Choose where a connector runs

A connector you added everywhere, or a linked account, has **Where**: **Everywhere**, or **Chosen projects and
agents**. Pick the projects and Lookout Agents it may run in; anywhere else it shows **Not here** and the agent
doesn't get it. The projects you pick are kept on this Mac. The agents you pick go with your account, so an agent on
another machine gets the connector there, and keeps it when it moves; a Mac that runs none of them never connects
to it.

## Add a connector

1. Open **Settings › Connectors** and pick the scope: **Everywhere** or a project.
2. Click **Add custom**.
3. Enter an **ID**: letters, digits, `_` and `-`. The agent's tools from it are named `mcp__<id>__<tool>`, so the ID can't change later.
4. Under **Transport**, pick **Remote URL** and enter its **URL**, or **Local command** and enter the **Command** and
   its **Arguments**, one per line.
5. With a project in scope, choose where it **Applies**: **Everywhere**, or only that project.
6. Click **Add everywhere**, or **Add to** the project.

It connects at the next turn in that scope; to check it now, open it and click **Test connection**. A working
connector shows **Ready** and the tools it gave.

Lookout's own MCP is for [other apps](https://lookout.itoowasinarcadia.com/docs/other-apps). A connector whose server is Lookout itself, by any name,
shows **Not for chats** and gives no chat its tools: a chat reaches Lookout through its own tools.

To add servers from a config in a server's instructions, click **Paste a config** and paste the JSON: a whole
`mcpServers` map or one server's settings.

## Add from a link

A server's own page may offer an install link (`lookout://mcp/install`, or on this site, `/mcp/install`). Opening
one shows the one connector it names in the add form, filled in for you to check over. Nothing is added until you
press **Add**, and it always lands in **Everywhere**, never in a project on its own.

A link carries only the name and where the connector runs. Anything credential-shaped in it (headers, environment
values, a caller identity) is left out, and said so on the form; add a key afterwards if the connector needs one.
Past one into **Paste a config** and you get the same review.

## Sign in to a connector

A remote connector whose server asks you to sign in shows **Needs sign-in** with **Sign in to** its name: in Settings
on the connector and in a chat's connectors under the message box. An agent's connector card shows **Sign in** at
its end.

1. Click **Sign in to** the connector (**Sign in** on an agent's card). Your browser opens the server's own sign-in
   page.
2. Sign in there and allow Lookout. The page says you can go back to Lookout.
3. The connector connects and shows **Ready** with its tools.

Lookout names itself to the server's sign-in only when you click, never before, and registers only where the server
needs it. The sign-in syncs through your
Lookout account, so your other devices, and an agent that runs on another machine, connect with it too; one device
renews it for the rest. **Sign out** under **Headers** on the connector forgets it everywhere. When the server stops
taking it, the connector shows **Needs sign-in** again. A server that offers no sign-in says it **takes an API key**
instead: give it one below.

## Give a connector a key

1. Open the connector (on an agent's card, **Add API key**).
2. Paste the key under **API key**. It goes to the server as `Authorization: Bearer <key>`; for a server that wants
   another header, click **Send it in another header** and name it. A local command takes a **Variable** and its
   **Value** instead.
3. Click **Save on this Mac**. It reconnects.

Keys stay on the Mac you enter them on, and their values never show again. A server that refuses its key shows
**Needs sign-in**. A saved key stays in charge of a browser sign-in for the same server; the connector says so. An
agent's own connector takes its key the same way, from its card in the agent's [Connectors](https://lookout.itoowasinarcadia.com/docs/agents#folder).

A project's `.lookout/mcp.json` can name a stored secret instead of holding a value: `"Authorization": "Bearer ${secret:EXAMPLE_API_KEY}"`. The connector then asks for that secret under **Secrets**, and sends nothing for it until you set it. A secret set for one connector is sent only to that connector's server; another connector naming it gets nothing. In an agent's home the value is that agent's secret and syncs like its other secrets.

Lookout doesn't expand `${VAR}` or `${env:NAME}` in a project's `.lookout/mcp.json`, and doesn't run a
`headersHelper` command. A repo could otherwise pull one of your credentials into a request it chooses, or run a
command of its own on every connect. Only `${secret:NAME}` expands; any other reference stays as written and is
flagged on the connector.

## Share connectors with a project

A project's connectors live in `.lookout/mcp.json` in its folder: commit the file and everyone on the repo gets them.
Adding a connector to the project in Settings writes this file, or you can write it yourself:

```json
{
  "mcpServers": {
    "docs": { "url": "https://mcp.example.com/v1" },
    "db": { "command": "npx", "args": ["-y", "some-db-mcp"] }
  }
}
```

An entry with a `url` is a remote server, one with a `command` runs on your Mac. Lookout changes only the entries it
manages and leaves the rest of the file as it is, so other apps that read the file keep working. It never writes a key
there.

## Trust a project's connector

A connector a project's file declares doesn't run until you trust it on your Mac. Until then its row shows **Needs
trust**.

1. Open **Settings › Connectors** with the project in scope, or choose **Connectors and skills** in the project's menu in
   the sidebar.
2. Click the connector. Lookout shows the exact command or URL it would run.
3. Click **Trust on this Mac**. When it has the same ID as one of yours, Lookout asks first, since it takes the place
   of yours in that project.

If the file's entry changes later, the row shows **Changed** and asks again. A connector you add through Lookout is
trusted when it is written. An untrusted project connector never takes the place of one of yours with the same ID.

## Tell a server who calls

A connector can learn who calls each of its tools: which of your agents, in which chat and turn, started by whom, on
which Mac. It is off until you turn it on for that connector, so a server learns nothing about your agents, chats or
Macs by default.

1. Open the connector in **Settings › Connectors**.
2. Under **Identity**, set **Caller identity** to **On**, or **Signed** for a remote URL the server checks.
3. To sign in to the server as its own client, enter the **Client ID** and **Scope** the server gave you, then click
   **Save client**. The **Issuer** the server names then is kept, and a server that later names another reads **Needs
   sign-in** until you save the client again.
4. Click **Copy public key** on the **Key** row and register it with the server. **Rotate** makes a new key, which
   the server has to register again.

A server that refuses the key shows its own words at the top of the connector, with **Copy public key** beside them.

A project's entry turns it on in a `lookout` block, which other apps that read the file ignore:

```json
"ops": { "url": "https://ops.example.com/mcp",
         "lookout": { "identity": "signed",
                      "auth": { "type": "client_credentials", "clientId": "agent-hazel", "scope": "fleet.read" } } }
```

- `identity`: `off`, `on` (each tool call carries who called it), or `signed` (the same, signed with the caller's key,
  so the server can check it). Signing needs a remote URL.
- `auth`: optional. The connector signs in to the server as its own client, with no browser: each agent gets its own
  client and key, so the server can give each agent its own access. Register the client and its public key with the
  server first.

Lookout fills in who called from the chat itself, so nothing the agent writes can change it. Each key is made on the Mac that
uses it, one per connector and agent (or one for the Mac, for chats no agent owns), and never leaves it: it is never
synced, exported or shown to a command the agent runs. The block counts toward trust, so a change to it shows
**Changed** until you trust the entry again.

## Turn a connector's tools on or off

Every tool a connector gives is **On**: the agent calls it when your request needs it, whether it reads, changes or
sends something, and nothing waits for you in the chat. To keep the agent from a tool:

1. Open the connector, or an account's row on an official connector's page, and click **Tools**.
2. Under **Reads** and **Changes**, set the tool to **Off**. **On** puts it back.
3. To make an exception for one of your Lookout Agents, click the agent button at the end of the tool's row and check
   the agent: under **Off for** while the tool is on, under **On for** while it is off. The row then names the agent.
   An agent's [Connectors](https://lookout.itoowasinarcadia.com/docs/agents#folder) set the same for that agent.

A tool that is off never reaches its server: the agent is told so and says what it would have done. Results from a
connector whose source can hold instructions from others, such as mail, reach the agent marked as untrusted, as text
to read and never as instructions to follow.

## See what a connector did

An official connector's page, and a connector you added, list their **Activity** under the accounts: each change a
tool made, newest first, with the chat, the account, whether it was **Done** or what stopped it (**Off**, **Stopped**,
**Failed**), and when. Click a line to open its chat at the turn that made the call. The log stays on this Mac for 90
days, with what each change touched and never the text of a message.

Each line also keeps the call's id, its turn and who started the turn, and for a connector that signs, the key's
`kid` and the cause's `jti`, so a line matches the server's own audit row.

## Turn a connector or skill off

Every row has a switch. Turning off one of yours turns it off in every project; turning off a project's turns it off in
that project, on this Mac only. To turn one off for a single chat, use its switch in the chat's connectors chip.

## See what the agent has in a chat

Once a chat's project has a connector, the connectors chip under the message box counts the connectors that run there
and flags any that need a look (**Needs trust**, **Changed**, **Needs sign-in**, **Can't connect**). Click it for the
connectors and skills offered there; **Manage in Settings** opens the page on that project. Each connector that runs
there has a switch for this chat alone: off, its tools leave the chat from its next request. An agent's chat has the
same switches under **Connectors** in its **+** menu.

A project with no connector shows no chip, unless its [tool hooks](https://lookout.itoowasinarcadia.com/docs/safety#hooks) wait for your approval. To add
one from a chat, choose **Connectors** in the **+** menu: it opens Settings on that project.

## Write a skill

1. Open **Settings › Skills** and click **New skill**.
2. Enter a **Name** (lowercase letters, digits, `-` and `_`) and **When to use it**: the line the agent reads to decide
   when the skill applies.
3. With a project in scope, choose where it **Applies**: **Everywhere**, or only that project.
4. Click **Create and open**. Lookout writes the `SKILL.md` and opens it: write the steps.

A skill is a folder with a `SKILL.md`, and the folder's name is the skill's name:

| Applies | Folder |
|---|---|
| Everywhere | `~/.lookout/skills/<name>/` |
| One project | `.lookout/skills/<name>/` in the project, which you can commit |

```md
---
name: release-notes
description: Write release notes in the team's format
---

# release-notes

1. List the pull requests merged since the last tag.
2. Group them under Added, Changed and Fixed.
```

The `description` is what the agent sees in every chat; it reads the rest only when it uses the skill. Files beside
`SKILL.md` are there for its steps to point at. A chat is offered the skills that are on when it starts.

## Skills from Claude Code and Codex

Lookout also reads skills kept for other agents, in place, and never changes them:

| Folder | When |
|---|---|
| `.agents/skills/` and `.claude/skills/` in the project | always, listed under **From Codex** and **From Claude Code** with the project in scope |
| `~/.agents/skills/` and `~/.claude/skills/` | when **Use Claude Code and Codex rules and skills** is on in **Settings › Skills** |

Each shows the harness it comes from. Skills that Claude Code plugins bring are not read: to use one, copy its folder
into `~/.lookout/skills/`. A skill's switch turns it off for Lookout;
Lookout offers no way to edit it. When one has the same name as a skill in `.lookout/skills/` or `~/.lookout/skills/`,
Lookout's own wins. The same setting reads those harnesses' [global rules files](https://lookout.itoowasinarcadia.com/docs/rules#other-harnesses).

## Use a skill

The agent picks a skill when its description fits the task. To ask for one, type `@` in the message box and pick it under
**Skills**: its `SKILL.md` goes with that message, and the agent follows it.

Lookout's own **visualize** skill is listed under **Built in**, for a [chart or diagram](https://lookout.itoowasinarcadia.com/docs/chats#visuals) in the
chat. The agent is offered it by description like any other skill, and `/visualize` anywhere in a message sends it with
that message. A chat that started before a skill was added is told about it once, at its next message.

## Install a plugin

1. Open **Settings › Plugins** and click **Install plugin**.
2. Pick the plugin's folder.

Lookout copies the folder, and its skills and connectors join the agent in every project. They show on the Skills and
Connectors pages under **From** and the plugin's name. The plugin's switch turns them all on or off, and **Uninstall**
removes them. To update a plugin, install it again from its folder. Plugins have no project scope.

**Browser** is listed there too, built in and on: it gives every chat and subagent the
[Browser tool](https://lookout.itoowasinarcadia.com/docs/tools#browser). Its switch takes the tool out of every chat; it can't be uninstalled, and a plugin
of your own can't take its name.

## Make a plugin

A plugin is a folder with a `plugin.json` that names its skills and connectors:

```text
team-kit/
  plugin.json
  skills/triage/SKILL.md
  connectors/docs.json
```

```json
{
  "name": "team-kit",
  "version": "1.0.0",
  "displayName": "Team kit",
  "description": "The triage playbook and the docs server",
  "skills": ["skills/triage"],
  "mcpServers": ["connectors/docs.json"]
}
```

Each file in `mcpServers` is one connector:

```json
{ "name": "Team docs", "transport": "http", "url": "https://mcp.example.com/v1" }
```

A local command takes `"transport": "stdio"`, a `command` and its `args`.

- `name` is lowercase letters, digits and `-`, up to 40 characters; `version` is `1.2.3`.
- Optional: `author`, `license`, `homepage`, and `enabledByDefault` (`false` installs it off).
- Up to 10 skills and 10 connectors, and 200 files and 1 MB in all.
- A connector file can't carry `env` or `headers`: give it a key on its page once installed.

## Sync across your Macs

Signed in to a Lookout account, your Everywhere connectors, which of your skills are on, your list of plugins and
[your rules for every project](https://lookout.itoowasinarcadia.com/docs/rules#roam) sync to your other machines. They sync when you open one of these
pages, after each change, and every couple of minutes on each machine signed in; the button beside the page's title
says when they last did, and syncs again when clicked. Keys, skill files and plugin folders stay on each Mac: a
plugin installed on another Mac says its copy is missing until you install it here from its folder. When both Macs
changed, Settings asks which to keep: **Keep this Mac’s** or **Use the other device’s**.

## Limits

- The agent uses a connector's tools. Its resources and prompts are not offered.
- A remote URL connects over Streamable HTTP. A server that offers only the older SSE transport can't connect.
- A connector signs in in your browser when its server offers the standard sign-in (MCP authorization), with the keys
  and headers you give it, or as its own client with a key Lookout makes. A browser sign-in is kept on the Mac you
  signed in on.

## Related

- [Rules](https://lookout.itoowasinarcadia.com/docs/rules.md): The instruction files a chat reads from each of its folders, how an edit reaches a running chat, and the ignore files that keep the agent out of paths.
- [Agents](https://lookout.itoowasinarcadia.com/docs/agents.md): Named agents with their own folder, memory and instructions, teams that message each other, routines on a schedule, and chats an agent starts.
- [App access](https://lookout.itoowasinarcadia.com/docs/other-apps.md): Drive Lookout from another app over MCP, or from Claude Code with its plugin.
- [Settings](https://lookout.itoowasinarcadia.com/docs/settings.md): Settings in the Mac app page by page: what each setting does, and its default.