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

# MCP Server Recording

> Record Scope output headlessly and control recording via MCP tools

# Recording Scope output with the MCP server

Scope exposes recording controls through its **MCP (Model Context Protocol) server**, so you can start, stop, and download recordings without touching the browser. This is useful for batch workflows, CI pipelines, or automating Scope from an AI assistant like Claude.

***

## Prerequisites

* Scope running in server mode (or with the MCP server enabled)
* An MCP client configured to connect to Scope's MCP endpoint

<Note>
  See the `.mcp.json` file in the Scope repository root for the default endpoint configuration. Make sure your MCP client points to the same address.
</Note>

***

## Available MCP tools

### `start_recording`

Starts capturing Scope's output to an MP4 file. Recording happens headlessly via the `HeadlessRecorder`, so no active WebRTC session is required.

```json theme={null}
{
  "tool": "start_recording",
  "arguments": {}
}
```

Returns the session ID to use when stopping or downloading.

### `stop_recording`

Stops the active headless recording session.

```json theme={null}
{
  "tool": "stop_recording",
  "arguments": {}
}
```

### `download_recording`

Returns the recorded MP4 file content (base64-encoded) or a download URL.

```json theme={null}
{
  "tool": "download_recording",
  "arguments": {}
}
```

<Note>
  Output format is MP4 (H.264), encoded using PyAV. The frame rate matches Scope's inference throughput rather than a fixed FPS target.
</Note>

<Warning>
  Only one headless recording can run at a time. Starting a new recording while one is already active will fail.
</Warning>

### `connect_to_cloud`

Connect Scope to a remote cloud inference backend (e.g. Livepeer).

```json theme={null}
{
  "tool": "connect_to_cloud",
  "arguments": {
    "app_id": "<your-app-id>",
    "api_key": "<your-api-key>"
  }
}
```

### `disconnect_from_cloud`

Disconnect from the active cloud backend.

```json theme={null}
{
  "tool": "disconnect_from_cloud",
  "arguments": {}
}
```

### `get_cloud_status`

Returns the current cloud connection status.

```json theme={null}
{
  "tool": "get_cloud_status",
  "arguments": {}
}
```

***

## REST API equivalent

The same recording endpoints are available over HTTP if you prefer to use `curl` or a script.

<Note>
  Replace `<port>` with your Scope server's port. Check your server startup logs for the actual port number.
</Note>

```bash theme={null}
# Start recording
curl -X POST http://localhost:<port>/api/v1/recordings/headless/start

# Stop recording
curl -X POST http://localhost:<port>/api/v1/recordings/headless/stop

# Check status
curl http://localhost:<port>/api/v1/recordings/headless/status

# Download
curl http://localhost:<port>/api/v1/recordings/headless/download -o output.mp4
```

***

## Example: Automate a timed recording

Using the Scope MCP server from Claude Desktop or another MCP client:

<Steps>
  <Step title="Start Scope in server mode">
    Launch Scope with the MCP server enabled.
  </Step>

  <Step title="Connect to the cloud (optional)">
    If you want remote inference, call `connect_to_cloud` with your API key and user ID.
  </Step>

  <Step title="Start recording">
    Call `start_recording`. Scope begins capturing frames immediately.
  </Step>

  <Step title="Wait for desired duration">
    Let the recording run for as long as you need (e.g. 30 seconds).
  </Step>

  <Step title="Stop and download">
    Call `stop_recording`, then `download_recording` to retrieve the MP4 file.
  </Step>
</Steps>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Recording returns an empty file">
    Make sure a pipeline is actively streaming before calling `start_recording`. The recorder captures inference output, so there must be frames being generated.
  </Accordion>

  <Accordion title="MCP tools are not available">
    Verify that the MCP server is enabled in your Scope configuration. Check the `.mcp.json` file in the repository root for the correct endpoint configuration.
  </Accordion>

  <Accordion title="Cannot connect to cloud">
    Double-check your API key and user ID. Make sure your machine has internet access and can reach the Livepeer backend.
  </Accordion>
</AccordionGroup>

***

## See also

<CardGroup cols={2}>
  <Card title="Remote Inference" icon="cloud" href="/scope/guides/remote-inference">
    Run Scope pipelines on cloud-hosted GPUs without local hardware
  </Card>

  <Card title="Reporting Issues" icon="bug" href="/scope/guides/reporting-issues">
    Use logs and the built-in bug reporter if something goes wrong
  </Card>
</CardGroup>