MCP

MCP server documentation

Connect veridive to any MCP-compatible AI client and call your library and YouTube research pipelines through natural conversation.

Overview

The veridive MCP server speaks the Model Context Protocol over Streamable HTTP. Point a client at the endpoint below, authenticate, and your assistant can search and import library content, run YouTube tools, and run agentic research that returns grounded, citation-backed answers.

Endpointhttps://mcp.veridive.com/mcp

Available on every plan, including Free — usage is credit-metered, so all you need is credits in your wallet.

Get Started

Web clients (Claude, ChatGPT) connect by URL and sign in — no key. Desktop and CLI clients use an API key you generate in Settings → Integrations.

How to connect

1
Open Settings → Connectors → Add Custom Connector
2
Paste this URL:
https://mcp.veridive.com/mcp
3
Sign in with your veridive account — no key needed.

Authentication

Web connectors authenticate via sign-in. Desktop / CLI clients send a bearer API key on every request:

Authorization: Bearer vd_mcp_...

Generate, name, and revoke keys in Settings → Integrations. A key is shown only once at creation — store it somewhere safe.

Rate Limits & Quotas

Catalog tool runs (run_youtube_tool) draw from a per-account daily free credit budget that resets each day; once it's used up, runs fall back to your wallet. Other credit-bearing tools (the Deep tools, chat, imports) bill the wallet directly. Check your balance and remaining budget at any time withget_credit_status.

Fair-use rate limits apply per account across a per-tool-per-minute window, a global per-minute window, and a short burst window. Exceeding them returns a rate-limit error — back off and retry.

Tools Reference

Deep Tools

deep_querycreditsstreams

Agentic YouTube research — runs the full DeepQuery pipeline (search → select → transcribe → retrieve → generate) and synthesizes a grounded answer.

Parameters

promptrequired

Research question or instruction.

intelligenceoptional

defaultthinkingpro

Quality dial / model bundle. Omit to use your tier default.

depthoptional

standardextended

Retrieval breadth. standard hones in on the most relevant videos; extended searches wider across more of YouTube. Only applies when intelligence is pro; coerced to standard otherwise.

channeloptional

Channel filter — accepts a channel id, URL, or @handle. When set, search is restricted to that channel.

chat_idoptional

Existing MCP chat id to continue. Omit to start fresh — the new id is returned so you can resume next turn.

Returns

A grounded answer with inline timestamp citations. For purely conversational prompts use chat instead — deep_query detects non-research prompts and refunds the reservation.

deep_contextcreditsstreams

Chat over a selection of videos already in your library. Same pipeline as deep_query, but scoped to the items you provide.

Parameters

promptrequired

Question or instruction to ground against the chosen library items.

library_item_idsrequired

1–20 library item IDs (from library_search / library_list) to scope the chat against.

intelligenceoptional

defaultthinkingpro

Quality dial / model bundle. Omit to use your tier default.

depthoptional

standardextended

Retrieval breadth over the chosen items. standard hones in on the most relevant chunks; extended casts a wider net. Only applies when intelligence is pro.

chat_idoptional

Existing MCP chat id to continue; new id is returned to resume.

Returns

A grounded answer with citations back to specific transcript chunks of the provided items.

deep_searchcreditsstreams

Transcript-aware YouTube video search — find the videos that actually answer a query (not just the most-viewed). Runs search → filter → transcript deep-read → classify → rank. Videos that fail an active filter are dropped (no greyed pool).

Parameters

queryrequired

What to search YouTube for (1–500 chars).

typeoptionaldefault all

allvideosshorts

Video kind. all = videos and shorts; videos = exclude Shorts (<60s); shorts = only Shorts.

upload_dateoptional

hourtodaythis_weekthis_monththis_year

Recency filter — only videos uploaded within this window. Omit for no recency limit.

sort_byoptional

relevanceupload_dateview_countrating

Result ordering. Omit for the transcript-aware blended rank (relevance); upload_date = newest first; view_count = most-viewed; rating = top rated.

lengthoptional

shortmediumlong

Duration — short (<4 min), medium (4–20 min), long (>20 min). Omit for any length.

reachoptional

nichebalancedverified

Channel-reach preference. balanced (default) mixes popular + niche; niche surfaces hidden gems from smaller channels; verified restricts to verified channels. Affects ranking, so set it here rather than post-filtering.

content_typesoptional

tutorialreviewopinioninterviewnewsdocumentaryexplainervlogpodcastlectureentertainmentgameplaymusicsportsreactioncompilation

List — keep only videos whose transcript-classified content type is one of these (e.g. [review, opinion]). Non-matching videos are dropped. Omit for any type.

leveloptional

beginnerintermediateadvanced

Keep only videos at this expertise level. Non-matching videos are dropped. Omit for any level.

fastoptionaldefault false

Fast mode — skip the transcript deep-read (metadata-only, cheaper, ~10-credit floor), but the result cards then carry NO transcript labels / evidence / summary. Leave false for the transcript-aware analysis.

limitoptional

Return only the top N ranked videos (e.g. 5). Omit for the whole analyzed pool. NOTE: this only trims the response — it does NOT reduce credits (cost is by videos analyzed, not returned).

Returns

Ranked video cards, each with descriptive labels (content_type, level, a short summary), boolean quality verdicts (high_density, ad_free, clear_title, actionable, original, factual), and an evidence snippet + timestamp.

