Connection guide
Connect your AI client
Use a client that supports remote MCP over Streamable HTTP and OAuth browser sign-in. Access requires an active Viraldi workspace; it is free during beta.
Connect with browser sign-in
Add a remote MCP server in your client
Choose a name such as Viraldi and paste this address. Client menus and configuration formats vary.
Sign in and review the request
Your client opens Viraldi in a browser. Check the app name, return address and requested permissions before allowing the connection. App names are provided by their developers; only connect apps you recognize.
Choose any available sign-in method on the normal Viraldi sign-in page. After signing in, you’ll return automatically to review your AI client’s access.
Try a research question
Find recent cooking Shorts with an outlier score of at least 5×. Compare their opening words where transcripts are available, and include links to the source videos.
If the client asks you to enable tools, enable the Viraldi tools you want to use.
Client compatibility
Use a desktop or server-based client that supports remote Streamable HTTP and OAuth. Third-party browser-only clients that send cross-origin requests are not supported. Viraldi does not provide a persistent event stream or a legacy SSE endpoint.
Client configuration formats differ. Follow your client’s remote-server instructions; a generic JSON snippet is not a guarantee that a particular app supports this connection.
What your connection can read
| Tool | Permission | Result |
|---|---|---|
search_outliers | outliers:read | Current and retained outliers, with topic and format filters. |
search_trending | videos:read | List or search chart discoveries by country, topic, tags, format, language and publication age. Sort by newest or views and paginate results. |
get_video | videos:read | Public details and metrics for Trending discoveries and eligible current or retained outliers. Baselines are included where available. |
search_channels, get_channel | videos:read | Public creator directory, topic summaries, outlier counts and best scores. Filter video searches by exact channel ID. |
search_topics, get_topic | videos:read | Full public topic tree, descriptions, alternative names and category paths. |
get_related_videos | videos:read | Breakout examples from other creators, matching the video page. |
get_methodology | videos:read | Public scoring, ranking, measurement and retention rules. |
list_saved_videos, list_followed_channels | library:read · optional | Your account's saved collection and channel watchlist. Unavailable items are labelled honestly. |
get_workspace | workspace:read · optional | Your connection's workspace details, seat limit, member identities and email addresses. |
get_transcript | transcripts:read | An available cached transcript with timestamps, or its availability state. |
get_advanced_analytics | analytics:read | Available growth observations and transcript evidence for eligible outlier Shorts. This permission includes transcript text. |
For Trending, ask for videos discovered in a country, such as cooking videos in Mexico published within the last seven days. The response includes available country codes and topic names for follow-up filters. Country marks record the first observed chart discovery, not the current YouTube chart rank. Publication age and observation dates are different; missing metrics remain unavailable.
MCP only reads existing research; it does not queue transcription. To request a missing transcript, open the video on Viraldi. Transcript availability depends on video eligibility and source material. Detailed analytics cover eligible outlier Shorts up to three minutes, including retained evidence where available.
Analytics describe observed metrics and text patterns. They do not inspect visual frames, measure retention or establish what caused a video’s performance. Missing measurements remain unavailable.
Optional personal data
Saved videos, watchlist and workspace information use separate permissions. Requested personal-data checkboxes start unchecked when you connect. Leave them off to use research tools without sharing those categories.
In Account → MCP access → Optional AI data access, you can disable either category for all AI clients. This revokes connections that already had its permission, including their other permissions; other connections continue to work. Turning sharing on again requires a fresh connection or token and explicit approval. Allowing apps to request a category does not itself share any data.
Guest saves stored only in your browser cannot be read through MCP. Account settings, passwords, payments and internal operations are outside these tools.
Manage access
Review and revoke connections in Account → MCP access. Revoking a connection stops its access and token renewal.
If your client requests offline_access, it can stay connected after you sign out of the website. Access tokens last one hour and refresh tokens rotate with a 30-day lifetime. Without offline access, the connection remains tied to the browser session. Reconnect if your client can no longer renew its access.
Advanced: personal access tokens
Use a personal token only when your client supports bearer authentication but cannot complete browser sign-in. In Account → MCP access, open “Personal access tokens”, select only the permissions you need, and choose an expiry. Copy the token when it is created; it is shown only once.
Configure your client to send the token in the Authorization: Bearer <token> header. Keep it in your client’s secret storage. Never put it in the server URL, a prompt, a screenshot or a shared configuration file. Revoke it if exposed.
Limits and troubleshooting
Each user can have up to 10 active connections and personal tokens combined. They share 120 protocol requests per minute and 10,000 per UTC day. Creating personal tokens is limited to 30 per day. Search returns up to 100 results per call, with offsets up to 10,000; requests are limited to 32 KiB and one JSON-RPC message each (no batch arrays).
- The browser does not open for sign-in
- Check that your client supports remote Streamable HTTP and OAuth, and that the server address ends in
/mcp. Restart the connection from the client. The server address is a protocol endpoint, not a web page. - The connection was denied or expired
- Reconnect from your client and approve the permissions you need. A removed workspace membership or unavailable research access also prevents tool calls. Check your workspace in Account.
- A tool reports insufficient scope
- Reconnect with that tool’s permission, or create a personal token with the required permission. Analytics access includes transcript evidence.
- A video or transcript is unavailable
- The video may no longer meet the public catalog’s eligibility rules, or its transcript may be missing, pending, skipped or failed. Search Trending or outliers again for available examples. Request eligible missing transcripts on the website.
- You reached a usage limit
- Wait before retrying and reduce repeated calls. A per-minute limit normally clears after a minute; a daily limit clears at the next UTC day.