# Stockfilm MCP Server

**Search and license 217,000+ authentic vintage home movie clips from the 1930s-1980s.**

Stockfilm is the largest curated archive of restored vintage home-movie footage available for licensing. This MCP server lets AI agents discover, preview, and license archival clips directly through the [Model Context Protocol](https://modelcontextprotocol.io).

Every clip is real 8mm, Super 8, or 16mm film shot by ordinary families across the United States and around the world. Professionally scanned, digitally restored (dust/scratch removal, stabilization, color correction), and cataloged with metadata including shot year, location, and descriptive tags. **No AI-generated content. Every frame is real archival film.**

---

## Quick Start

### Claude Code (one command)

```bash
claude mcp add --transport http stockfilm https://api.stockfilm.com/mcp
```

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "stockfilm": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.stockfilm.com/mcp"]
    }
  }
}
```

### Cursor / Windsurf / Other MCP Clients

```
Server URL: https://api.stockfilm.com/mcp
Transport:  Streamable HTTP
Auth:       None required
```

---

## What's in the Archive

| Category | Examples | Decades |
|----------|---------|---------|
| **Family Life** | Backyard barbecues, birthday parties, holidays, baby's first steps | 1930s-1980s |
| **Travel & Vacation** | Road trips, national parks, beach holidays, camping | 1940s-1970s |
| **Holidays** | Christmas morning, Easter, Thanksgiving, 4th of July | 1930s-1980s |
| **Suburban America** | Neighborhoods, new homes, lawn care, swimming pools | 1950s-1970s |
| **Cars & Driving** | Classic cars, highway driving, gas stations, car culture | 1940s-1970s |
| **Schools & Graduations** | Classrooms, school plays, proms, college campuses | 1950s-1970s |
| **Sports & Activities** | Little League, fishing, skiing, bowling, roller skating | 1950s-1970s |
| **International** | European vacations, world fairs, military bases abroad | 1940s-1960s |
| **Cities & Streets** | Downtown streets, storefronts, neon signs, public transit | 1930s-1970s |
| **Nature & Outdoors** | Mountains, lakes, forests, wildlife, farming | 1940s-1970s |

**217,000+ clips** across all categories. Most footage is from the United States, with significant international coverage from Europe, Asia, and Latin America.

### Why This Footage Matters

- **Irreplaceable** - These are one-of-a-kind family films that cannot be recreated
- **Authentic** - Real film grain, period color, original aspect ratios preserved
- **Restored** - Professional 4K scanning with digital restoration
- **Cataloged** - Metadata includes shot year, location, and descriptive tags
- **Licensed** - Royalty-free, worldwide, perpetual license per clip

---

## Available Tools

The MCP server exposes 6 tools:

### `search_vintage_footage` (Free)

Search the archive by text query with optional year range and location filters.

```
"Find 1960s California family barbecue footage"
"Christmas morning clips from the 1950s"
"Beach vacation footage, 1940s to 1960s"
```

**Parameters:**
- `query` (required) - Natural language search. Be descriptive for best results.
- `limit` (optional) - Number of results, 1-50. Default: 10.
- `year_from` (optional) - Earliest year filter (e.g., 1950).
- `year_to` (optional) - Latest year filter (e.g., 1969).
- `location` (optional) - Location filter (city, state, or country).

### `get_clip_details` (Free)

Get full metadata for a specific clip: title, description, duration, tags, thumbnail URL, pricing, and license URL.

**Parameters:**
- `clip_id` (required) - The clip ID from search results.

### `find_similar_footage` (Free)

Find visually similar clips by providing a clip ID. Uses visual similarity matching to find footage with similar content, color palette, or scene composition.

**Parameters:**
- `clip_id` (required) - Clip ID to find similar footage for.
- `limit` (optional) - Number of results, 1-25. Default: 10.

### `build_rough_cut` (Free)

Auto-assemble a timed sequence of vintage clips into a video timeline based on a natural language description. Returns an ordered list of clips with durations. Great for creating edit lists, storyboards, or mood reels.

**Parameters:**
- `query` (required) - Description of the video sequence (e.g., "american road trip summer vacation 1960s").
- `target_seconds` (optional) - Target timeline length in seconds, 20-600. Default: 60.
- `pace` (optional) - Editing pace: "slow" (4-8s/clip), "balanced" (3-6s/clip), "fast" (2-4s/clip). Default: "balanced".
- `year_from` / `year_to` (optional) - Year range filters.

### `check_clip_rights` (Free)

Verify that a clip is eligible for a specific intended use before licensing.

**Parameters:**
- `clip_id` (required) - The clip ID to check.
- `intended_use` (optional) - One of: "commercial", "editorial", "broadcast", "digital", "ai_training". Default: "commercial".

### `license_clip` ($10 USD)

License a clip for download. Returns the x402 protocol endpoint for payment. Payment is handled via [x402](https://x402.org) using USDC on Solana or Base.

**Parameters:**
- `clip_id` (required) - The clip ID to license.

---

## Pricing

| Format | Price | Details |
|--------|-------|---------|
| 144p preview | $10 USD | Instant via x402 USDC (Solana or Base) |
| HD (1080p) | Contact us | Available on request |
| 4K (2160p) | Contact us | Available on request |

**License terms:** Royalty-free, worldwide, perpetual, one-time purchase. Use in commercial projects, documentaries, editorial content, digital media, and AI training datasets.

---

## x402 Protocol Integration

The licensing endpoint uses the [x402 protocol](https://x402.org) (V2) for instant, trustless payments. Any x402-compatible agent or wallet can license clips without API keys or sign-up.

### How It Works

1. Agent calls `GET /x402/clip/{clip_id}/license`
2. Server returns HTTP 402 with `PAYMENT-REQUIRED` header
3. Agent's x402 client signs a USDC payment authorization
4. Agent retries with `PAYMENT-SIGNATURE` header
5. Server verifies and settles via facilitator, returns license + download URL

### Supported Networks

| Network | Chain ID (CAIP-2) | Token | Receiving Address |
|---------|-------------------|-------|-------------------|
| Solana mainnet | `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` | USDC | `FERR1XDCsvLRzU8U29baMY4XvZ8kwk52tUjqy3SaDRtQ` |
| Base mainnet | `eip155:8453` | USDC | `0x4AeeD280b6006Aa354e09427AF4F49bD09f9447B` |

### Direct x402 Endpoints (No MCP Required)

```bash
# Search (free, no auth)
curl "https://api.stockfilm.com/x402/search?q=beach+1960s&limit=5"

