MCP tools
Every tool the Viral Swipe File MCP server offers, with its arguments, from the same list the server registers. 26 tools; your assistant picks them, you ask in plain words.
search_library
read-onlySearch the library
Search the stored Viral Swipe File catalog by topic, creator or category name. Returns matching videos, creators, niches and formats with IDs, slugs, descriptions and page URLs; video hits have no stats. Accepts plain keywords, not Boolean operators. May expand a word prefix or correct spelling, disclosed in hint or corrected_query. Preview access caps results. No pagination or live platform search.
querystringrequiredPlain keywords, e.g. "morning routine", "skincare", a creator name. No OR, AND or quotes; videos holding every word rank first. 2 to 200 characters.
limitintegerHow many to return (1–25, default 10). Default
10.
list_videos
read-onlyList viral videos
Retrieve stored TikToks and Instagram Reels by the supplied filters, ordered by viral factor, views or recency. Returns hooks, descriptions, stats, classification labels where available, and source links. Classification filters match classified videos only. Preview access caps results; next_offset is null at the available end. Missing creators return found: false and possible matches. followed: true lists only the creators and brands the workspace follows, with every filter. Six cards by default. Does not fetch new posts or measure live trends.
nichestringThe niche slug from its page URL ("fitness") or its plain name. Call list_niches if unsure. 1 to 120 characters.
formatstringThe format slug from its page URL ("selfie-with-background") or its plain name. Call list_formats if unsure. 1 to 120 characters.
brandstringThe brand slug from its page URL ("gauth") or its plain name. Call list_brands if unsure. 1 to 120 characters.
platformenumOne of
instagram,tiktok.creatorstringCreator username, with or without @. 1 to 100 characters.
languagestringThe video's language as a two-letter code, e.g. en, es, fr, pt.
visual_formatstringOnly videos in this visual format, e.g. "ugc-selfie", "app-mockup", "text-overlay", "screen-recording". Classified videos only; a video's own visual_formats are on its card. 1 to 60 characters.
hook_tacticenumOnly videos whose hook_tactic is this. Classified videos only; get_video returns available classification labels. One of
aspirational,authority,belief,bold-claim,call-to-action-first,challenge,contrast,confession,contrarian,curiosity,demographic-callout,direct-address,directive,exclusivity,explainer,fomo,how-to,if-then,listicle,myth-busting,offer-only,price-anchor,question,reasons-why,relatability,reverse-psychology,risk-reversal,shocking-statement,social-proof,statistic,storytelling,urgency,warning,none.toneenumOnly videos whose tone is this. Classified videos only; get_video returns available classification labels. One of
relatable,funny,surprising,aspirational,emotional,educational,controversial,dramatic,wholesome,satisfying.emotional_triggerenumOnly videos whose emotional_trigger is this. Classified videos only; get_video returns available classification labels. One of
fear,frustration,relief,hope,pride,belonging,curiosity,aspiration,urgency,fomo,guilt,none.talentenumOnly videos whose talent is this. Classified videos only; get_video returns available classification labels. One of
none,creator,founder,customer,model.awarenessenumOnly videos whose awareness is this. Classified videos only; get_video returns available classification labels. One of
unaware,problem-aware,solution-aware,product-aware,most-aware.asset_typeenumOnly videos whose asset_type is this. Classified videos only; get_video returns available classification labels. One of
ugc,hybrid,lifestyle-image-text,product-image-text,text-only,illustration,ugc-mashup,other.content_typeenumOne of
video,photo.creator_genderenumOne of
male,female.daysintegerOnly videos posted in the last N days, e.g. 90, 365. The library is an archive, so a short window can be empty: sort by recent to see its newest.
min_viral_factornumberOnly videos with at least this viral factor, e.g. 4, 8, 32.
searchstringPlain words over hook, caption, description, niche, formats and creator; no OR, AND or quotes. Videos holding every word rank first. Accents are ignored, a last word of four letters or more can be a word start, and when the first page is empty misspelt words are corrected and searched once more (
corrected_querysays what was searched). 2 to 200 characters.sortenumOrder by viral factor (viral, default), view count (views), or posting date (recent, newest first). One of
viral,views,recent. Defaultviral.followedbooleantrue: only the videos of the creators and brands the workspace follows (the app's Track feed), with every other filter and sort. list_followed_videos is the same feed, newest first, with the creators followed.
workspacestringOptional: the workspace's id or exact name, from list_workspaces. Without it, the current workspace. 1 to 120 characters.
limitintegerHow many to return (1–50, default 6). Default
6.offsetintegerNumber of results to skip. Use the preceding next_offset; null means no further page is available. Default
0.
get_video
read-onlyGet a video
Retrieve one stored video by its UUID for close analysis: full hook and description, available stats, creator, niche, formats, classification labels and links. how_its_built describes its construction, not the cause of its performance; it may be null and is omitted with preview access. Does not return a video download or full transcript. Unknown IDs return an error.
idstring (uuid)requiredThe video id, as in its page URL /videos/<id>.
list_niches
read-onlyList niches
Retrieve the catalog's available niches, names, slugs, video counts and page URLs, for browsing or resolving a niche filter. Takes no input and does not count against the team's tool-call allowance. Covers this catalog only, not every topic on TikTok or Instagram.
list_formats
read-onlyList formats
Retrieve the catalog's available library formats, names, slugs, video counts and page URLs, for browsing or resolving a format filter. These differ from classification visual_format labels. Takes no input and does not count against the team's tool-call allowance.
list_brands
read-onlyList brands
Retrieve published apps and brands promoted in the catalog's videos, ordered by video count, with slugs, creator and video counts, top viral factor and links. Publication requires verified source, sufficient coverage and an acceptable name. Preview access caps this list; it has no search or pagination input. Absence from a result does not establish why a brand is missing or whether it runs paid campaigns.
get_brand
read-onlyGet a brand
Retrieve a published brand by slug or matching name: stored video and creator counts, views, viral factors, top hooks, creators and links. Includes its niche, format and classification mix when access permits; preview access omits mix. Unknown or unpublished brands return an error. These are catalog aggregates, not the brand's account analytics or proof of paid sponsorship.
brandstringrequiredThe brand slug from its page URL ("gauth") or its plain name. Call list_brands if unsure. 1 to 120 characters.
list_saved_videos
read-onlyList my saved videos
Retrieve a workspace's saved library videos and their shared notes, newest save first, for a requested review or brief. Returns video cards, note (null when absent), next_offset and the workspace read. workspace takes an id or exact name from list_workspaces; without it, the current workspace. Preview access caps results; no saves returns an empty list. Cannot read another organization's saves. To change saves and notes, use save_video, unsave_video and set_video_note.
limitintegerHow many to return (1–100, default 20). Default
20.offsetintegerNumber of results to skip. Use the preceding next_offset; null means no further page is available. Default
0.workspacestringOptional: the workspace's id or exact name, from list_workspaces. Without it, the current workspace. 1 to 120 characters.
list_followed_videos
read-onlyList new videos from creators I follow
Retrieve the newest library videos from the creators a workspace follows, newest to join the library first, with the followed creators. Returns video cards, next_offset, the creators (handle, platform, app page URL) and the workspace read. workspace as in list_saved_videos. Empty when the workspace follows nobody; the result then says where following is set up. Preview access caps results. Covers creators in this library only, not a live feed of their accounts.
limitintegerHow many to return (1–50, default 20). Default
20.offsetintegerNumber of results to skip. Use the preceding next_offset; null means no further page is available. Default
0.workspacestringOptional: the workspace's id or exact name, from list_workspaces. Without it, the current workspace. 1 to 120 characters.
list_boards
read-onlyList my boards
Retrieve a workspace's boards, A to Z: each with its id, name, how many videos it holds, its app URL and its share_url when its public share link is on (null when off). Use the ids or exact names with the board tools in the same workspace. Takes an optional workspace. Does not count against the team's tool-call allowance.
workspacestringOptional: the workspace's id or exact name, from list_workspaces. Without it, the current workspace. 1 to 120 characters.
list_workspaces
read-onlyList my workspaces
Retrieve the organization's workspaces, oldest first: each with its id, name, current (true for the one calls act in without a workspace argument) and locked (past the plan's workspaces: it cannot be read or changed). Saves, notes, boards and follows belong to one workspace; pass its id or exact name as workspace to the tools that take one. Does not count against the team's tool-call allowance.
switch_workspace
read-onlySwitch workspace
Make a workspace of the organization (its id or exact name, from list_workspaces) the one this connection works in: every later call without workspace reads and writes there, until the next switch. Only this connection moves; the user's workspace on the site, and their other assistants', stay where they are. Returns the workspace now active and the previous one. A workspace the caller may not use (another organization's, a guest's, one past the plan's workspaces) is refused, and nothing moves. Switch only when the user asks to work on another client or brand. Does not count against the allowance.
workspacestringrequiredThe workspace's id or exact name, from list_workspaces: calls without
workspaceact there from now on. 1 to 120 characters.
get_usage
read-onlyCheck my remaining calls
Retrieve the team's MCP and API calls this period: used, limit, left, per (day, month, or life for an account with no plan, whose preview calls never reset), resets_at (when the count starts again, UTC; null when it never does) and exhausted; on a monthly plan, today holds the daily ceiling, and left and exhausted follow whichever limit runs out first. MCP tool calls and JSON API requests share this allowance. A team whose calls are not counted answers limit: null. Read-only and does not count against the allowance. Call it before a long run of reads, or when the user asks how many calls are left.
get_saved_video
read-onlyInspect a saved video
Read one video's save state in the specified workspace, or the current one: saved, the workspace note, and every board containing it with that board's note and whether its link is public (shared). Use before replacing a note, removing a board item or unsaving, to show what would be lost and identify public changes. Accepts a video id or page URL. Returns saved: false and an empty boards list when absent. Read-only, unmetered and available without a paid plan; workspace access rules still apply. Does not return the video's catalog details.
video_idstringrequiredThe video id from list_videos, search_library or get_video, or its Viral Swipe File page URL (/videos/<id>). 1 to 300 characters.
workspacestringOptional: the workspace's id or exact name, from list_workspaces. Without it, the current workspace. 1 to 120 characters.
save_video
changes your accountSave a video
Save an existing library video in the specified workspace, or the current one when omitted, when the user asks to save it. video_id takes the video id from list_videos, search_library or get_video, or its Viral Swipe File page URL. Returns the video id and URL, saved: true, the saved videos page URL and the workspace. The save is visible to everyone in that workspace and appears in list_saved_videos. Saving a saved video changes nothing and keeps its note. Needs a trial or a plan; otherwise nothing is saved and the answer says so. Does not add the video to a board, download it, or change the original post.
video_idstringrequiredThe video id from list_videos, search_library or get_video, or its Viral Swipe File page URL (/videos/<id>). 1 to 300 characters.
workspacestringOptional: the workspace's id or exact name, from list_workspaces. Without it, the current workspace. 1 to 120 characters.
unsave_video
changes your accountUnsave a video
Unsave a video in the workspace: it leaves list_saved_videos and every board it was on, and its notes go with it. Read get_saved_video first and confirm with the user when it is on a board or has a note, explaining which notes and board entries will be removed. A video that is not saved succeeds and changes nothing. Open on every plan.
video_idstringrequiredThe video id from list_videos, search_library or get_video, or its Viral Swipe File page URL (/videos/<id>). 1 to 300 characters.
workspacestringOptional: the workspace's id or exact name, from list_workspaces. Without it, the current workspace. 1 to 120 characters.
set_video_note
changes your accountWrite a note on a saved video
Write the workspace's note on a saved video (why it is worth keeping, what to borrow), or with board that board's own note on it. Replaces the note there, and the old text is not kept; an empty note clears it. Read get_saved_video first; show the existing note and confirm before replacing it. A board-specific note is public when that board is shared: explain this and confirm before publishing new text. The video must be saved, or on the board, first (save_video, add_video_to_board). get_saved_video returns workspace and board-specific notes; list_saved_videos returns only the workspace note. Open on every plan.
video_idstringrequiredThe video id from list_videos, search_library or get_video, or its Viral Swipe File page URL (/videos/<id>). 1 to 300 characters.
notestringrequiredThe note, up to 500 characters; an empty string clears it.
boardstringOptional: the board (id or exact name) whose own note on the video to write. Without it, the note on the saved video. 1 to 120 characters.
workspacestringOptional: the workspace's id or exact name, from list_workspaces. Without it, the current workspace. 1 to 120 characters.
create_board
changes your accountCreate a board
Create a board with name in the specified workspace, or the current one when omitted, when the user asks for one. Board names are unique in a workspace: a name that exists returns that board with created: false. Optional video_id (a library video id or its page URL) also saves that video and puts it on the board. Returns the board id, name, video count, app URL, share_url (null for a new board; an existing board keeps its link) and the workspace. A new board is visible to the workspace only. If the name already exists, optional video_id adds to that existing board; when it is shared, the added video becomes public. With video_id, check list_boards first and confirm that public addition before calling. Needs a trial or a plan; otherwise nothing is created and the answer says so.
namestringrequiredThe board's name, up to 60 characters. 1 to 60 characters.
video_idstringOptional: a library video to save and put on the new board (its id or page URL). 1 to 300 characters.
workspacestringOptional: the workspace's id or exact name, from list_workspaces. Without it, the current workspace. 1 to 120 characters.
rename_board
changes your accountRename a board
Rename one of the workspace's boards (by id or exact name from list_boards) with name. Its videos, notes and share link stay as they are. A name another board of the workspace has is refused. Open on every plan.
boardstringrequiredThe board's id or its exact name, from list_boards. 1 to 120 characters.
namestringrequiredThe board's name, up to 60 characters. 1 to 60 characters.
workspacestringOptional: the workspace's id or exact name, from list_workspaces. Without it, the current workspace. 1 to 120 characters.
delete_board
changes your accountDelete a board
Delete one of the workspace's boards, by id or exact name. Its videos stay saved (list_saved_videos), its board notes go, and its share link stops working. Cannot be undone: confirm with the user first. A board that is not there answers found: false. Open on every plan.
boardstringrequiredThe board's id or its exact name, from list_boards. 1 to 120 characters.
workspacestringOptional: the workspace's id or exact name, from list_workspaces. Without it, the current workspace. 1 to 120 characters.
add_video_to_board
changes your accountAdd a video to a board
Put a library video on an existing board in the specified workspace, or the current one when omitted, when the user asks. board takes an id or exact name from list_boards; video_id a library video id or its page URL. Also saves the video in that workspace. Returns the board, the video, on_board: true and the workspace. Check list_boards first: if the share link is on, anyone with the link sees the added video; explain this and confirm the public addition. Adding a video already on the board changes nothing. Needs a trial or a plan.
boardstringrequiredThe board's id or its exact name, from list_boards. 1 to 120 characters.
video_idstringrequiredThe video id from list_videos, search_library or get_video, or its Viral Swipe File page URL (/videos/<id>). 1 to 300 characters.
workspacestringOptional: the workspace's id or exact name, from list_workspaces. Without it, the current workspace. 1 to 120 characters.
remove_video_from_board
changes your accountRemove a video from a board
Take a video off one of the workspace's boards; it stays saved, but its board-specific note is deleted. Read get_saved_video first and confirm any note loss. If shared, the public board also loses the item. A video that is not on the board succeeds and changes nothing. Open on every plan.
boardstringrequiredThe board's id or its exact name, from list_boards. 1 to 120 characters.
video_idstringrequiredThe video id from list_videos, search_library or get_video, or its Viral Swipe File page URL (/videos/<id>). 1 to 300 characters.
workspacestringOptional: the workspace's id or exact name, from list_workspaces. Without it, the current workspace. 1 to 120 characters.
follow_creator
changes your accountFollow a creator
Follow a library creator in the workspace, as the Follow button on their page does: their new library videos then show in list_followed_videos and on the app's Track page. creator takes their TikTok or Instagram handle (with or without @); platform picks one when the handle is on both. Only creators with videos in the library can be followed. Following a creator already followed succeeds and changes nothing. Returns how many creators the organization follows and how many its plan allows, across its workspaces. When the plan follows nobody, or the organization is at its cap, nothing is followed and the answer says so: relay it once, do not retry.
creatorstringrequiredThe creator's TikTok or Instagram handle, with or without @ ("@creatorname"), as list_videos and search_library return it. 1 to 60 characters.
platformenumOptional: the creator's platform, when the handle is on both. One of
tiktok,instagram.workspacestringOptional: the workspace's id or exact name, from list_workspaces. Without it, the current workspace. 1 to 120 characters.
unfollow_creator
changes your accountStop following a creator
Stop following a creator in the workspace: their videos leave list_followed_videos and the Track page. Open on every plan. Unfollowing a creator the workspace does not follow succeeds and changes nothing.
creatorstringrequiredThe creator's TikTok or Instagram handle, with or without @ ("@creatorname"), as list_videos and search_library return it. 1 to 60 characters.
platformenumOptional: the creator's platform, when the handle is on both. One of
tiktok,instagram.workspacestringOptional: the workspace's id or exact name, from list_workspaces. Without it, the current workspace. 1 to 120 characters.