---
title: Connectors and skills
description: Give the agent more tools with connectors (the official ones are in the Marketplace), playbooks with skills, and both together with plugins.
canonical_url: https://lookout.arcadia.is/docs/connectors-and-skills
type: guide
section: Use Lookout
last_updated: 2026-11-17
related:
  - https://lookout.arcadia.is/docs/rules
  - https://lookout.arcadia.is/docs/agents
  - https://lookout.arcadia.is/docs/other-apps
  - https://lookout.arcadia.is/docs/settings
---

> Every page of these docs: https://lookout.arcadia.is/llms.txt

# Connectors and skills

Give the agent more tools with connectors (the official ones are in the Marketplace), 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.

Arcadia's own products, such as Crew, stand there too while you are signed in to your Arcadia account. **Add** adds
one at once: nothing to type, and nothing signs in. One you added by its address is that same tile. Its page lists
your agents, each with what it may do there: **Use Crew** lets one act there as itself, **Stop** ends it. Your own
chats sign in to it the first time one calls its tools, or when you click **Sign in** on its page.

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 chat's connectors card. Where the provider lets you turn training off, turn it off there, then click
**Training is off at** the provider in that card, 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 lists the tools it gives, each with what its server says it does; **Edit** there turns
tools on or off.

Lookout's own MCP is for [other apps](https://lookout.arcadia.is/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**: in Settings on the
connector, in a chat's connectors card, and on an agent's connector card.

1. Click **Sign in**. Your browser opens the server's own sign-in page, and the connector shows **Finish signing in in
   your browser** with **Cancel**.
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.

A sign-in you cancel, one the server refuses, and one the browser never answers within ten minutes shows **Sign-in
didn't finish** with **Try again**; the server's reason shows on hover.

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** beside **Signed in** at the top of 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.

An Arcadia product, such as Crew, is the exception for an agent: the agent acts there as itself, with its own name and
picture, never under your sign-in. On Crew's page or the agent's connector card, click **Use Crew**, pick **Read** or
**Read and change** and the teams, and allow it with Touch ID, the code from your authenticator app (when your account
has two-step verification), or your Arcadia password. **Stop** on Crew's page, or **Stop using Crew** in the card's
menu, ends it. A paused agent makes no calls there.

When a teammate there mentions the agent, replies to it, reacts to its message or gives it a card, the agent's chat
shows it as messages under one line naming the product and the team: who did it, their words as they wrote them, the
message a reply answers in one quiet line, a card as a chip. **What the agent read** opens the text the agent was
given, and the group's first line opens every such message in one view.

## Give a connector a key

1. Open the connector and click **Add API key** on its **Sign-in** (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 **Add a variable** under
   **Environment**: a **Variable** and its **Value**.
3. Click **Save on this Mac**. It reconnects.

Keys stay on the Mac you enter them on, and their values never show again: a saved one reads **Saved on this Mac**,
with **Replace**. 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.arcadia.is/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 **Sign-in**, 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. Open **Advanced** and 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.arcadia.is/docs/agents#folder) set the same for that agent.

The list is the tools the server last gave Lookout, and its foot says when that was. Lookout reads it again when the
server says its tools changed, when it connects to the server again, when a chat starts a turn ten minutes or more after
the last read, and when the server refuses a call because it doesn't know the tool or its arguments. A chat that uses
the connector is told which tools changed at its next turn, once.

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

## See what the agent has in a chat

Choose **Connectors** in a chat's **+** menu 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.

While one needs a look (**Needs trust**, **Changed**, **Needs sign-in**, **Can't connect**) or waits on your browser
(**signing in**), a connectors chip under the message box says so and opens the same card. A project with no connector
shows no chip, unless its [tool hooks](https://lookout.arcadia.is/docs/safety#hooks) wait for your approval; there **Connectors** in the **+**
menu opens Settings on that project to add one.

## 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.arcadia.is/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.

Or type `/` and the skill's name anywhere in the message, as in "after the fix, use /review": a `/` after a space lists
your skills, and the one you pick shows as its chip, as with `@`. A name typed whole and sent as it is goes with the
message too. A `/` in a link, a path such as `src/review`, or code (between backticks or in a code block) never sends
a skill. At the start of a message `/` lists the [commands](https://lookout.arcadia.is/docs/chats#composer), and skills only when no command
matches what you typed.

Lookout's own **visualize** skill is listed under **Built in**, for a [chart or diagram](https://lookout.arcadia.is/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.arcadia.is/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.arcadia.is/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.arcadia.is/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.arcadia.is/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.arcadia.is/docs/other-apps.md): Drive Lookout from another app over MCP, or from Claude Code with its plugin.
- [Settings](https://lookout.arcadia.is/docs/settings.md): Settings in the Mac app page by page: what each setting does, and its default.