# Clip details (free)
curl "https://api.stockfilm.com/x402/clip/120818702"

# Rights check (free)
curl "https://api.stockfilm.com/x402/clip/120818702/rights?intended_use=commercial"

# License (returns 402 with payment instructions)
curl "https://api.stockfilm.com/x402/clip/120818702/license"
```

---

## Architecture

This MCP server is a remote Streamable HTTP server embedded in the Stockfilm Agent API (Rust/Axum). It does not require local installation -- agents connect directly over HTTPS.

```
Agent (Claude, GPT, etc.)
  |
  | MCP Streamable HTTP
  v
api.stockfilm.com/mcp
  |
  | Internal API calls
  v
Stockfilm Agent API (Rust/Axum)
  |
  +-- Search (PostgreSQL full-text + visual embeddings)
  +-- Rights verification
  +-- x402 payment processing (facilitator-mediated)
  +-- License management
  +-- Download token generation
```

### Discovery Endpoints

| Endpoint | Purpose |
|----------|---------|
| `https://api.stockfilm.com/.well-known/mcp.json` | MCP server discovery |
| `https://api.stockfilm.com/.well-known/stockfilm-agent.json` | Full agent manifest |
| `https://api.stockfilm.com/llms.txt` | LLM-readable service index |
| `https://api.stockfilm.com/v1/capabilities` | Machine-readable capability surface |
| `https://stockfilm.com/for-ai-agents` | Complete API documentation |

---

## Full Agent API

Beyond MCP, Stockfilm offers a complete agent-native API with HMAC-SHA256 request signing, multi-step licensing workflows, webhooks, and TypeScript/Python SDKs:

- **API Base:** `https://api.stockfilm.com`
- **Auth:** API key + HMAC-SHA256 signing for mutations
- **Payment Rails:** Solana USDC, Solana SOL, Lightning BTC
- **Docs:** [stockfilm.com/for-ai-agents](https://stockfilm.com/for-ai-agents)

---

## About Stockfilm

Stockfilm specializes in authentic archival home-movie footage -- the kind of footage that cannot be recreated by AI or restaged in a studio. Every reel was shot on real film by real families, capturing genuine moments from mid-20th-century life.

The archive includes footage from across the United States and around the world: suburban neighborhoods, family vacations, holiday celebrations, school events, road trips, city streets, and everyday life from an era that exists only on film.

**Website:** [stockfilm.com](https://stockfilm.com)
**Browse Clips:** [stockfilm.com/browse](https://stockfilm.com/browse)
**Popular Clips:** [stockfilm.com/popular](https://stockfilm.com/popular)
**Curated Collections:** [stockfilm.com/curated](https://stockfilm.com/curated)
**Agent Docs:** [stockfilm.com/for-ai-agents](https://stockfilm.com/for-ai-agents)
**Contact:** [stockfilm.com/contact](https://stockfilm.com/contact)

---

## License

The MCP server wrapper is open source under the MIT License.

The archival footage itself is proprietary content licensed per-clip through Stockfilm. Each clip purchase grants a royalty-free, worldwide, perpetual license for the specified use.