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": {
      "url": "https://vidiyo-mcp-server.davidnaffis.workers.dev/mcp"
    }
  }
}

Claude (web, Desktop, and mobile)

Claude connects to remote MCP servers natively. Go to Settings → Connectors → Add custom connector, name it Vidiyo, and enter the MCP URL above. Enable it in a chat via the + menu, then verify: "Use the ping tool to check the Vidiyo MCP server." For Claude Code:

claude mcp add --transport http vidiyo https://vidiyo-mcp-server.davidnaffis.workers.dev/mcp

ChatGPT

Requires a paid plan. Enable Settings → Connectors → Advanced settings → Developer Mode, then Connectors → Create with the MCP URL and authentication set to None (you authenticate in-session with set_api_key). Enable the connector per chat via + → More → Developer Mode.

Grok

Go to grok.com/connectors → New Connector → Custom and enter the MCP URL. For the xAI API, pass the URL as an mcp tool with server_url and server_label.

MCP Inspector (debugging)

npx @modelcontextprotocol/inspector@latest # Enter: https://vidiyo-mcp-server.davidnaffis.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 recency.
`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.

Playback (1 tool — no auth)

Tool	Auth	Description
`get_stream_url`	None	HLS master playlist URL, now-playing EPG, and VMAP ad tag for a channel.

Content library (7 tools)

Tool	Auth	Description
`list_my_content`	content:read	List your content library. Filter by status: 'ready' to find schedulable videos.
`get_my_content_item`	content:read	Full detail for one owned item: renditions, captions, thumbnails, transcode status.
`update_content`	content:write	Update title, description, channel, rating, or tags.
`delete_content`	content:write	Soft-delete a content item.
`retry_transcode`	content:write	Re-queue a failed transcode without re-uploading.
`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.

Two ways to upload a video. If your agent can make an HTTP PUT (Cursor, Claude Code, scripts), use init_direct_upload + complete_direct_upload. If it's a chat client that can't send file bytes (Claude web, ChatGPT, Grok), host the file at a public URL and use ingest_from_url — it works for any video, not just AI-generated content.

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.

Channel management (8 tools)

Tool	Auth	Description
`get_my_channels`	channel:read	List all channels you own, including drafts.
`get_channel_dashboard`	channel:read	Realtime viewers, 7-day overview, now-playing, content counts.
`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.
`delete_channel`	channel:write	Soft-delete a channel you own.
`get_my_profile`	Yes	Authenticated user's profile.

Analytics (7 tools)

Tool	Auth	Description
`get_analytics_overview`	analytics:read	Per-channel KPIs: views, sessions, watch minutes, trends.
`get_content_performance`	analytics:read	Per-content metrics with pagination.
`get_viewer_demographics`	analytics:read	Country and platform breakdown.
`get_realtime_viewers`	analytics:read	Live viewer count and per-minute activity.
`get_creator_overview`	analytics:read	Cross-channel totals with per-channel breakdown.
`get_analytics_timeseries`	analytics:read	Daily series for views, sessions, watch minutes, or ad impressions.
`get_creator_analytics_summary`	analytics:read	Compact today-vs-last-week snapshot.

Favorites and follows (7 tools)

Tool	Auth	Description
`list_my_favorites`	Yes	User's favorited channels.
`add_favorite`	Yes	Favorite a channel by UUID or slug.
`remove_favorite`	Yes	Unfavorite a channel.
`list_followed_creators`	Yes	Creators the user follows.
`follow_creator`	Yes	Follow a creator by username.
`unfollow_creator`	Yes	Unfollow a creator.
`list_followed_collections`	Yes	Channel collections the user follows.

Ingest, AI creation, Autopilot, and credits (10 tools)

Tool	Auth	Description
`ingest_from_url`	content:write	Ingest any publicly downloadable video URL (not just AI output). The upload path for chat clients that can't PUT file bytes.
`estimate_generation`	Yes	Price an AI generation in credits without submitting. Free.
`request_generation`	credits:spend	Submit an AI video generation. Spends credits.
`get_generation`	Yes	Status of one creation job.
`list_generations`	Yes	Recent creation jobs, newest first.
`cancel_generation`	Yes	Cancel a pre-submission job; refunds the hold.
`create_brief`	credits:spend	Recurring Autopilot programming brief on a channel.
`list_briefs`	Yes	Briefs with status and next run time.
`run_brief`	credits:spend	Trigger a brief run now. Spends credits within caps.
`get_credits`	Yes	Credits balance and recent transactions.

Webhooks (4 tools)

Tool	Auth	Description
`list_webhooks`	content:write	Your outbound webhook subscriptions with status and delivery stats.
`create_webhook`	content:write	Subscribe an HTTPS endpoint to pipeline events. Returns the signing secret once.
`delete_webhook`	content:write	Remove a subscription.
`enable_webhook`	content:write	Re-enable a subscription auto-disabled after delivery failures.

Payouts and viewer (2 tools)

Tool	Auth	Description
`get_payout_summary`	Yes	Stripe Connect status, payout history, pending balance.
`get_continue_watching`	Yes	In-progress viewing sessions with position and last-watched time.

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_my_content_item(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.davidnaffis.workers.dev/mcp`
Staging	`https://vidiyo-mcp-server-staging.davidnaffis.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