---
title: MCP tools
description: The tools Lookout's MCP server gives other apps, grouped by what they act on.
canonical_url: https://lookout.itoowasinarcadia.com/docs/mcp
type: reference
section: Reference
last_updated: 2026-10-21
related:
  - https://lookout.itoowasinarcadia.com/docs/other-apps
  - https://lookout.itoowasinarcadia.com/docs/machines
  - https://lookout.itoowasinarcadia.com/docs/connectors-and-skills
---

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

# MCP tools

The tools Lookout's MCP server gives other apps, grouped by what they act on.

Lookout's MCP server lets another app start, follow and steer chats on any of your machines. The app reads each tool's full description and parameters from the server. The lines below are the ones **Settings › App access** shows when you choose an app's tools.

## Connect an app

The server's address, which **Connect an app** in **Settings › App access** shows as **Server URL**:

```text
https://mcp.lookout.itoowasinarcadia.com/mcp
```

1. In the other app, add that address as an MCP server.
2. Sign in with your Lookout account when the browser opens.
3. The app shows under **Apps** in **Settings › App access**, with every tool allowed. **Edit tools** in its menu turns tools off for it, and **Revoke** cuts it off at once.

## Read

| Tool | What it does |
|---|---|
| `lookout_status` | At a glance: the models that run now, plan usage, projects, chat counts |
| `lookout_fleet` | Every chat's state, last reply and errors in one read |
| `lookout_check` | One chat in depth: its state, transcript and to-dos; can wait for it |
| `lookout_changes` | The files a chat changed, with stats and hunks |
| `lookout_models` | The models a chat can run now, with their effort levels |
| `lookout_usage` | What each provider's plan has left, and when it resets |
| `lookout_usage_local` | This machine's token usage |

## Start and steer work

| Tool | What it does |
|---|---|
| `lookout_delegate` | Start work: the project, a chat and its prompt in one call |
| `lookout_steer` | Send a follow-up into a chat |
| `lookout_answer` | Answer a chat's pending question |
| `lookout_retry` | Re-run a cut-off or failed turn, optionally on another model |
| `lookout_stop` | Stop a chat's turn and its subagents |
| `lookout_rewind` | Edit and resend from an earlier turn |
| `lookout_restore` | Reset a chat's files to a checkpoint |
| `lookout_compact` | Compact a chat's context now |

## Manage chats

| Tool | What it does |
|---|---|
| `lookout_configure` | Retune a chat: model, effort, mode, title |
| `lookout_handoff` | Hand chats you started to a Lookout agent |
| `lookout_mark_read` | Mark chats read: their finished dot clears |
| `lookout_archive` | Archive chats out of the sidebar, or restore them |
| `lookout_delete_thread` | Delete a chat and its transcript |

## Agents

| Tool | What it does |
|---|---|
| `lookout_configure_agent` | Set up an agent: name, description, instructions, projects, fallback models |

## Background runs

| Tool | What it does |
|---|---|
| `lookout_tasks` | List a chat's subagents |
| `lookout_task_transcript` | Read a subagent's transcript tail |
| `lookout_cancel_task` | Cancel a chat's subagents |

## Projects and worktrees

| Tool | What it does |
|---|---|
| `lookout_projects` | Every project, or one by id |
| `lookout_create_project` | Make a project: clone a repo, a folder, or scratch |
| `lookout_configure_project` | Retune a project's defaults |
| `lookout_delete_project` | Delete a project and its chats |
| `lookout_worktrees` | List the git worktrees Lookout made for a project's chats |
| `lookout_merge_worktree` | Merge a chat's worktree branch into the project |
| `lookout_push_worktree` | Push a chat's worktree branch to the project's remote |

## Machines

| Tool | What it does |
|---|---|
| `lookout_machines` | See your machines and their load; reach them from any tool |
| `lookout_use_machine` | Pick the machine the session tools run on |
| `lookout_doctor` | A machine's preflight: providers, git, disk, and whether it takes new chats |
| `lookout_configure_machine` | Set a machine's limits on running chats, or drain it |
| `lookout_install_line` | The line that adds a server to your account |
| `lookout_open_add_link` | Show a server's request to join in Lookout on this Mac |

## When a call fails