Library Tools

library_searchfree

Full-text search across the titles of videos in your library.

Parameters

queryrequired

Free-text query matched against library item titles.

item_typeoptional

Filter to a single content type. Omit to search all types.

tag_namesoptional

List — items tagged with ANY of these tag names. Unknown tags are dropped silently and reported in warnings.

pageoptionaldefault 1

1-indexed page number.

per_pageoptionaldefault 20

Items per page (max 50). Prefer narrowing the query over fetching more.

Returns

Matching library items with metadata.

library_listfree

Browse and filter your saved content with sorting.

Parameters

item_typeoptional

Filter to a single content type. Omit to include all types.

tag_namesoptional

List — items tagged with ANY of these tag names. Unknown tags dropped (reported in warnings).

is_favoriteoptional

When true, return only favorites. Omit for no favorite filter.

sort_byoptionaldefault created_at

Field to sort by.

sort_orderoptionaldefault desc

ascdesc

Sort direction.

pageoptionaldefault 1

1-indexed page number.

per_pageoptionaldefault 20

Items per page (max 50).

Returns

A page of library items.

library_import_youtube_videocreditsstreams

Import a single YouTube video into your library.

Parameters

urlrequired

YouTube video URL (youtube.com/watch?v=… or youtu.be/…).

tag_idsoptional

Optional tags to apply to the imported item (up to 20 tag UUIDs).

Returns

Resolves when the video reaches a terminal status (COMPLETED / FAILED / NO_TRANSCRIPT). Idempotent. Charged per transcript size.

library_import_youtube_channelcreditsstreams

Import a whole channel (or playlist) into your library.

Parameters

urlrequired

Channel URL (youtube.com/@channel) or playlist URL (youtube.com/playlist?list=…).

idempotency_keyoptional

Repeating the same key with identical input returns the same parent without re-importing. Auto-generated if omitted, but persisted callers should supply their own so retries dedup.

tag_idsoptional

Optional tags applied to all imported items.

include_shortsoptionaldefault false

Channel only — include YouTube Shorts. Ignored for playlists.

include_livesoptionaldefault false

Channel only — include Live streams. Ignored for playlists.

Returns

Resolves when all children reach terminal status; streams per-child updates. Charged per imported video.

YouTube Tools

get_youtube_transcriptfree

Fetch the stored transcript + metadata for a video already imported into your library. Provide exactly one of the three inputs.

Parameters

library_item_idoptional

LibraryItem id from library_search / library_list. Fastest path — resolves directly.

video_urloptional

Full YouTube URL — parsed and resolved to your library item.

video_idoptional

Bare 11-char YouTube video id — resolved to your library item.

Returns

Timestamped transcript segments + video metadata.

run_youtube_toolcredits

One generic entry point over the whole YouTube tool catalog — pick a tool by slug and run it on a video.

Parameters

toolrequired

Which catalog tool to run — one of the 32 slugs in the catalog below.

urlrequired

Full YouTube URL or bare 11-char video id.

optionsoptional

Per-tool knobs as a string→string dict (e.g. { summary_length: brief }). Only 7 tools take options — see the catalog below. Unknown / missing keys fall back to the tool's defaults.

Returns

Segments, markdown, or structured json_data depending on the tool. Covered by the daily free budget up to its limit.

Catalog

32 slugs · 7 with options

transcriptsegments

chapter-generatormarkdown

key-quotesjson

how-to-extractormarkdown

meeting-notesmarkdown

podcast-notesmarkdown

action-itemsjson

study-notesmarkdown

flashcardsjsoncount=8|12|16 · difficulty=easy|medium|hard

quiz-generatorjsoncount=5|8|10 · difficulty=easy|medium|hard

mindmapjsondepth=brief|standard|detailed

documentjsonlength=short|standard|long · style=analytical|educational|narrative

presentationjsonslide_count=6|10|15 · detail_level=minimal|standard|detailed

infographicjsoncolor_scheme=blue|green|purple|orange|red

vocabulary-builderjson

title-generatorjson

description-generatormarkdown

tag-extractorjson

hashtag-generatorjson

hook-gradermarkdown

shorts-scriptmarkdown

blog-postmarkdown

x-postjson

linkedin-postjson

newsletterjson

slidesmarkdown

most-replayedjson

comment-summarizermarkdown

comment-sentimentjson

srt-vtt-downloadersegments

stt-transcriptionsegments

Conversational & Utility

chatcreditsstreams

Plain conversational chat with no YouTube retrieval — follow-ups, clarifications, brainstorming.

Parameters

promptrequired

The user's message or question.

intelligenceoptional

instantthinkingpropro_extended

Quality dial. instant = fastest / cheapest (simple replies); thinking adds a reasoning pass; pro / pro_extended route to the deepest model for complex, multi-step questions. Omit to use your tier default.

chat_idoptional

Existing MCP chat id to continue; new id is returned to resume.

Returns

An assistant reply. Available on every plan — usage is credit-metered.

pingfree

Health check — verify your client can reach veridive.

Parameters

messageoptionaldefault pong

Echoed back verbatim. Useful for debugging client serialization.

Returns

The server version + your echoed message.

get_credit_statusfree

Read your current credit state. Takes no inputs.

Returns

Wallet balance, plan tier, and today's free-budget remaining / limit / used.