Skip to content

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-only

Search 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.

  • querystringrequired

    Plain keywords, e.g. "morning routine", "skincare", a creator name. No OR, AND or quotes; videos holding every word rank first. 2 to 200 characters.

  • limitinteger

    How many to return (1–25, default 10). Default 10.

list_videos

read-only

List 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.

  • nichestring

    The niche slug from its page URL ("fitness") or its plain name. Call list_niches if unsure. 1 to 120 characters.

  • formatstring

    The format slug from its page URL ("selfie-with-background") or its plain name. Call list_formats if unsure. 1 to 120 characters.

  • brandstring

    The brand slug from its page URL ("gauth") or its plain name. Call list_brands if unsure. 1 to 120 characters.

  • platformenum

    One of instagram, tiktok.

  • creatorstring

    Creator username, with or without @. 1 to 100 characters.

  • languagestring

    The video's language as a two-letter code, e.g. en, es, fr, pt.

  • visual_formatstring

    Only 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_tacticenum

    Only 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.

  • toneenum

    Only 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_triggerenum

    Only 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.

  • talentenum

    Only videos whose talent is this. Classified videos only; get_video returns available classification labels. One of none, creator, founder, customer, model.

  • awarenessenum

    Only 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_typeenum

    Only 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_typeenum

    One of video, photo.

  • creator_genderenum

    One of male, female.

  • daysinteger

    Only 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_factornumber

    Only videos with at least this viral factor, e.g. 4, 8, 32.

  • searchstring

    Plain 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_query says what was searched). 2 to 200 characters.

  • sortenum

    Order by viral factor (viral, default), view count (views), or posting date (recent, newest first). One of viral, views, recent. Default viral.

  • followedboolean

    true: 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.

  • workspacestring

    Optional: the workspace's id or exact name, from list_workspaces. Without it, the current workspace. 1 to 120 characters.

  • limitinteger

    How many to return (1–50, default 6). Default 6.

  • offsetinteger

    Number of results to skip. Use the preceding next_offset; null means no further page is available. Default 0.

get_video

read-only

Get 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)required

    The video id, as in its page URL /videos/<id>.

list_niches

read-only

List 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-only

List 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-only

List 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-only

Get 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.

  • brandstringrequired

    The brand slug from its page URL ("gauth") or its plain name. Call list_brands if unsure. 1 to 120 characters.

list_saved_videos

read-only

List 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.

  • limitinteger

    How many to return (1–100, default 20). Default 20.

  • offsetinteger

    Number of results to skip. Use the preceding next_offset; null means no further page is available. Default 0.

  • workspacestring

    Optional: the workspace's id or exact name, from list_workspaces. Without it, the current workspace. 1 to 120 characters.

list_followed_videos

read-only

List 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.

  • limitinteger

    How many to return (1–50, default 20). Default 20.

  • offsetinteger

    Number of results to skip. Use the preceding next_offset; null means no further page is available. Default 0.

  • workspacestring

    Optional: the workspace's id or exact name, from list_workspaces. Without it, the current workspace. 1 to 120 characters.

list_boards

read-only

List 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.

  • workspacestring

    Optional: the workspace's id or exact name, from list_workspaces. Without it, the current workspace. 1 to 120 characters.

list_workspaces

read-only

List 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-only

Switch 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.

  • workspacestringrequired

    The workspace's id or exact name, from list_workspaces: calls without workspace act there from now on. 1 to 120 characters.

get_usage

read-only

Check 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-only

Inspect 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_idstringrequired

    The video id from list_videos, search_library or get_video, or its Viral Swipe File page URL (/videos/<id>). 1 to 300 characters.

  • workspacestring

    Optional: the workspace's id or exact name, from list_workspaces. Without it, the current workspace. 1 to 120 characters.

save_video

changes your account

Save 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_idstringrequired

    The video id from list_videos, search_library or get_video, or its Viral Swipe File page URL (/videos/<id>). 1 to 300 characters.

  • workspacestring

    Optional: the workspace's id or exact name, from list_workspaces. Without it, the current workspace. 1 to 120 characters.

unsave_video

changes your account

