Docs / MCP

Clipy MCP: Setup & Reference

The default way to hand a recording to an agent is the Clipy skill: install it once, then paste a normal public Clipy video link. MCP is the advanced authenticated track for private recordings, library search, and tool-call access to summaries, transcripts, and key moments and, with an ingest-scoped key, recording tools that let an agent capture a web app or run a live session and get it back as a Clipy recording. For the why and the use cases, see the MCP overview.

Cross-surface routing and proof guidance live at /agents.md. For the exact connected MCP version, use its standard tools/list response.

1. Get an API key (browser login)

Skip this if you only need public links and the Clipy skill. Otherwise run npx @clipy/cli@latest login and click Approve once. The key is stored at ~/.config/clipy/config.json and the MCP server reads it from there, so there is nothing to copy, and no secret lands in your shell history or MCP config. Login keys carry both read and Record & upload (ingest) access, so the write tools work out of the box.

Prefer minting a key by hand? Go to clipy.online/settings/api-keys. It looks like clipy_sk_live_…, is shown only once, reads only your own recordings, and can be revoked any time. Hand-minted keys default to read-only; pick the Record & upload (ingest) permission if the agent should record. Put a hand-minted key in CLIPY_API_KEY (an env block on the server, or --env on the mcp add command); it overrides the logged-in one. Do that for CI and containers, where there is no clipy login to read.

2. Install the server

Claude Code. The --scope user flag installs Clipy globally for every project. Drop it and claude mcp add falls back to its default local scope, the current folder only, which is why the server "disappears" in your other repos.

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

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@latest

Prefer to edit config by hand? Paste the block into the matching user-level file: claude_desktop_config.json, ~/.cursor/mcp.json, or the Windsurf MCP config:

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

…or, for Codex, into ~/.codex/config.toml:

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

3. Tools

The read tools work with any key; the recordings:read scope is granted by default. They accept a recording's public id (the slug in its share URL) or a full https://clipy.online/video/<id> URL.

tool	args	does
search_memory	query, kinds?, limit?	Preferred search: hybrid semantic + keyword across recordings and imported/watched context, returning exact moments and semantic status.
search_recordings	query, status?, limit?	Legacy recording-only keyword search.
list_recordings	status?, limit?	List recent recordings.
get_recording	id	Metadata + processing status.
get_transcript	id	Full transcript (segments + plaintext).
get_summary	id	AI summary (TL;DR / key points / action items).
wait_for_artifacts	id, require?, timeoutSeconds?	Poll until transcript/summary are ready.
download_recording	id, outputPath?	Download the MP4 locally to clip / extract frames yourself.
get_key_moments	id, includeFrames?, maxFrames?	Timestamped visual moments: what the speaker pointed at, with the frame at that instant (inline image) and click coordinates on Mac app and Chrome-extension tab recordings.
get_agent_context	id, maxFrames?	One-call bundle: metadata + summary + key moments (with frames) + transcript. Start here when handed a Clipy link.
list_context_documents	limit?, offset?	List imported/watched context.
get_context_document	id	Read context metadata and classification without the full transcript.
read_context_document	id, startMs?, endMs?	Read only the needed timestamp range from an imported context document.

claude

Clipy memory47 recordings·23 imported videosnothing expires

>which recording covered the pricing discussion?

clipy · search_memory

recordingPricing sync34:02

…we cap the free tier at five, then it is nine a month…

recorded 4 months ago · /video/b596rrc8yhi6?t=2042

contextHow SaaS teams set a price08:19

…anchor on the annual number before you show the monthly…

imported from YouTube 7 months ago · /video/k41xq7dm2p0e?t=499

You settled it in the pricing sync at 34:02: five free, then nine a month.

Ask your agent what you said six months agoEvery recording you make and every video you import is kept in your Clipy knowledge base for good. Claude Code searches all of it with one search_memory call and answers with the moment, not a list of files: the recording, the timestamp, the sentence.

The write tools let an agent record its own screen recordings and fix up transcripts. They additionally need the ingest scope ("Record & upload"), which the server enforces: record also needs Playwright installed where the server runs. A read-only key can read your recordings but cannot create or modify anything.

tool	args	does
record	url, durationSeconds?, name?, width?, height?	Record a web app headlessly and upload it as a Clipy recording; returns its share + agent-context URLs. Needs Playwright in this server's environment.
start_recording	url, maxSeconds?	Start a live session that keeps recording while the agent works. Auto-stops and uploads at maxSeconds (default 600) so it can never run away.
add_marker	text, atSeconds?, assert*/observed+verdict?	Drop a live-timestamped narration marker into the active session; markers become the transcript. Optional assertions are verified against the live page (or driver-attested). Navigations + console errors are added automatically.
add_chapter	label	Drop a chapter boundary (=== CHAPTER: label ===) into the active session at the live clock.
stop_recording	—	Finish the session: close the browser, upload, and return the share + agent-context URLs.
abort_recording	—	Discard the active session; nothing is uploaded.
replace_transcript	id, expectedRevision, segments? / plaintext?	Call get_transcript first and pass its revision. Stale replacements are rejected instead of overwriting another edit; the summary regenerates from accepted text.

4. REST API (under the hood)

The server wraps a small read-only REST surface. You can call it directly with any Bearer-capable client:

curl -s https://clipy.online/api/v1/recordings \
  -H "Authorization: Bearer clipy_sk_live_xxx"

method	path	returns
GET	/api/v1/search?q=&kinds=&limit=	Hybrid semantic + keyword search across recordings and imported context.
GET	/api/v1/recordings?q=&status=&limit=&page=	List / search your recordings.
GET	/api/v1/recordings/{id}	One recording's metadata + statuses.
GET	/api/v1/recordings/{id}/transcript	Timestamped segments + plaintext.
GET	/api/v1/recordings/{id}/summary	TL;DR, key points, action items.
GET	/api/v1/recordings/{id}/key-moments	Timestamped visual moments + click coordinates.
GET	/api/v1/context-documents	List imported/watched context documents.
GET	/api/v1/context-documents/{id}/recording.arec	Read compiled imported AREC markdown.

All endpoints are owner-scoped: a key only ever returns the recordings that belong to its owner. Transcript/summary endpoints return status (e.g. queued, ready) so you can poll while a fresh recording finishes processing.

Config

CLIPY_API_KEY (optional): your key. Defaults to the apiKey saved by clipy login; set it to override that.
CLIPY_API_URL (optional): base URL, defaults to https://clipy.online.
CLIPY_DISABLE_CDP (optional): set to 1 to hard-disable the Chrome DevTools Protocol endpoint on live sessions (overrides a tool's exposeCdp).

Default path: install the Clipy skill and paste a normal video link · the integration reference at /docs/agents · the agent story at /for-agents · prefer a terminal? the Clipy CLI wraps the same API · package on npm: @clipy/mcp

Getting started

Agent tools