---
title: "MCP server"
description: "Connect Claude Code, Codex, Cursor, OpenCode, VS Code or Claude.ai to Faylee's MCP server so a coding agent can read a recording from its link, fix the bug and report back."
canonical: https://faylee.app/docs/agents/mcp
---

# MCP server

Faylee runs an MCP server at `https://app.faylee.app/mcp`. Connect your coding agent to it once, and you can paste a Faylee link into a chat with no other context. The agent reads the recording the way a teammate would: what the person meant, what they said and pointed at, the screen at any moment, and the page's console and network. It can then fix what it found and comment on the recording with what it changed.

The server speaks Streamable HTTP. It signs in with OAuth the first time an agent connects, so you don't paste a token for the usual clients.

## Connecting your agent

**Settings**, **Agents** in Faylee shows the server address and a ready command or link for each agent.

### Claude Code

```bash
claude mcp add --transport http faylee https://app.faylee.app/mcp
```

Then run `/mcp` in Claude Code, pick `faylee` and sign in. Your browser opens Faylee's consent page.

### Codex

```bash
codex mcp add faylee --url https://app.faylee.app/mcp
codex mcp login faylee
```

The second command opens the browser so you can sign in.

### OpenCode

Add the server to `opencode.json`, in your project or in `~/.config/opencode/`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "faylee": {
      "type": "remote",
      "url": "https://app.faylee.app/mcp"
    }
  }
}
```

Then run `opencode mcp auth faylee`, which opens the browser so you can sign in.

### Cursor and VS Code

**Settings**, **Agents** has an install link for each. The link opens the editor and adds a server named `faylee` with the address above, as an HTTP server. The editor then asks you to sign in.

### Claude.ai and Claude Desktop

In Claude, open **Settings**, **Connectors**, choose **Add custom connector** and paste `https://app.faylee.app/mcp`. Claude sends you to Faylee to sign in.

### Scripts and headless agents

An agent that can't open a browser can send a personal token instead. Create one in Faylee under **Settings**, **Browsers and tokens**, in **Tokens for the CLI and agents**: give it a name such as "Claude Code on the build server" and click **Create token**. The token is shown once, with a ready command:

```bash
claude mcp add --transport http faylee https://app.faylee.app/mcp --header "Authorization: Bearer <token>"
```

Any client can do the same by sending `Authorization: Bearer <token>` with its requests.

:::caution
A personal token can do whatever you can do in Faylee. Keep it out of shared config and repositories, and revoke it in **Browsers and tokens** when you no longer need it.
:::

### Clients that only run local commands

Some clients can only start a local process and talk to it over stdio. For those, the `faylee` CLI has a relay:

```bash
claude mcp add faylee --env FAYLEE_URL=https://app.faylee.app --env FAYLEE_TOKEN=<token> -- faylee mcp
```

`faylee mcp` passes each message to Faylee's server with your personal token and writes back the answer. The tools, the guide and the prompt all live on the server, so the relay never falls behind it. See [The faylee CLI](https://faylee.app/docs/agents/cli.md).

## Signing in

The first time an agent connects, it finds Faylee's sign-in by itself and opens your browser. If you aren't signed in to Faylee, you sign in first. Then the consent page, titled with your agent's name, such as **Connect Claude Code to Faylee**, says which workspace the agent will work in and as whom, and lists what it can do:

- Read recordings in this workspace, with their video, console, network and what was said.
- Comment on recordings as you.
- Create recording links to ask for a repro.

Click **Allow** to connect it, or **Deny**.

There is one permission, the `mcp` scope. An agent reads what you can read in Faylee and nothing more, and its comments appear under your name.

Access tokens last two hours. The agent refreshes them without asking you again.

## Disconnecting

**Settings**, **Agents** lists the agents you connected under **Connected agents**, with when each was connected and last used. **Disconnect** stops an agent right away. To connect it again, you have to allow it again.

Connecting and disconnecting an agent are recorded in the workspace's audit log.

A personal token is separate. Revoke it in **Settings**, **Browsers and tokens**.

## A worked example