Unsave 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_idstringrequired

    The video id from list_videos, search_library or get_video, or its Viral Swipe File page URL (/videos/<id>). 1 to 300 characters.

  • workspacestring

    Optional: the workspace's id or exact name, from list_workspaces. Without it, the current workspace. 1 to 120 characters.

set_video_note

changes your account

Write 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_idstringrequired

    The video id from list_videos, search_library or get_video, or its Viral Swipe File page URL (/videos/<id>). 1 to 300 characters.

  • notestringrequired

    The note, up to 500 characters; an empty string clears it.

  • boardstring

    Optional: 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.

  • workspacestring

    Optional: the workspace's id or exact name, from list_workspaces. Without it, the current workspace. 1 to 120 characters.

create_board

changes your account

Create 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.

  • namestringrequired

    The board's name, up to 60 characters. 1 to 60 characters.

  • video_idstring

    Optional: a library video to save and put on the new board (its id or page URL). 1 to 300 characters.

  • workspacestring

    Optional: the workspace's id or exact name, from list_workspaces. Without it, the current workspace. 1 to 120 characters.

rename_board

changes your account

Rename 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.

  • boardstringrequired

    The board's id or its exact name, from list_boards. 1 to 120 characters.

  • namestringrequired

    The board's name, up to 60 characters. 1 to 60 characters.

  • workspacestring

    Optional: the workspace's id or exact name, from list_workspaces. Without it, the current workspace. 1 to 120 characters.

delete_board

changes your account

Delete 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.

  • boardstringrequired

    The board's id or its exact name, from list_boards. 1 to 120 characters.

  • workspacestring

    Optional: the workspace's id or exact name, from list_workspaces. Without it, the current workspace. 1 to 120 characters.

share_board

changes your account

Share a board by link

Turn on a board's public share link and return it as share_url: anyone with the link sees the board, its videos and all board-specific notes without an account. Workspace save notes stay private. Explain this exposure and confirm with the user before sharing. A board already shared returns its current link unchanged. Needs a trial or a plan.

  • boardstringrequired

    The board's id or its exact name, from list_boards. 1 to 120 characters.

  • workspacestring

    Optional: the workspace's id or exact name, from list_workspaces. Without it, the current workspace. 1 to 120 characters.

unshare_board

changes your account

Turn off a board's share link

Turn off a board's share link: the old link stops working at once, and sharing it again later makes a new link. A board whose link is already off succeeds and changes nothing. Open on every plan; an owner or admin of the organization can also turn off a link in a locked workspace (name it as workspace).

  • boardstringrequired

    The board's id or its exact name, from list_boards. 1 to 120 characters.

  • workspacestring

    Optional: 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 account

Add 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.

  • boardstringrequired

    The board's id or its exact name, from list_boards. 1 to 120 characters.

  • video_idstringrequired

    The video id from list_videos, search_library or get_video, or its Viral Swipe File page URL (/videos/<id>). 1 to 300 characters.

  • workspacestring

    Optional: 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 account

Remove 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.

  • boardstringrequired

    The board's id or its exact name, from list_boards. 1 to 120 characters.

  • video_idstringrequired

    The video id from list_videos, search_library or get_video, or its Viral Swipe File page URL (/videos/<id>). 1 to 300 characters.

  • workspacestring

    Optional: the workspace's id or exact name, from list_workspaces. Without it, the current workspace. 1 to 120 characters.

follow_creator

changes your account

Follow 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.

  • creatorstringrequired

    The creator's TikTok or Instagram handle, with or without @ ("@creatorname"), as list_videos and search_library return it. 1 to 60 characters.

  • platformenum

    Optional: the creator's platform, when the handle is on both. One of tiktok, instagram.

  • workspacestring

    Optional: the workspace's id or exact name, from list_workspaces. Without it, the current workspace. 1 to 120 characters.

unfollow_creator

changes your account

Stop 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.

  • creatorstringrequired

    The creator's TikTok or Instagram handle, with or without @ ("@creatorname"), as list_videos and search_library return it. 1 to 60 characters.

  • platformenum

    Optional: the creator's platform, when the handle is on both. One of tiktok, instagram.

  • workspacestring

    Optional: the workspace's id or exact name, from list_workspaces. Without it, the current workspace. 1 to 120 characters.