A refused call returns an error with a `code`, a `message`, and `next`: what to do instead, often the call to make. `lookout_unreachable` means Lookout isn't running on that machine, or is still starting: call again in a moment. `grant_needed` means you haven't let that app add a folder as a project: [Let an app add projects](https://lookout.itoowasinarcadia.com/docs/other-apps#add-projects).

## Chat titles

A chat's title is its row in the sidebar. `lookout_delegate` and `lookout_configure` take `title` as 2 to 6 words, at most 40 characters; the goal goes in the prompt. A start title longer than 40 characters is not used: the chat shows the prompt's opening words, whole, until Lookout titles it from its first exchange as it does any chat, and the answer's `titleNote` says the title was too long and what to pass. A rename through `lookout_configure` over 40 characters is refused with `title_too_long`, and nothing in the call changes. Leave `title` out and Lookout titles the chat itself. If the first try fails, the next turn that carries a message titles the chat from the first message (three tries at most); a turn with no message (a resume after a plan reset, a wake) never titles it.

## Typed answers

Pass `schema` (a JSON Schema object) to `lookout_delegate` and the chat ends its turn by submitting an object that matches it. Once the turn is over the chat's lane carries that object as `result`, checked against the schema, so a review can return a verdict you read as data. A turn that ended without one reads `resultError: "schema"`. `lookout_steer` takes `schema` too, to change it for the next turn.

## Background commands

A chat can read `done` while a background command it started itself (a build, a test run, a dev server) is still running. Its lane then carries `shells`: each such command's `id`, `command` and `runningFor`. A command running does not make the chat busy (one left running on purpose may never end), but its end wakes the chat with a turn of its own, and `next` says so. If a Lookout restart stops such a command while the chat sits idle, the chat wakes once at the next start and is told the restart stopped it, with the output it produced in its terminal file, so it can run the command again or go on without it.

## When a plan runs out

`lookout_usage` carries each provider's `forecast` at the pace of the last two hours of readings: `emptyAt`, when the last account routing can send requests to runs out; `reopensAt`, when a reset opens one again; `ratePerHour`, the burn of the `window` that runs out, in percent points of one account's window per hour; and `span`, the readings it was measured over. Each account's windows carry their own `ratePerHour` and `emptyAt`. `forecast` is null until there are twenty minutes of readings. `lookout usage --json` prints the same answer. Read it before launching a batch of chats on one provider.

`lookout_usage_local` with `by` (`agent`, `account`, `project`, `model` or `provider`) answers the last `days` local days' totals per group, largest first, counted from the same daily totals as History in **Settings › Usage**: every turn of the period, the four token counts, turns, compaction passes, Task runs and, by agent or account, `weekPercent`, about how much of each plan's week went there.

By default a chat whose model's plan is spent, or that is rate limited, stops with the state `quota` until the app retries it. Pass `onQuota: "wait"` to `lookout_delegate` and the chat waits for the reset and goes on by itself, or `onQuota: "fallback"` with `fallbacks` (up to 4 models) and it goes on at once on the first of them whose plan is open. No model outside that list is used. A chat that already stopped takes `lookout_retry` with `wait: true`. While it waits its state is `parked`, a restart doesn't lose the wait, and `lookout_stop` ends it. A `lookout_steer` into a waiting chat joins the wait (`delivered: next_turn`): the chat stays parked for the same reset and reads the message when it goes on, instead of running a turn that would only meet the spent plan. To move a waiting chat instead of waiting, `lookout_retry` with `model` (or `effort`) ends the wait and re-runs the same request on the new model in one call, at `effort` or else the chat's effort carried to the same place on the new model's levels; it also takes a chat that was stopped after its turn hit the limit, with or without a model. Without a model, `lookout_retry` on a parked chat is Try now: Lookout reads the plans again and re-runs the request at once on the first model of its list that is open on any account, its own model first; when none is open it answers `delivered: waiting` and the chat keeps waiting. A subagent waiting for its plan moves the same way: `lookout_retry` with `task` (its id from `lookout_tasks`) and `model` continues it now on that model, from where it stopped. The plan is read before the turn starts, and the delegate's answer names the model the turn runs on as `model`. When `lookout_delegate`, or `lookout_retry` or `lookout_configure` with a `model`, names a model whose plan is already spent, the answer says so at once as `planSpent`, with its window and `resetsAt`. Without `onQuota` the call is refused with `plan_spent` and `openModels`, the models whose plans are open. With `fallback` the turn starts right away on the first open one. With `wait`, or when no model on the list is open (`allClosed`), the chat parks at once without sending anything (`parks`). `lookout_models` shows each model's `planState`.

## Related

- [App access](https://lookout.itoowasinarcadia.com/docs/other-apps.md): Drive Lookout from another app over MCP, or from Claude Code with its plugin.
- [Machines](https://lookout.itoowasinarcadia.com/docs/machines.md): Run chats on your other Macs and on your servers, from the app or the terminal.
- [Connectors and skills](https://lookout.itoowasinarcadia.com/docs/connectors-and-skills.md): Give the agent more tools with connectors, playbooks with skills, and both together with plugins.