AI Integration

MCP Integration

Connect your Castiz video library to AI assistants using the Model Context Protocol (MCP). Enable semantic video search directly from Cursor, Windsurf, Claude Desktop, and more.

What is MCP?

The Model Context Protocol (MCP) is an open standard that allows AI assistants to connect with external data sources and tools. Castiz provides an MCP server that exposes your video library to AI assistants, enabling natural language video search.

Semantic Search

Search videos by meaning, not just keywords. Works in English and Hebrew.

Instant Results

AI-powered embeddings provide fast, relevant results from your library.

AI-Native

Works seamlessly with AI coding assistants and chat interfaces.

Supported Platforms

Cursor

AI-powered code editor

~/.cursor/mcp.json

Windsurf

AI development environment

~/.windsurf/mcp.json

Claude Desktop

Anthropic's Claude assistant

~/Library/Application Support/Claude/claude_desktop_config.json

Quick Start

1. Get your API Key

Go to your Dashboard → Settings → API Keys and create a new API key with read scope.

2. Configure your AI assistant

Add the Castiz MCP server to your configuration file. The location depends on your platform:

Cursor:~/.cursor/mcp.json

Windsurf:~/.windsurf/mcp.json

Claude Desktop:~/Library/Application Support/Claude/claude_desktop_config.json

mcp.json (using uvx - recommended)

{
  "mcpServers": {
    "castiz": {
      "command": "uvx",
      "args": ["--from", "castiz-mcp", "castiz-mcp"],
      "env": {
        "CASTIZ_API_KEY": "sk_live_your_api_key_here"
      }
    }
  }
}

Alternative using npx:

mcp.json (using npx)

{
  "mcpServers": {
    "castiz": {
      "command": "npx",
      "args": ["-y", "castiz-mcp"],
      "env": {
        "CASTIZ_API_KEY": "sk_live_your_api_key_here"
      }
    }
  }
}

3. Restart your AI assistant

Quit and reopen your AI assistant. The Castiz tools should now be available.

4. Try it out

Ask your AI assistant to search your videos:

"Search for holiday videos in my Castiz library"

"Find videos about cooking tutorials"

"What videos do I have about product demos?"

Available Tools

search_videos

Search for videos using natural language queries

Parameters

query*

string

Natural language search query (supports Hebrew and English)

limit

integer

Maximum number of results (default: 20, max: 100)

similarity_threshold

float

Minimum similarity score 0-1 (default: 0.5)

Response Format

The search tool returns a JSON object with the matching videos and query interpretation:

Example Response

{
  "videos": [
    {
      "id": "181e00e6-496c-4821-9d6b-7451734318ed",
      "uri": "/videos/181e00e6-496c-4821-9d6b-7451734318ed",
      "name": "Holiday Songs Collection",
      "description": "A collection of holiday songs for children...",
      "thumbnail": "https://cdn.castiz.com/thumbnails/.../thumb.jpg",
      "duration": 102,
      "tags": ["holiday", "songs", "children"],
      "relevance_score": 0.87,
      "match_type": "semantic"
    }
  ],
  "total_count": 1,
  "query_interpretation": {
    "original_query": "holiday songs for kids",
    "normalized_query": "holiday songs for kids",
    "detected_tags": [],
    "semantic_terms": ["holiday", "songs", "kids"],
    "search_strategy": "semantic"
  }
}

Response Fields

Field	Description
id	Unique video identifier (UUID)
uri	API path to the video resource
name	Video title
description	Video description
thumbnail	URL to thumbnail image
duration	Duration in seconds
tags	Array of tag names
relevance_score	Similarity score (0-1)
match_type	How matched: semantic, tag, or hybrid

Troubleshooting

Tools not showing up

Make sure you've restarted your AI assistant after adding the configuration. Check that the config file path is correct for your platform.

Authentication errors

Verify your API key is correct and has not been revoked. API keys start with sk_live_ or sk_test_.

No results returned

Try lowering the similarity_threshold parameter (e.g., 0.3). Make sure your videos have been indexed for semantic search.

REST API Alternative

You can also use the search functionality via REST API:

cURL

curl -X POST "https://api.castiz.com/skills/search_videos/execute" \
  -H "X-API-Key: sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"query": "holiday songs", "limit": 10}'