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. For the why and the use cases, see the MCP overview.

1. Create an API key

Skip this if you only need public links and the Clipy skill. Create an API key when your agent needs authenticated access to your recordings. Go to clipy.online/settings/api-keys and create a key. It looks like clipy_sk_live_… and is shown only once — copy it immediately. The key reads only your own recordings and can be revoked any time.

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 --env CLIPY_API_KEY=clipy_sk_live_xxx -- 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 --env CLIPY_API_KEY=clipy_sk_live_xxx -- npx -y @clipy/mcp

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"],
      "env": { "CLIPY_API_KEY": "clipy_sk_live_xxx" }
    }
  }
}

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

[mcp_servers.clipy]
command = "npx"
args = ["-y", "@clipy/mcp"]
env = { CLIPY_API_KEY = "clipy_sk_live_xxx" }

3. Tools

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

tool	args	does
search_recordings	query, status?, limit?	Search recordings by keyword.
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 recordings.
get_agent_context	id, maxFrames?	One-call bundle: metadata + summary + key moments (with frames) + transcript. Start here when handed a Clipy link.

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

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 (required) — your key.
CLIPY_API_URL (optional) — base URL, defaults to https://clipy.online.

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