Online MCP

@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](https://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](https://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 .
• 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 support@clipy.online.

Tools

| replace_transcript | Replace a recording's transcript with text you author (needs the ingest scope). Call get_transcript first and pass its revision; stale replacements are rejected instead of overwriting a concurrent edit. The summary regenerates automatically. Marked as agent-edited, never passed off as spee