> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inlace.co/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> Connect your agent to the comments and decisions your team captures, so it executes with full context.

The Lace MCP server connects your agents to everything your team captures. Comments carry the screenshot, the spot on screen, and the discussion behind them. Resolving a comment promotes it to a decision. Recorded [sessions](/concepts/sessions) expose the ordered screens and actions from capture. Agents search your comments and sessions, pull the full context, and execute: they can rerun a workflow the way you ran it, or take on follow-up work with your reasoning in hand.

## Connect in Claude

The fastest way to use Lace is the hosted connector at `https://mcp.inlace.co`. It runs in the cloud and reads your comments and decisions straight from your Lace account, so you don't need the desktop app open.

<Tabs>
  <Tab title="Claude.ai">
    1. Open **Settings → Connectors → Add custom connector**.
    2. Enter the URL `https://mcp.inlace.co` and click **Add**.
    3. Click **Connect** and sign in with your Lace account.

    Then start a chat and say **"Search Lace decisions"**.
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http lace https://mcp.inlace.co
    ```

    The first call opens a browser to sign in with your Lace account. After that, say **"Search Lace decisions"**.
  </Tab>
</Tabs>

<Note>
  The hosted connector needs a Lace account and at least one resolved comment. Sign-in uses OAuth 2.0, so the first connection opens your browser.
</Note>

## Install from the CLI

Use the Lace CLI to register the right MCP transport for each editor. Claude Code uses the hosted OAuth connector so it
can manage authentication in `/mcp`; Claude Desktop, Cursor, and Codex use the local stdio server for editor-side installs.

<Tabs>
  <Tab title="Cursor">
    [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=lace\&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImxhY2UtbWNwQGxhdGVzdCIsIm1jcCIsIi0tZWRpdG9yIiwiY3Vyc29yIl19)

    Or install from the terminal:

    ```bash theme={null}
    npx lace-mcp install cursor
    ```

    **Restart Cursor**, then open a new chat and ask about resolved Lace decisions.
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={null}
    npx lace-mcp install claude
    ```

    Start a new Claude Code session, run `/mcp`, and authenticate Lace. Claude Code uses the hosted OAuth connector so
    its MCP menu can show tools, re-authenticate, clear authentication, reconnect, and disable.
  </Tab>

  <Tab title="Claude Desktop">
    ```bash theme={null}
    npx lace-mcp install claude-desktop
    ```

    Restart Claude Desktop and say **"Search Lace decisions"**.
  </Tab>

  <Tab title="Codex CLI">
    ```bash theme={null}
    npx lace-mcp install codex
    ```

    Start a new Codex session and say **"Search Lace decisions"**.
  </Tab>
</Tabs>

<Warning>
  Claude Desktop, Cursor, and Codex local installs only work while the Lace desktop app is open and you're signed in. The Claude Code
  hosted connector at `mcp.inlace.co` does not need the app open.
</Warning>

## How it works

