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.

  1. Step 1: Create your Virlo account for free

    Create your free Virlo account in under a minute. Already signed up? Open API Keys.
  2. Step 2: Install the Mastra MCP package and add your key

    Install @mastra/mcp in the project, then put a key from the Virlo developer dashboard in .env as VIRLO_API_KEY.

    Terminal
    npm install @mastra/mcp@latest
  3. Step 3: Declare Virlo in an MCPClient

    Create an MCP client file with Virlo as a named server. The requestInit.headers field 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}` },
          },
        },
      },
    })
  4. Step 4: Give an agent the Virlo tools and register it

    Pass await virloMcp.listTools() as the agent's tools, then add the agent to new Mastra({ agents: { trendScout } }) in src/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(),
    })
  5. 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 prompt
    Use 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 patternWhat it does with VirloUse it when
tools: await virloMcp.listTools()Loads Virlo's research tools into the agent definition onceOne team, one Virlo key, a fixed agent
toolsets: await mcp.listToolsets()Passes Virlo tools at call time on generate or streamEach end user brings their own Virlo key
Workflow step calling the agentRuns the Virlo-equipped agent as one step in a typed workflowScheduled research that feeds later steps
createTool on the REST APIA Mastra tool that fetches https://api.virlo.ai/v1/content-trendsA 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

JobWithout VirloWith Virlo
Spot a rising formatNeeds a scraper you writeTrends to copy with the part to keep and the part to swap
Rank competitor videosNo access to view countsOutlier videos scored by how far they beat the creator's normal
Draft on-screen hooksModel-generated linesRewrites of real hooks tagged by type
Choose a Reels soundGuessworkSounds 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

Which Virlo tool would a Mastra agent call for each question?
Question your app asksTool it callsTop answer
Which format are most creators copying?get_content_trendsMy 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_hooksPOV setup: 32.9% reach a Virality Score of 18+
Which hook type wins most often on Instagram?search_hooksComparison: 19.0% reach a Virality Score of 18+
What is the second trend to copy?get_content_trendsWhile 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 free

How 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_KEY in .env locally 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.