Clipy

@clipy/mcp

Give your AI agent access to your Clipy screen recordings.

Developed in the Clipy monorepo. A public mirror for browsing the source and filing issues lives at github.com/clipy-recorder/clipy-mcp (MIT), kept in sync with each npm release.

This is a Model Context Protocol (MCP) server. It lets Claude, Cursor, Windsurf, and other MCP-capable agents search your recordings and your team library, and read their transcripts and AI summaries, so you can do things like "turn this bug-report recording into a Linear ticket" without leaving your agent — and, with the record tool, record a web app headlessly and get it back as a Clipy recording ("build the feature, then record the outcome").

The canonical cross-surface operating contract is clipy.online/agents.md. For the exact connected MCP version and schemas, use the standard tools/list request.

The read tools need the recordings:read scope, which every key gets by default. The write tools — record, the session tools (start_recording, add_marker, add_chapter, stop_recording, abort_recording), and replace_transcript — additionally need the key to carry the ingest scope ("Record & upload"), which the server enforces. get_edit_transcript and edit_recording need the recordings:write scope. A recordings:read-only key can read every recording you can open but cannot create, modify, or delete anything.

Setup

Log in once with the Clipy CLI:

npx @clipy/cli@latest login

It opens your browser; click Approve once. The key is saved to ~/.config/clipy/config.json, and this server reads that file — so there is no key to copy anywhere, and no secret ends up in your shell history or your MCP config.

Then add the server to your MCP client.

Claude Code

The --scope user flag installs Clipy globally for every project. Without it, claude mcp add defaults to local scope (the current folder only):

claude mcp add --scope user clipy -- npx -y @clipy/mcp

Codex

This writes the server to your global ~/.codex/config.toml, so it's available in every Codex session:

codex mcp add clipy -- npx -y @clipy/mcp

Or add it to ~/.codex/config.toml by hand:

[mcp_servers.clipy]command = "npx"args = ["-y", "@clipy/mcp"]

Claude Desktop / Cursor / Windsurf

Edit the matching user-level config (claude_desktop_config.json, ~/.cursor/mcp.json, or the Windsurf MCP config) directly:

{  "mcpServers": {    "clipy": {      "command": "npx",      "args": ["-y", "@clipy/mcp"]    }  }}

Add an "env": { "CLIPY_API_KEY": "clipy_sk_live_xxx" } block only if you are not using clipy login on this machine.

Setting the key explicitly

Use CLIPY_API_KEY when there is no clipy login to read from — CI, a container — or when you deliberately want a different key than the logged-in one. An explicit env var always wins over the config file. Mint keys at https://clipy.online/settings/api-keys (shown only once).

Never inline your key into the server's launch command — e.g. "command": "sh", "args": ["-c", "CLIPY_API_KEY=… npx -y @clipy/mcp"]. Command-line arguments are visible to every local process via the process table (ps, /proc), so a key placed there is effectively world-readable on the machine. Put it in the env block instead. (claude mcp add --env … / codex mcp add --env … write that env block for you — they expose the key only in the argv of that single setup command, never in the long-running server's.)

Hosted connector

You can also connect without installing anything. Clipy runs this server at https://clipy.online/api/mcp (Streamable HTTP).

• Connector UIs such as Claude and ChatGPT sign in with OAuth. Discovery starts at https://clipy.online/.well-known/oauth-protected-resource.
• Other clients send Authorization: Bearer <Clipy API key>.
• A key with only the recordings:read scope sees only the read tools.

For MCP directories and reviewers

Clipy keeps a demo account with three sample recordings: a bug walkthrough, UI feedback and a product demo. Directories can get a read-only test key by emailing [email protected].

Tools

Read tools accept a recording's public id (the slug in its share URL) or the full https://clipy.online/video/<id> URL.

Who records what. These MCP tools record the browser (a headless Chromium page Clipy owns). The Clipy CLI records Mac windows, displays and the iOS Simulator (--source mac-screen) and Linux screens (--source screen, including a private virtual display), and the Clipy Mac and Windows apps record everything else, including the real logged-in browser.

Using record

record opens a URL in a headless Chromium (works in CI / cloud sandboxes, no display), records for a few seconds, and streams it into Clipy — then returns the id so you can call wait_for_artifacts and get_agent_context to read it back. It needs:

1. Playwright in the environment running this MCP server:
   bash

   npm install -g playwright && npx playwright install chromium

2. An API key with the "Record & upload" (ingest) permission — choose it when you mint the key at clipy.online/settings/api-keys.

Parameters: url (required, http/https), durationSeconds (default 15, max 300, applied per viewport pass), name, description, type (recording kind — bug_report, feature_request, product_demo, walkthrough_tutorial, feedback_review, discussion_talk, other, plus aliases), viewports (e.g. mobile,desktop or 390x844,1440x900 — recorded sequentially into one video, frame sized to the largest, each pass slow-scrolled and auto-chaptered), storageState / initScript (paths, never logged), notes, and width/height (default 1280×720, ignored when viewports is set).