<Steps>
  <Step title="Write a comment">
    In [Reviews](https://docs.inlace.co/concepts/reviews), write a comment and attach screen context — a pin on the exact spot you're looking at. Resolve it into a decision. The screenshot, spatial context, and discussion persist with it.
  </Step>

  <Step title="Your agent queries Lace" stepNumber={2}>
    It calls `search_comments` to find relevant comments, picks one, then calls `apply_comment` for screenshots, element metadata, and step-by-step context. For what you did on screen earlier, it calls `search_sessions` then `get_session_flow`.
  </Step>

  <Step title="Your agent executes" stepNumber={3}>
    It carries out the work and you review the result.
  </Step>
</Steps>

## Technical reference

### MCP server

The Lace MCP server is registered under the name `lace`. It exposes comment/decision tools, session-flow tools, and publishing.

### Session tools

Session data resolves in tiers — prefer the cheapest tier that answers: `search_sessions` (find) → `get_session_flow` (skeleton) → `include: "elements"` for specific screens → `include: "screenshots"` last.

Sessions you create are available to you automatically. Another user's sessions appear only when that user has turned on sharing for the session.

#### `search_sessions`

Find recorded screen sessions — episodes of what the user did on their machine. Returns up to 20 summaries: session id, time span, apps, screen/step counts. Never returns steps, elements, or images.

**Parameters:**

| Parameter     | Type              | Default | Description                                                      |
| ------------- | ----------------- | ------- | ---------------------------------------------------------------- |
| `query`       | string            | —       | Free text over window titles and on-screen element/target labels |
| `appName`     | string            | —       | App name filter                                                  |
| `url`         | string            | —       | URL path filter                                                  |
| `startedFrom` | string (ISO date) | —       | Lower bound for session start                                    |
| `startedTo`   | string (ISO date) | —       | Upper bound for session start                                    |
| `limit`       | number            | `20`    | Max summaries to return                                          |
| `cursor`      | string            | —       | Opaque pagination cursor from a previous response                |

All parameters are optional.

**Returns:** session summaries. Next step: `get_session_flow` with a returned `sessionId`.

***

#### `get_session_flow`

Replay one recorded session as an ordered flow.

**Parameters:**

| Parameter    | Type                        | Default | Description                                                         |
| ------------ | --------------------------- | ------- | ------------------------------------------------------------------- |
| `sessionId`  | string (UUID)               | —       | Session ID from `search_sessions` (**required**)                    |
| `include`    | `elements` \| `screenshots` | omitted | Optional detail tier (see below); omit for skeleton                 |
| `screenKeys` | string\[]                   | —       | Required for `elements` and `screenshots` — which screens to expand |

**`include` options:**

* Omitted — ordered skeleton: actions, targets, dwell, and screen identity (app, window, url, `screenKey`). No elements, no images. Capped at \~200 steps.
* `elements` — `CapturedElement` trees (role, label, bbox) for the listed `screenKeys` only. Use this to reason about what was on screen.
* `screenshots` — at most one inline image plus download links for the listed `screenKeys`. Use only for visual/layout questions the element tree cannot answer. Never request screenshots to identify or locate elements.

**Returns:** the requested tier, plus a plain-text hint for the next cheaper/richer call.

***

### Discovery tools

#### `search_comments`

Search and filter comments with cursor pagination. With no parameters, returns the top 20 resolved comments ranked by recency. Use the filter parameters to narrow results by review, project, app, element, time range, and more.

**Parameters:**

| Parameter              | Type                                                   | Default            | Description                                                    |
| ---------------------- | ------------------------------------------------------ | ------------------ | -------------------------------------------------------------- |
| `query`                | string                                                 | —                  | Text search across headline, body, and element text            |
| `status`               | `resolved` \| `suggested` \| `all`                     | `resolved`         | Filter by comment status                                       |
| `limit`                | number (1–100)                                         | `20`               | Results per page                                               |
| `cursor`               | string                                                 | —                  | Pagination cursor from a previous response                     |
| `sort`                 | `relevance` \| `resolved_at_desc` \| `created_at_desc` | `resolved_at_desc` | Sort order                                                     |
| `reviewId`             | string (UUID)                                          | —                  | Exact review ID                                                |
| `reviewTitle`          | string                                                 | —                  | Review title substring match                                   |
| `reviewStatus`         | `active` \| `archived`                                 | —                  | Review lifecycle status                                        |
| `pageId`               | string (UUID)                                          | —                  | Exact page ID                                                  |
| `pageName`             | string                                                 | —                  | Page name substring match                                      |
| `projectId`            | string (UUID)                                          | —                  | Exact project ID                                               |
| `projectName`          | string                                                 | —                  | Project name substring match                                   |
| `threadId`             | string (UUID)                                          | —                  | Filter by thread ID                                            |
| `appName`              | string                                                 | —                  | App name substring match                                       |
| `windowTitle`          | string                                                 | —                  | Window title substring match                                   |
| `url`                  | string                                                 | —                  | URL substring match                                            |
| `anchorState`          | `anchored` \| `reanchored` \| `detached`               | —                  | Anchor state filter                                            |
| `elementEid`           | string                                                 | —                  | Exact element accessibility ID                                 |
| `elementRole`          | string                                                 | —                  | Exact element ARIA role                                        |
| `elementInteractivity` | boolean                                                | —                  | Filter to interactive elements only                            |
| `minEndorsements`      | number                                                 | —                  | Minimum endorsement count                                      |
| `hasReplies`           | boolean                                                | —                  | Filter to comments with replies                                |
| `createdBy`            | string (UUID)                                          | —                  | Creator user ID                                                |
| `resolvedFrom`         | string (ISO date)                                      | —                  | Lower bound for resolved date                                  |
| `resolvedTo`           | string (ISO date)                                      | —                  | Upper bound for resolved date                                  |
| `createdFrom`          | string (ISO date)                                      | —                  | Lower bound for created date                                   |
| `createdTo`            | string (ISO date)                                      | —                  | Upper bound for created date                                   |
| `compact`              | boolean                                                | `false`            | Return summary fields only to reduce token usage when scanning |

All parameters are optional.

**Returns:** a paginated list of comment summaries including headline, element info, review/project context, timestamps, and a `nextCursor` for the next page.

***

#### `list_reviews`

List reviews in the current org. Returns title, project, page names, and comment counts per page. Use review titles and IDs to scope `search_comments` queries.

**Parameters:**

| Parameter      | Type                   | Default  | Description                   |
| -------------- | ---------------------- | -------- | ----------------------------- |
| `status`       | `active` \| `archived` | `active` | Review status filter          |
| `content_type` | `review` \| `artifact` | —        | Filter by review content type |
| `projectId`    | string (UUID)          | —        | Filter by project ID          |
| `limit`        | number (1–100)         | `50`     | Results per page              |
| `cursor`       | string                 | —        | Pagination cursor             |

All parameters are optional.

**Returns:** a list of reviews, each with `id`, `title`, `status`, project info, pages (with per-page comment counts), and timestamps.

***

#### `list_projects`

List projects in the current org. Returns name, thread count, and review count.

**Parameters:**

| Parameter | Type           | Default | Description       |
| --------- | -------------- | ------- | ----------------- |
| `limit`   | number (1–100) | `50`    | Results per page  |
| `cursor`  | string         | —       | Pagination cursor |

All parameters are optional.

**Returns:** a list of projects, each with `id`, `name`, `threadCount`, `reviewCount`, and `createdAt`.

***

#### `search_discussion`

Search chat discussion threads linked to a review. Returns messages from the latest thread by default. Use `query` to search within a thread and `threadId` to target a specific linked thread. Returns messages only when the review owner has turned on **Include linked chats** in Share Settings and the linked thread has messages.

**Parameters:**

| Parameter  | Type          | Default | Description                                        |
| ---------- | ------------- | ------- | -------------------------------------------------- |
| `reviewId` | string (UUID) | —       | Review ID to search discussions for (**required**) |
| `query`    | string        | —       | Search query to filter messages                    |
| `threadId` | string (UUID) | —       | Specific thread ID to search within                |

All parameters except `reviewId` are optional.

**Returns:** matching messages from the review's linked discussion thread.

***

### Action tools

#### `apply_comment`

Act on a comment. Returns a multimodal response with page screenshots, element metadata, and step-by-step instructions. Control what's returned with `include`.

**Parameters:**

| Parameter | Type                                              | Default        | Description                                      |
| --------- | ------------------------------------------------- | -------------- | ------------------------------------------------ |
| `id`      | string                                            | —              | Comment ID from `search_comments` (**required**) |
| `include` | `instructions` \| `crop` \| `discussion` \| `all` | `instructions` | What to return (see below)                       |

**`include` options:**

* `instructions` — full page screenshot + element metadata + step-by-step implementation instructions
* `crop` — the full page screenshot plus a cropped element zoom for spatial grounding (falls back to full page only when no element region exists)
* `discussion` — the chat discussion behind the comment; requires **Include linked chats** in the review's Share Settings, otherwise returns empty
* `all` — instructions, crop, and discussion combined

***

### Publishing tools

#### `publish_review`

Your agent presents its work as a live web page anyone can open. Reviewers pin comments directly on the page, and each comment they resolve becomes a decision your agent can query and act on. Use it for a prototype your team needs to see or a walkthrough of what the agent built. Supports Vite+React projects, pre-built static sites, and any web project with an `index.html`.

Returns a `reviewId` (save it — use with `search_comments` to check for reviewer feedback) and `shareUrl` (shareable link for reviewers).

**Parameters:**

| Parameter          | Type           | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------------ | -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`            | string         | —       | Artifact title. Required unless `publishReviewId` is present                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `files`            | array          | `[]`    | Source files as `{path, content}` objects (no `node_modules`). Include `package.json` with a `dev` script; files mode builds in the sandbox. For pre-built static sites use `sourceArchive`. Max 500 files, 25 MB total                                                                                                                                                                                                                                                                              |
| `assets`           | array          | —       | Binary assets as `{path, filename, contentType, sizeBytes}` objects for two-phase upload (see below). Max 50 assets, 50 MB each                                                                                                                                                                                                                                                                                                                                                                      |
| `sourceArchive`    | object         | —       | `{localPath?, sizeBytes?, contentSha256?}` describing a `tar.gz` of the project. Mutually exclusive with `files`, `assets`, and `publishReviewId`. Local `lace-mcp`: set `localPath` and it reads + uploads the file. Hosted MCP: set `sizeBytes` + `contentSha256` to receive a presigned upload URL (see Archive flow). Archives with `package.json` build in the sandbox; pre-built archives with root `index.html` and no `package.json` are served from the CDN. Max 500 MB source, 1 GB static |
| `publishReviewId`  | string (UUID)  | —       | Review ID from a prior asset-upload prepare phase (see below)                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `sourceCommentIds` | array of UUIDs | —       | Comment IDs this prototype addresses. Links the artifact back to its source comments                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `sourceThreadId`   | string (UUID)  | —       | Thread ID for the conversation that motivated this prototype                                                                                                                                                                                                                                                                                                                                                                                                                                         |

Each entry in `files` has:

| Field     | Type   | Description                                                  |
| --------- | ------ | ------------------------------------------------------------ |
| `path`    | string | File path relative to project root (no leading `/`, no `..`) |
| `content` | string | File content as text                                         |

Each entry in `assets` has:

| Field         | Type   | Description                                                                                                                                                                                                                                                                                  |
| ------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `path`        | string | Local asset path                                                                                                                                                                                                                                                                             |
| `filename`    | string | Asset basename used in source rewriting and upload tracking                                                                                                                                                                                                                                  |
| `contentType` | string | MIME type for the asset. Accepted values: `image/png`, `image/jpeg`, `image/gif`, `image/webp`, `image/svg+xml`, `image/x-icon`, `font/woff2`, `font/ttf`, `font/otf`, `application/javascript`, `text/css`, `text/html`, `application/json`, `application/wasm`, `application/octet-stream` |
| `sizeBytes`   | number | Exact asset size in bytes (max 50 MB)                                                                                                                                                                                                                                                        |

**Text-only flow:** pass `title` and `files`, including a `package.json` with a `dev` script. Returns `reviewId` and `shareUrl`.

**Two-phase asset upload:** pass `title`, `files`, and `assets`. The tool returns `publishReviewId`, CDN URLs, and presigned upload URLs. Upload each asset, rewrite source file references to the CDN URLs, then call `publish_review` again with `publishReviewId` and the rewritten `files`. Do not pass `assets` and `publishReviewId` together. If the finalize step returns `missing_assets`, re-upload the missing files using the fresh URLs and retry.

**Archive flow:** pass `title` and `sourceArchive`. Cannot be combined with `files`, `assets`, or `publishReviewId`. With the local `lace-mcp`, set `sourceArchive.localPath` and the server reads and uploads the file for you. On the hosted MCP (which cannot read your disk), set `sourceArchive.sizeBytes` and `sourceArchive.contentSha256` (lowercase hex); the tool returns a `publishReviewId` and a presigned `archive_upload.upload_url`. Upload the archive there with the returned headers, then call `publish_review` again with that `publishReviewId` to finalize.

***

### Config file locations

| Tool           | Config file                                                       |
| -------------- | ----------------------------------------------------------------- |
| Claude Code    | `~/.claude.json`                                                  |
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Cursor         | `~/.cursor/mcp.json`                                              |
| Codex CLI      | `~/.codex/config.toml`                                            |

## Troubleshooting

<AccordionGroup>
  <Accordion title="Hosted connector won't connect">
    Make sure you finished the browser sign-in step. The connector needs a Lace account, and you'll only see results once you've resolved at least one comment.
  </Accordion>

  <Accordion title="Local install can't connect to Lace">
    The Lace desktop app must be open and signed in for the local `npx` install. Open the app and retry. (The hosted connector does not need the app open.)
  </Accordion>

  <Accordion title="I connected the wrong Lace account">
    In Claude Code, clear Lace authentication from `/mcp`, then reconnect; Lace will ask you to choose an account again.
    In clients that do not expose auth reset controls, remove and re-add the Lace MCP connector so the client starts OAuth again.
    For the local CLI, run `npx lace-mcp login --switch`.
  </Accordion>

  <Accordion title="No comments returned">
    You need at least one resolved comment. Open Lace, switch to Review mode, pin a comment, and resolve it. Or start from the agent side: ask it to publish something with `publish_review`, open the share link, comment on the page, and resolve it.
  </Accordion>

  <Accordion title="No sessions returned">
    Start a capture session in the Lace desktop app (header control or **⌘S**), work through a few screens, then stop or wait for idle close. Your own sessions appear automatically; a teammate's sessions appear only if they enabled sharing on that session.
  </Accordion>

  <Accordion title="Agent doesn't recognize the MCP server after install">
    Restart your coding tool fully (quit and reopen), then confirm the Lace server appears in your MCP settings.
  </Accordion>

  <Accordion title="Something isn't working — how do I diagnose?">
    Run `npx lace-mcp health` from your terminal. It checks connectivity to the Lace backend, validates your credentials, and reports any issues.
  </Accordion>

  <Accordion title="Screenshots are missing from comment details">
    For the local install, screenshots are stored alongside the Lace app data. If they were deleted or the app was reinstalled, the comment will still return card and targeting data but without images.
  </Accordion>
</AccordionGroup>

## Privacy and terms

The Lace MCP server reads the comments and decisions your team captures, the recorded sessions you share (or own), and the context behind them. Writes happen only through `publish_review`, which turns your agent's work into a shareable review page. It never edits or deletes existing data. See our [Privacy Policy](https://inlace.co/privacy-policy) and [Terms](https://inlace.co/terms). Questions or support: [hello@inlace.co](mailto:hello@inlace.co).