Skip to main content

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

​
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. 
{
  "tool": "start_recording",
  "arguments": {}
}
Returns the session ID to use when stopping or downloading.

​
stop_recording

Stops the active headless recording session. 
{
  "tool": "stop_recording",
  "arguments": {}
}

​
download_recording

Returns the recorded MP4 file content (base64-encoded) or a download URL. 
{
  "tool": "download_recording",
  "arguments": {}
}
Output format is MP4 (H.264), encoded using PyAV. The frame rate matches Scope’s inference throughput rather than a fixed FPS target.
Only one headless recording can run at a time. Starting a new recording while one is already active will fail.

​
connect_to_cloud

Connect Scope to a remote cloud inference backend (e.g. Livepeer). 
{
  "tool": "connect_to_cloud",
  "arguments": {
    "app_id": "<your-app-id>",
    "api_key": "<your-api-key>"
  }
}

​
disconnect_from_cloud

Disconnect from the active cloud backend. 
{
  "tool": "disconnect_from_cloud",
  "arguments": {}
}

​
get_cloud_status

Returns the current cloud connection status. 
{
  "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.
Replace <port> with your Scope server’s port. Check your server startup logs for the actual port number.
# 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:
1

Start Scope in server mode

Launch Scope with the MCP server enabled.
2

Connect to the cloud (optional)

If you want remote inference, call connect_to_cloud with your API key and user ID.
3

Start recording

Call start_recording. Scope begins capturing frames immediately.
4

Wait for desired duration

Let the recording run for as long as you need (e.g. 30 seconds).
5

Stop and download

Call stop_recording, then download_recording to retrieve the MP4 file.

​
Troubleshooting

Make sure a pipeline is actively streaming before calling start_recording. The recorder captures inference output, so there must be frames being generated.
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.
Double-check your API key and user ID. Make sure your machine has internet access and can reach the Livepeer backend.

​
See also

Remote Inference

Run Scope pipelines on cloud-hosted GPUs without local hardware

Reporting Issues

Use logs and the built-in bug reporter if something goes wrong