Production

MCP

Pure Frame exposes your video library as an MCP server. Once connected, any MCP-compatible AI client can search footage, list collections, and retrieve video details — all through natural language. Try asking your agent: “Find the moment our CEO mentions pricing.”

Quick Start

Run this once:

$claude mcp add pureframe -- npx -y pureframe-mcp

Or add it manually to ~/.claude.json:

1{
2  "mcpServers": {
3    "pureframe": {
4      "command": "npx",
5      "args": ["-y", "pureframe-mcp"],
6      "env": { "PUREFRAME_API_KEY": "pf_..." }
7    }
8  }
9}

Try it: “Search my videos for a customer mentioning pricing objections.”

What is MCP?

The Model Context Protocol (MCP) is an open standard for connecting AI clients to external tools and data sources. Instead of writing custom integration code for each AI product, you configure one MCP server and every MCP-compatible client — Claude, Cursor, VS Code, Codex, OpenCode, and others — can call it the same way.

How It Works

  1. Your AI client sends a natural-language request to the model (e.g. “find the moment someone mentions churn”)
  2. The model decides to call the search_videos tool and generates its input
  3. The MCP server forwards the call to Pure Frame’s API and returns matching clips — including thumbnail_base64, a base64-encoded JPEG of the matched frame
  4. The model reads the frame directly, in the same turn, without fetching a URL, and can answer follow-up questions about what’s visible

Available Tools

ToolDescription
search_videosFind moments matching a text query. Returns clips with timestamps, presigned URLs, and base64-encoded frame images.
list_collectionsList all collections in the library.
get_collectionGet details about a specific collection: video count, total duration, and storage used.
get_videoGet metadata and a presigned playback URL for a specific video.

Detailed Configuration

All six clients above use the same underlying local server, started via npx -y pureframe-mcp, with one required environment variable:

VariableDescription
PUREFRAME_API_KEYYour Pure Frame API key (see API Keys). Use a read_only key for agent integrations that only need to search.

Config file locations:

ClientConfig fileRoot key
Claude Code~/.claude.jsonmcpServers
Claude Desktop~/Library/Application Support/Claude/claude_desktop_config.jsonmcpServers
Cursor.cursor/mcp.jsonmcpServers
VS Code.vscode/mcp.jsonservers
Codex~/.codex/config.tomlmcp_servers.<name> (TOML table)
OpenCodeopencode.jsonmcp

Advanced Setup

Remote MCP (no install) — for clients that support remote MCP endpoints, including Claude.ai web, skip the local npx process entirely and point at Pure Frame’s hosted Worker:

1{
2  "mcpServers": {
3    "pureframe": {
4      "url": "https://mcp.pureframe.ai",
5      "headers": { "Authorization": "Bearer pf_..." }
6    }
7  }
8}

Scoping to a collection — pass collection_id to search_videos to limit results to one library. Call list_collections first to discover available IDs:

1{
2  "tool": "search_videos",
3  "input": {
4    "query": "customer objection about pricing",
5    "collection_id": "col_abc123",
6    "limit": 5
7  }
8}

Rate limits — agent tool calls share the same limits as the REST API: 30 requests/minute for search_videos. See Rate Limits.

Usage Examples

Search footage

  • “Find the moment someone mentions the annual contract.”
  • “Search for a clip of a whiteboard diagram.”

Browse collections

  • “List all my video collections.”
  • “How much storage is the ‘Sales calls’ collection using?”

Inspect a video

  • “Get the playback URL for video vid_abc123.”
  • “How long is the demo recording from last Tuesday?”

Troubleshooting

Client doesn’t detect the server — restart the client after editing its config file. For Claude Code, confirm with claude mcp list.

“Invalid API key” errors — check that PUREFRAME_API_KEY (or the Authorization header for remote MCP) is set correctly and hasn’t been revoked in API Keys.

No results returned — the query may not match any indexed content, or collection_id may be scoping the search too narrowly. Try list_collections first, or omit collection_id to search the whole library.

npx command not found — the local server requires Node.js. Install it, or use the remote MCP endpoint instead, which requires no local runtime.

Further Resources

  • Agent Vision — the concept behind giving agents visual search
  • API Reference — every endpoint, parameter, and response field
  • SDKs — official Python and TypeScript clients