Recording behind a login. storageState seeds exactly what its JSON contains (cookies + localStorage) but can't reproduce a whole browser identity (IndexedDB, service workers, some cross-origin auth). For a full identity, pass userDataDir — Chrome's user-data root (macOS: ~/Library/Application Support/Google/Chrome) — in one of two modes:

• Copy a named profile (recommended). Add profileDirectory ("Profile 1", "Default", … — the exact folder from chrome://version → Profile Path). Clipy copies that profile into a temporary root and records the copy, so your real profile is never opened or modified and the copy is deleted after upload. The tool result discloses the copy (profile name, bytes, and a warning if Chrome was running while it was copied).

  ⚠️ macOS: cookie logins may not survive the copy. Chrome encrypts cookies with the Chrome Safe Storage Keychain key; the recorder's bundled Chromium looks for Chromium Safe Storage. So on macOS a copied profile can produce a browser that looks like your identity but is silently logged out wherever the session is cookie-based — localStorage/ Preferences-based sessions still work. This is a pre-existing Playwright-vs-Chrome constraint, not something the copy introduces, and the copy disclosure repeats it. If the recording lands logged out, that's why. Record the real browser with the CLI's clipy record --source screen, or drive your own browser and attach evidence via add_marker's observed/verdict.

• Open the Default profile directly. Omit profileDirectory. Clipy opens the root's Default profile and writes to it, so it's refused while a live Chrome holds it locked — quit Chrome first. When the dir looks like a real Chrome root, the result carries a userDataDirWarning saying so and pointing you at profileDirectory (ephemeral copy) or the CLI's --source screen instead. Prefer those unless you specifically want in-place use.

Playwright strips Chromium's --profile-directory (it always loads Default from whatever dir it's given), so copying is the only way to record a named profile. Pointing userDataDir at a profile subdir (.../Chrome/Default) is refused — launching from there would silently record a blank, logged-out profile.

storageState and userDataDir are mutually exclusive; profileDirectory requires userDataDir.

Check the camera before you work

record and start_recording both return a source object describing what is actually being recorded, resolved fresh at start time — the post-redirect url, the page title, and the recording viewport:

"source": {  "kind": "headless_browser",  "title": "Orders — Admin",  "url": "https://app.example.com/orders",  "viewport": { "width": 1280, "height": 720 }}

Compare it against the surface your driver is acting on before doing minutes of work. This exists because driver-attested evidence proves what the driver observed and nothing ties it to what the camera saw — it's entirely possible to produce truthful marks over footage of the wrong thing. Clipy will never focus or foreground a window or tab for you; pointing the driver and the camera at the same surface is the caller's job.

kind is always headless_browser here: these tools record a headless page Clipy owns. Real application windows and displays are recorded by the Clipy CLI (clipy record --source mac-screen --window "<app>" on a Mac, --source screen on Linux), so no window id or window title is reported here. An empty or invented one would be exactly the kind of false confidence this field exists to prevent.

Evidence on a marker: two provenances

add_marker can carry evidence in exactly one of two provenances — they are tallied and rendered separately, never pooled:

Use driver-attested when your agent drives its own browser/tooling while Clipy records (e.g. --source screen on the CLI) or when there's no Clipy-owned page to assert against. It's weaker than clipy-verified but far stronger than plain prose. The transcript's leading [verification] note segments the two, e.g. [verification] 3 clipy-verified: 2 passed, 1 failed · 2 driver-attested: 2 passed, 0 failed.

Driving the recorded page over CDP (start_recording + exposeCdp: true)

Pass exposeCdp: true to start_recording and the recording browser opens a Chrome DevTools Protocol endpoint; the result returns cdpHttpUrl + cdpUrl. Connect your own Playwright and drive the page while Clipy records it:

const { chromium } = require("playwright");const browser = await chromium.connectOverCDP(cdpHttpUrl);const page = browser.contexts()[0].pages()[0]; // the page being recordedawait page.goto("http://localhost:3000/settings");await browser.close();                          // detaches; the recording keeps going

It's off by default — while it's open, any local process can attach to that browser. CLIPY_DISABLE_CDP=1 is a hard kill switch that forces it off. Gotchas: the recorded page is contexts()[0].pages()[0] (a new context you open won't be captured); page.viewportSize() reads null over a CDP attach; and to change the viewport use newCDPSession + Emulation.setDeviceMetricsOverride, not setViewportSize.

In-page bridge (zero extra tool calls). When exposeCdp is on, the recorded page also exposes window.__clipyMark(text, opts?) and window.__clipyChapter(label), so your CDP driver can drop asserted marks/chapters from inside the page:

await page.evaluate(() =>  window.__clipyMark("saved the form", { assertSelector: ".toast", assertText: "Saved" }),);await page.evaluate(() => window.__clipyChapter("AFTER — fix applied"));

opts mirrors add_marker (assertSelector / assertText / assertUrl / failMode); assertText requires assertSelector (the call rejects otherwise), and a failed assert with failMode: "abort" discards the session — same annotations and tally as the tools.

Config

Privacy

Your key reads the recordings you can open in Clipy: your own, your team library and Spaces, and recordings shared with you, with the same permissions as the app. Revoke it any time at /settings/api-keys. The server runs locally on your machine; your key is never sent anywhere except to the Clipy API over HTTPS.