Mastra MCP: give Mastra agents live TikTok and Instagram data
Updated
Virlo is social listening for TikTok and Instagram Reels. A Mastra agent can call tools, keep memory and run inside workflows, but none of its built-in integrations measure how TikTok or Instagram videos are doing this week. Register Virlo in an MCPClient and the agent can fetch trends to copy, sounds, hooks and outlier videos from a database of 23.1M viral videos. Mastra is an open-source TypeScript framework for building AI agents, workflows and RAG pipelines, with a local Studio for testing them.
- `MCPClient` with Virlo as one named server
- Static `listTools()` or per-user `listToolsets()`
- Test calls in Mastra Studio before you ship
Part of Virlo's AI assistant guides. Building on the AI SDK directly? See the Vercel AI SDK guide. Writing Python instead? See LangChain.
How do I connect the Virlo MCP server to a Mastra agent?
Five steps in a Mastra project. You declare Virlo once in an MCP client file and import its tools into any agent.
Step 1: Create your Virlo account for free
Step 2: Install the Mastra MCP package and add your key
Install
@mastra/mcpin the project, then put a key from the Virlo developer dashboard in.envasVIRLO_API_KEY.Terminalnpm install @mastra/mcp@latestStep 3: Declare Virlo in an MCPClient
Create an MCP client file with Virlo as a named server. The
requestInit.headersfield sends your bearer key with every request to Virlo.src/mastra/mcp.ts// src/mastra/mcp.ts import { MCPClient } from '@mastra/mcp' export const virloMcp = new MCPClient({ servers: { virlo: { url: new URL('https://dev.virlo.ai/api/mcp/mcp'), requestInit: { headers: { Authorization: `Bearer ${process.env.VIRLO_API_KEY}` }, }, }, }, })Step 4: Give an agent the Virlo tools and register it
Pass
await virloMcp.listTools()as the agent's tools, then add the agent tonew Mastra({ agents: { trendScout } })insrc/mastra/index.ts. Use any model string your project already supports.src/mastra/agents/trend-scout.ts// src/mastra/agents/trend-scout.ts import { Agent } from '@mastra/core/agent' import { virloMcp } from '../mcp' export const trendScout = new Agent({ id: 'trend-scout', name: 'Trend Scout', instructions: 'Research TikTok and Instagram with Virlo and link a source video for every idea.', model: 'openai/gpt-6.1-sol', tools: await virloMcp.listTools(), })Step 5: Chat with it in Mastra Studio
Run the dev server, open Studio in your browser and pick Trend Scout. Each Virlo tool call shows up in the trace with its input and output.
Your first promptUse Virlo to list the breakout TikTok sounds this week that suit a [tone] video for [your brand], with how many videos used each one.
From your app code, call mastra.getAgentById('trend-scout').generate(...) with the same question, or stream it to a chat UI.
listTools vs listToolsets vs a workflow step: how should Mastra use Virlo?
| Mastra pattern | What it does with Virlo | Use it when |
|---|---|---|
tools: await virloMcp.listTools() | Loads Virlo's research tools into the agent definition once | One team, one Virlo key, a fixed agent |
toolsets: await mcp.listToolsets() | Passes Virlo tools at call time on generate or stream | Each end user brings their own Virlo key |
| Workflow step calling the agent | Runs the Virlo-equipped agent as one step in a typed workflow | Scheduled research that feeds later steps |
createTool on the REST API | A Mastra tool that fetches https://api.virlo.ai/v1/content-trends | A single fixed lookup with your own schema |
All four use the same Virlo server and key format; pick by how many people share the agent and how fixed the data needs are.
Mastra agent on its own vs with Virlo
| Job | Without Virlo | With Virlo |
|---|---|---|
| Spot a rising format | Needs a scraper you write | Trends to copy with the part to keep and the part to swap |
| Rank competitor videos | No access to view counts | Outlier videos scored by how far they beat the creator's normal |
| Draft on-screen hooks | Model-generated lines | Rewrites of real hooks tagged by type |
| Choose a Reels sound | Guesswork | Sounds rising on Instagram Reels this week |
Which Virlo tool would a Mastra agent call for each question?
Here is the mapping a Mastra agent works through, with today's live answer beside each tool. Studio traces show the same tool names.
In Virlo's data, 659 creators posted the "My moon my man couple montage" trend in the last 7 days, the top answer the trends tool gives as of November 19, 2026.
As of November 19, 2026 at 13:07 UTC
| Question your app asks | Tool it calls | Top answer |
|---|---|---|
| Which format are most creators copying? | get_content_trends | My moon my man couple montage: 659 creators this week |
| Which sound is trending on Instagram Reels? | get_trending_sounds | "Flower In A Hurricane (feat. Tame Impala, SZA, King Gizzard & the Lizard Wizard) [From GTAVI: Original Score]": 75 Reels in 7 days |
| Which hook type wins most often on TikTok? | search_hooks | POV setup: 32.9% reach a Virality Score of 18+ |
| Which hook type wins most often on Instagram? | search_hooks | Comparison: 19.0% reach a Virality Score of 18+ |
| What is the second trend to copy? | get_content_trends | While they're out partying btw: 346 creators this week |
Every answer, not just the top one
Connect the server and the same tools return the full lists, filters and history.
Start for freeHow this sample is made
- Source
- Virlo's Trends to copy, Instagram sound rankings and daily hook snapshot: the same data the MCP tools read.
- Window
- Trends: creators in the last 7 days. Sounds: Reels in the last 7 days. Hooks: all hook-tagged videos in the latest snapshot. TikTok and Instagram only.
- Method
- Each row is the top item for that question, from the data the named tool reads.
- As of
- Trends November 19, 2026 at 13:07 UTC; sounds November 19, 2026 at 12:03 UTC; hooks November 19, 2026.
- Made by
- Numbers are pulled automatically from Virlo's data every hour; the text around them is written by the Virlo team.
Suggested citation: Source: Virlo, “Mastra MCP: give Mastra agents live TikTok and Instagram data”, virlo.ai/mastra
How do I run a scheduled Virlo research workflow in Mastra?
Mastra workflows give you typed steps around the agent. A weekly research workflow for marketers:
- Step 1: an input schema with [your niche] and the platforms to cover.
- Step 2: the Trend Scout agent asks Virlo for trends to copy and the week's outlier videos.
- Step 3: a second call for breakout sounds on TikTok and Instagram Reels.
- Step 4: a writer agent with no tools turns the data into three short scripts, each citing its source.
- Step 5: a final step sends the result to your team chat or stores it, triggered by your scheduler of choice.
Keeping research and writing in separate agents means the writer can only use ideas the scout actually found.
How do per-user Virlo keys work in a Mastra app?
If your product lets each customer connect their own Virlo account, build an MCPClient per request with that user's key in requestInit.headers, then pass await mcp.listToolsets() as toolsets on the generate or stream call. The agent definition stays shared while the credentials change per call.
Disconnect the per-request client when the call ends so connections do not pile up on a busy server.
Virlo also supports OAuth 2.1 with dynamic client registration, so a product built on Mastra can let each customer sign in to Virlo and store the resulting token as that user's credential instead of asking them to paste a key.
What can a Mastra agent research with Virlo?
Send these in Studio or through agent.generate(). Replace the brackets.
Trend scan
Use Virlo to list this week's top 5 trends to copy in [your niche], each with its stage and an example video.
Outlier pull
Find 20 TikTok videos about [topic] from the last 30 days with a Virality Score of 18 or more and return them as JSON.
Hook rewrite
Collect 10 hooks from top Instagram Reels in [your niche] and rewrite each for [your offer], keeping the hook type.
Creator lookup
Look up @[creator] on TikTok and list the three videos that beat their usual views by the widest margin.
Sound match
Pick the two Instagram Reels sounds trending this week that best fit a [tone] video and explain why.
Memory-aware recap
Compare this week's trends in [your niche] with what you told me last week and highlight anything new.
Transcript outline
Get the transcript of [TikTok link] and outline it as hook, setup, payoff and call to action for a [your product] remake.
Workflow input
Return the three strongest trends to copy in [your niche] as JSON matching this schema: name, keep, swap, example_url. The next workflow step parses it.
Mastra vs Vercel AI SDK vs LangChain.js: which TypeScript guide fits?
All three run in TypeScript and can load Virlo. They sit at different levels.
Mastra (this page)
A full agent framework with agents, workflows, memory and a local Studio. Virlo enters through MCPClient from @mastra/mcp.
Vercel AI SDK
The lower-level toolkit for calling models and streaming to a UI. Virlo enters through createMCPClient.
LangChain
Agents and graphs in Python or TypeScript, with its own MCP adapters.
Mastra MCPServer
Mastra can also publish your own tools as an MCP server for other clients. That is the opposite direction and is not needed for Virlo.
What are the limits?
- Virlo is a read-only source of public TikTok and Instagram data; a Mastra agent cannot post, comment or log in through it.
- Keep
VIRLO_API_KEYin.envlocally and in your host's secrets in production; never inline it in the MCP client file. - Background jobs such as creating a marketing agent complete later, so let a workflow step check back instead of holding one generate call open.
- Trends to copy refresh each hour after a team check; hook-type rankings rebuild daily.
- For what each Virlo plan includes, see pricing.
Frequently asked questions
How do I add an MCP server to Mastra?
Install @mastra/mcp, create an MCPClient with the server under servers, and pass await client.listTools() as an agent's tools. For Virlo, set url to new URL with the dev.virlo.ai MCP address and add an Authorization bearer header in requestInit.headers. Register the agent in your Mastra instance and the tools appear in Studio straight away.
Does Mastra support remote MCP servers?
Yes. MCPClient connects to remote servers by URL over Streamable HTTP, and also to local command-based servers. Virlo is hosted, so only the URL and a header are needed, with nothing extra running next to your app. That keeps deployments on serverless hosts and containers equally simple.
What is the difference between listTools and listToolsets in Mastra?
listTools returns tools you bake into an agent definition, best when one key serves everyone. listToolsets returns tools grouped by server that you pass at call time, which suits apps where each user connects their own Virlo account. Both return the same Virlo tools; only the moment you attach them differs.
Can a Mastra agent research TikTok?
With Virlo connected, yes. The agent can pull TikTok trends to copy, outlier videos ranked by Virality Score, trending and breakout sounds, hashtags, creator lookups and transcripts, and it keeps that context in memory for follow-up questions. Ask about a trend, then its top creator, and the agent connects the two without being reminded.
Can I test Virlo tools in Mastra Studio?
Yes. Start the Mastra dev server, open Studio and choose the agent that holds the Virlo tools. Chat with it and open the trace to see each tool call, its arguments and the data Virlo returned. Studio is the quickest way to tune the agent's instructions before you wire it into your app.
Does Mastra work with Instagram data through Virlo?
Yes. A Mastra agent can rank Instagram Reels on a topic by Virality Score, list trending and breakout Reels sounds, read hook types and check a creator's recent videos. Full transcripts are available for TikTok. Ask the agent to compare the two platforms and it will report where a format is stronger, using the same Virality Score scale on both.
Can a Mastra agent publish to TikTok with Virlo?
No. Virlo reads public data and never touches social accounts. Your agent can turn the research into scripts and plans, and publishing happens through your own tools. A workflow step can still hand the finished plan to a scheduler for a human to approve.
Should I use Mastra or the Vercel AI SDK for Virlo?
Use Mastra if you want agents, workflows and memory out of the box. Use the AI SDK if you only need a model call with tools in a route handler. The Virlo URL and key are the same either way, so moving between them is a small change. The Vercel AI SDK guide covers that setup.
Can a Mastra workflow start from a Virlo webhook?
Yes. Register a Virlo webhook for an event such as tracking.outlier_video.detected, point it at a route in your app, and start the Mastra workflow from that handler with the event payload as input. The workflow then runs the moment a tracked creator posts a breakout video.
Give your Mastra agents a social media brain
One MCPClient entry connects Virlo to every agent and workflow in your project.
More AI assistant guides
- AI assistant guides
- Claude
- Claude Code
- Cursor
- MCP server
- TikTok MCP server
- Instagram MCP server
- ChatGPT
- ChatGPT dots
- OpenAI Codex
- Gemini CLI
- Grok Build
- Claude Cowork
- n8n
- Zapier
- Grok Bot
- Muse
- Claude Duet
- Hermes Agent
- Kimi K3
- Cue
- Manus
- Perplexity Computer
- Paperclip
- OpenClaw
- NanoClaw
- DeepSeek
- AI agents CLI
- ChatGPT agent
- Perplexity
- Microsoft Copilot
- Le Chat
- Notion
- Slack
- Discord
- Telegram
- Google Sheets
- Windsurf
- VS Code
- GitHub Copilot
- Cline
- JetBrains
- Kiro
- Google Antigravity
- goose
- Warp
- OpenCode
- Zed
- Amp
- Factory Droid
- Raycast
- Lovable
- Replit
- Bolt.new
- v0
- Ollama
- LM Studio
- Open WebUI
- LibreChat
- Make
- Pipedream
- Gumloop
- Lindy
- Relevance AI
- Airtable
- ClickUp
- Dify
- Flowise
- LangChain
- CrewAI
- OpenAI Agents SDK
- Vercel AI SDK
- Claude Agent SDK