Integrations

MCP Server

The Vidiyo MCP server exposes your account as Model Context Protocol tools. Connect Cursor, Claude Desktop, or any MCP-compatible agent — then upload videos, manage your schedule, and query analytics using natural language or tool calls.

Connect your MCP client

Cursor IDE

Add this to .cursor/mcp.json in your project root, then restart Cursor:

{
  "mcpServers": {
    "vidiyo": {
      "command": "npx",
      "args": ["mcp-remote", "https://vidiyo-mcp-server.workers.dev/mcp"]
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/):

{
  "mcpServers": {
    "vidiyo": {
      "command": "npx",
      "args": ["mcp-remote", "https://vidiyo-mcp-server.workers.dev/mcp"]
    }
  }
}

Restart Claude Desktop, then verify: "Use the ping tool to check the Vidiyo MCP server."

MCP Inspector (debugging)

npx @modelcontextprotocol/inspector@latest # Enter: https://vidiyo-mcp-server.workers.dev/mcp

Authentication

Method 1 — API Key (recommended for agents)

For autonomous agents, CI pipelines, and any workflow that runs without a browser.
Generate a key in Studio → Account → API Keys, then call set_api_key.

set_api_key(api_key: "vk_live_...")

The key is stored in the Durable Object session and sent on every API call. It is not echoed back or logged. The tool verifies the key against the API before storing it and will reject invalid or revoked keys immediately.

Method 2 — Google OAuth (for interactive users)

Call authenticate — returns a URL
Visit the URL in your browser and sign in with Google
Return to your MCP client — the session is linked
JWTs refresh automatically; sessions persist for the Durable Object's lifetime

Tools

Core (4 tools)

Tool	Auth	Description
`ping`	None	Health check. Returns server status and auth method.
`authenticate`	None	Start Google OAuth. Returns a URL for the user to visit.
`set_api_key`	None	Authenticate with a creator API key. For agents without a browser.
`whoami`	Yes	Current user's profile and active auth method.

Browse (10 tools — no auth)

Tool	Auth	Description
`list_channels`	None	Paginated channel list, sorted by viewers.
`get_channel`	None	Channel detail by slug.
`get_channel_schedule`	None	Schedule blocks for a channel on a date.
`get_now_playing`	None	Current content + next upcoming on a channel.
`search`	None	Search channels and content.
`get_trending`	None	Trending search terms.
`get_home_feed`	None	Featured, live, and popular channels.
`get_content`	None	Public content item by UUID.
`list_categories`	None	All categories with channel counts.
`get_category`	None	Category detail with paginated channels.

Content library (1 tool)

Tool	Auth	Description
`list_my_content`	content:read	List your content library. Filter by status: 'ready' to find schedulable videos.

Schedule management (5 tools)

Tool	Auth	Description
`get_schedule`	schedule:read	Schedule blocks + gaps for a channel + date window.
`create_schedule_block`	schedule:write	Place a ready content item at a specific time. Returns 409 on overlap.
`update_schedule_block`	schedule:write	Move, resize, or swap content of an existing block.
`delete_schedule_block`	schedule:write	Remove a block. Content item is not deleted.
`fill_schedule_gaps`	schedule:write	Trigger async auto-fill to cover gaps with library content.

Uploads (2 tools)

Tool	Auth	Description
`init_direct_upload`	content:write	Start a direct-to-R2 upload. Returns a presigned URL + contentItemId.
`complete_direct_upload`	content:write	Finalize after the PUT succeeds. Triggers transcoding.

Channel management (5 tools)

Tool	Auth	Description
`create_channel`	channel:write	Create a new channel.
`update_channel`	channel:write	Update name, description, kind, category.
`publish_channel`	channel:write	Publish a draft channel.
`unpublish_channel`	channel:write	Take a channel offline.
`get_my_profile`	Yes	Authenticated user's profile.

Analytics (4 tools)

Tool	Auth	Description
`get_analytics_overview`	analytics:read	KPIs: views, watch time, revenue, trends.
`get_content_performance`	analytics:read	Per-content metrics with pagination.
`get_viewer_demographics`	analytics:read	Age, geography, devices, traffic sources.
`get_realtime_viewers`	analytics:read	Live viewer count and per-minute activity.

Favorites (3 tools)

Tool	Auth	Description
`list_my_favorites`	Yes	User's favorited channels.
`add_favorite`	Yes	Favorite a channel by slug.
`remove_favorite`	Yes	Unfavorite a channel.

Autonomous agent workflow

The complete flow for an AI agent that generates videos throughout the day and schedules them automatically:

# 1. Authenticate with API key (no browser needed)
set_api_key(api_key: "vk_live_...")

# 2. Upload a generated video
init_direct_upload(
  filename: "daily-briefing.mp4",
  title: "Daily Briefing — May 3",
  size_bytes: 52428800,
  content_type: "video/mp4",
  channel_id: "01936f4e-..."
)
# → { contentItemId, uploadUrl }
# Agent PUTs the file bytes to uploadUrl via HTTP

complete_direct_upload(content_item_id: "01936f4e-...")

# 3. Wait for transcoding (poll until status === "ready")
get_content(id: "01936f4e-...")   # repeat every 30s

# 4. Find an open slot
get_schedule(
  channel_id: "01936f4e-...",
  from: "2026-05-03T00:00:00Z",
  to: "2026-05-04T00:00:00Z"
)
# → inspect gaps[] to find open windows

# 5. Schedule the content
create_schedule_block(
  channel_id: "01936f4e-...",
  content_item_id: "01936f4e-...",
  starts_at: "2026-05-03T14:00:00Z"
)

Error handling

Status	MCP response
401	Authentication required. Call authenticate or set_api_key.
403 (scope)	API key is missing required scope(s): schedule:write
403 (ownership)	You don't own this channel.
404	The requested resource was not found.
409	That time slot already has a block. Move or shorten it first.
429	Rate limit exceeded. Please wait before retrying.
503	The Vidiyo API is currently unavailable. Please try again later.

MCP endpoints

Environment	URL
Production	`https://vidiyo-mcp-server.workers.dev/mcp`
Staging	`https://vidiyo-mcp-server-staging.workers.dev/mcp`
Local dev	`http://localhost:8787/mcp`

Transport: Streamable HTTP (SSE fallback supported). Standard MCP protocol — no vendor extensions.

Get API keys →REST API reference