Say a teammate recorded a checkout bug and sent you the link with the time it goes wrong. In Claude Code, inside your repository, you paste it:

```text
Checkout is broken, can you fix it? https://app.faylee.app/s/AbC123xYz0?t=1:22
```

When it connects, Faylee tells the agent what a Faylee link looks like and to start with `open_recording`. Here is what the agent does from there:

1. **`open_recording`** with the link exactly as pasted. It gets a briefing and an overview image of the screen. Because the link has `?t=1:22`, the key moments start with `1:22 link points here`.

   ```markdown
   # Checkout fails after applying a coupon
   Link: https://app.faylee.app/s/AbC123xYz0
   A video recording, 1:48 long, made 2026-09-30 by Dana.

   ## What they were trying to do
   ...
   ## Key moments
   - 1:22 link points here: the link was shared at this time
   - 1:22 failed request: #42 POST https://shop.example.com/api/orders -> 500
   ...
   ## Worth searching the code for
   - POST /api/orders
   ...
   ## Next
   Call get_moment at 1:22 to see the screen and everything around it. ...
   ```

2. **`get_guide`** once, for the workflow: understand, look at the moment, find the code, fix it, report back.
3. **`get_moment`** at `1:22`. It sees the screen at that moment and a moment earlier, what the person said, what they clicked, and the console and requests around it.
4. **`get_request`** with id `42`, for the full request and response bodies and a cURL command.
5. It searches your code for `/api/orders` and the error message, finds the cause and makes the fix.
6. **`add_comment`** at `1:22`, in plain words: what was wrong, why, and the pull request. Dana and the team are notified, and the comment sits on the timeline where Dana saw the bug.

If the recording doesn't show enough, the agent can call `create_recording_link` and ask for a new recording with exactly what it needs.

## The investigate_recording prompt

The server also offers a prompt, `investigate_recording`, titled "Investigate a Faylee recording", which runs the whole workflow on a link. Clients that show MCP prompts as commands list it. In Claude Code it appears among the slash commands once Faylee is connected.

It takes two arguments:

| Argument | Required | What it is |
|---|---|---|
| `link` | Yes | The Faylee link |
| `notes` | No | Anything else the agent should know, such as which repository or what to leave alone |

The prompt asks the agent to investigate the recording and fix what it shows, and includes Faylee's workflow guide.

## Tips for agents

- **Pass the link as given.** Every recording tool takes the link as pasted: a share, embed or dashboard link, with or without `?t=`, or a recording id.
- **Times.** Every tool writes times as `1:22` and accepts `1:22`, `82s`, `82000ms` or plain milliseconds. Any time in a briefing, transcript or error can go straight to `get_moment`.
- **`?t=` links.** A link with `?t=` points at a moment. `open_recording` lists it first among the key moments, as "link points here".
- **Start broad, then zoom in.** `open_recording` first, then `get_moment` on the times that matter. Use `get_console`, `get_network` and `get_request` for the details.
- **Report back.** Comment on the recording with `add_comment` at the time of the problem, written for the person who recorded it.
- **Errors are results.** When a tool fails, for example on an unknown request id or a link from another workspace, it returns a message the agent can act on instead of a protocol error. A link the person can't read reads as not found.

## What's hidden stays hidden

Faylee hides passwords, card numbers, tokens, cookies, authorization headers and anything your workspace chose to hide, in the browser, before anything is uploaded. Agents get the capture as it was stored, so hidden values show as `[redacted]` or `••••` in text, and as pixelated or blacked-out areas in frames. Nothing an agent does can bring them back.

Faylee's guide tells agents never to guess or reconstruct a hidden value and never to ask for one, and to reason from what is visible instead: the status code, the error message, whether a header is present at all. See [Privacy](https://faylee.app/docs/workspace/privacy.md).

## Limits

Faylee accepts up to 600 MCP requests a minute per person. Past that, the server answers "Too many requests. Try again in a minute."

## Related

- [MCP tools reference](https://faylee.app/docs/agents/tools.md)
- [The faylee CLI](https://faylee.app/docs/agents/cli.md)
- [The viewer](https://faylee.app/docs/viewer/overview.md)