Claude Agent SDK MCP: build agents on live TikTok and Instagram data

Updated

Virlo is social listening for TikTok and Instagram Reels. An agent built on the Claude Agent SDK can read files, run commands and call tools, but it has no window into how TikTok and Instagram videos are performing this week. Add Virlo under mcpServers and allow its tools, and the agent can pull trends to copy, hooks, sounds, transcripts and outlier videos from a database of 23.1M viral videos. The Claude Agent SDK is Anthropic's TypeScript and Python library that exposes the Claude Code agent loop, tools and context management for building your own agents.

  • `mcpServers.virlo` with `type: 'http'` and a bearer header
  • `allowedTools: ['mcp__virlo__*']` approves only Virlo
  • Same config from code or from a project `.mcp.json`

Part of Virlo's AI assistant guides. Using Claude interactively in the terminal? See Claude Code. Running a lightweight Claude agent in containers? See NanoClaw.

How do I add the Virlo MCP server to the Claude Agent SDK?

Five steps. The TypeScript and Python SDKs take the same server shape, so pick whichever language your agent is written in.

  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 SDK

    Use the npm package for TypeScript or the PyPI package for Python. Both bundle the agent loop the SDK runs.

    Terminal
    npm install @anthropic-ai/claude-agent-sdk
    # or
    pip install claude-agent-sdk
  3. Step 3: Set your Anthropic and Virlo keys

    The SDK authenticates with ANTHROPIC_API_KEY. Add a Virlo key from the developer dashboard as VIRLO_API_KEY. The SDK does not open a browser for MCP sign-in, so the header route is the one to use here.

    Terminal
    export ANTHROPIC_API_KEY=sk-ant-...
    export VIRLO_API_KEY=virlo_tkn_YOUR_KEY
  4. Step 4: Register Virlo and allow its tools

    Add Virlo under mcpServers with type: 'http', the URL and an Authorization header, then list mcp__virlo__* in allowedTools. Without that wildcard the agent sees Virlo's tools but cannot call them.

    agent.ts
    import { query } from '@anthropic-ai/claude-agent-sdk'
    
    for await (const message of query({
      prompt: "Use Virlo to list this week's top 5 trends to copy in [your niche].",
      options: {
        mcpServers: {
          virlo: {
            type: 'http',
            url: 'https://dev.virlo.ai/api/mcp/mcp',
            headers: { Authorization: `Bearer ${process.env.VIRLO_API_KEY}` },
          },
        },
        allowedTools: ['mcp__virlo__*'],
      },
    })) {
      if (message.type === 'result' && message.subtype === 'success') {
        console.log(message.result)
      }
    }
  5. Step 5: Run your first query

    Run the file. Check the system init message: virlo should report connected, and the agent's tool calls appear as mcp__virlo__... blocks.

    Your first prompt
    Find the TikTok sounds breaking out this week in [your niche], then write a 30-second script for [your product] that uses the strongest one.

Prefer Python? The same server goes in ClaudeAgentOptions(mcp_servers=..., allowed_tools=[...]); the full snippet is in the section below.

In code vs .mcp.json vs the Virlo skill: how should a Claude Agent SDK agent load Virlo?

RouteWhere it livesBest for
mcpServers in query() optionsYour agent's source codeAgents you deploy, where config and code ship together
.mcp.json at the project rootLoaded through the project setting sourceSharing one Virlo config between the SDK agent and Claude Code in the same repo
Virlo skill (virlo skill install --dir)A SKILL.md the agent reads when the task matchesTeaching the agent to rank by Virality Score and pick the right tool
Virlo CLI via the Bash toolvirlo trends digest --json run by the agentQuick scripts where an MCP server is not wanted

Whichever route loads Virlo, allowedTools still decides whether the agent may call it. Use the mcp__virlo__* wildcard rather than a permission mode that approves everything.

Claude Agent SDK agent on its own vs with Virlo

TaskBuilt-in tools onlyWith Virlo
Research a TikTok trendWebSearch results about trends in generalTrends to copy with creator counts and example videos
Explain why a video workedWebFetch of a page that hides the numbersHook, transcript, format and baseline comparison for that video
Write a sourced content planPlan based on model knowledgePlan where every row links to a real outlier video
Monitor a competitorA scraper you would have to buildCreator lookups with outlier videos on each run

Which TikTok sounds would a Claude Agent SDK agent flag as breaking out?

Ask the agent for breakout audio and the Virlo sounds tool returns rows like these: TikTok sounds climbing fast from a small base this week, pulled live.

In Virlo's data, "original sound - Hani" is the fastest-rising sound on TikTok: 236 TikTok videos used it in the last 7 days, against about 7 a week before, as of November 19, 2026.

As of November 19, 2026 at 12:03 UTC

Which TikTok sounds would a Claude Agent SDK agent flag as breaking out?
SoundArtistTikTok videos (7 days)Usual week before
Cover art for original sound - Hanioriginal sound - HaniHani2367
ICKYSTICKY1.5MUTAYDOESNTGATEKEEP2179
original sound - thanks.forthemusicpor um propósito1769
Cover art for original soundoriginal soundRaven17821
Cover art for oryginalny dźwiękoryginalny dźwiękDavidBeSlime🌍17850

See all 300 breakout sounds on TikTok

Usage history and the TikTok videos behind every sound are in the Virlo app.

Open sounds in Virlo

How this sample is made

Source
Virlo's sound rankings for TikTok, built from the TikTok videos Virlo collects.
Window
TikTok videos posted in the last 7 days that Virlo collected. Counts are TikTok videos in Virlo's data, not every video on the platform.
Method
Ranked by breakout score: use in the last 7 days against the sound's usual weekly use before that, so a sound rising from a small base ranks above an old hit.
As of
November 19, 2026 at 12:03 UTC. Rebuilt every day.
Made by
Numbers are pulled automatically from Virlo's data; the text around them is written by the Virlo team.

Suggested citation: Source: Virlo, “Claude Agent SDK MCP: build agents on live TikTok and Instagram data”, virlo.ai/claude-agent-sdk

What does the Python and .mcp.json setup look like?

The Python SDK takes the same keys with snake_case names. Put the server in mcp_servers, approve it in allowed_tools, and iterate over query() for messages.

To share one config between your SDK agent and Claude Code in the same repository, put Virlo in .mcp.json at the project root. The SDK loads it when the project setting source is on, which it is with default options; the ${VIRLO_API_KEY} syntax expands from the environment at run time.

Virlo for the Claude Agent SDK, by language
FormConfig
Pythonimport asyncio, os from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage options = ClaudeAgentOptions( mcp_servers={ "virlo": { "type": "http", "url": "https://dev.virlo.ai/api/mcp/mcp", "headers": {"Authorization": f"Bearer {os.environ['VIRLO_API_KEY']}"}, } }, allowed_tools=["mcp__virlo__*"], ) async def main(): async for message in query(prompt="Which TikTok sounds are breaking out this week?", options=options): if isinstance(message, ResultMessage) and message.subtype == "success": print(message.result) asyncio.run(main())
.mcp.json{ "mcpServers": { "virlo": { "type": "http", "url": "https://dev.virlo.ai/api/mcp/mcp", "headers": { "Authorization": "Bearer ${VIRLO_API_KEY}" } } } }

How do I build a weekly research agent with the Claude Agent SDK?

The SDK agent can read and write files, so it can keep its own research log. A layout that works for marketers:

  • A system prompt that names [your niche], the platforms, and the rule that every idea links to a source video.
  • Virlo allowed through mcp__virlo__*, plus Read and Write so the agent can update research/week.md.
  • A first turn that asks for trends to copy, outlier videos and breakout sounds, written to the file as tables.
  • A second turn that compares this week's file with last week's and lists what is new.
  • A cron job or CI schedule that runs the script every Monday and commits the updated file.

Add a subagent for scripting if you want research and writing separated: the scripting subagent gets no Virlo tools, so it can only use what the research agent recorded.

What can a Claude Agent SDK agent do with Virlo?

Pass these as the prompt to query(). Replace the brackets.

  • Research file

    Use Virlo to pull this week's top 10 trends to copy in [your niche] and write them to research/trends.md as a table with an example link for each.

  • Outlier dataset

    Collect 50 TikTok videos about [topic] from the last 30 days with a Virality Score of 18 or more and save them to data/outliers.json.

  • Transcript to script

    Get the transcript of [TikTok link], then write scripts/remake.md: a 30-second version for [your product] with the same beats.

  • Competitor diff

    Look up @[competitor] on TikTok and Instagram, compare with notes/competitor.md from last week, and update the file with what changed.

  • Hook library

    Find 20 spoken hooks from top videos in [your niche], group them by hook type and append them to hooks/library.md.

  • Sound brief

    List the Instagram Reels sounds trending this week and recommend one for each of the three scripts in the scripts folder.

  • Creator outreach list

    Find 10 TikTok creators in [your niche] under [N] followers whose videos beat their follower count and write them to outreach.csv.

Claude Agent SDK vs Claude Code vs NanoClaw: which guide do I need?

All three run on the same Claude agent loop and all three can use Virlo. They differ in who drives the agent.

Claude Agent SDK (this page)

A library for building your own agent in TypeScript or Python. Virlo is passed in code through mcpServers.

Claude Code

Anthropic's interactive coding agent in the terminal and IDE. Add Virlo with claude mcp add or the Virlo plugin.

NanoClaw

A small open-source personal agent that runs Claude in containers and talks over chat apps. It has its own setup guide.

Claude apps

Claude on the web, desktop and phone, where Virlo is added as a connector rather than in code.

What are the limits?

  • Virlo is read-only research on public TikTok and Instagram data; an SDK agent cannot post, comment or log in to accounts through it.
  • The SDK does not run an interactive OAuth flow, so pass the Virlo key in headers; the server reports needs-auth if the header is missing.
  • MCP tools need explicit permission: if the agent never calls Virlo, check that mcp__virlo__* is in allowedTools.
  • Trends to copy refresh every hour after a team check; hook rankings rebuild daily.
  • For what each Virlo plan includes, see pricing.

Frequently asked questions

How do I add an MCP server to the Claude Agent SDK?

Pass it in the mcpServers option of query(), keyed by a name, then allow its tools in allowedTools. For Virlo: type http, the dev.virlo.ai MCP URL and an Authorization bearer header, with allowedTools set to mcp__virlo__*. Python uses mcp_servers and allowed_tools in ClaudeAgentOptions.

Why can my Claude Agent SDK agent see Virlo tools but not use them?

MCP tools need permission before the agent can call them. Add mcp__virlo__* to allowedTools. The acceptEdits permission mode does not cover MCP tools, and bypassing permissions approves far more than you need. The wildcard grants exactly the Virlo server and nothing else, which is the scoped choice for agents that run unattended.

Does the Claude Agent SDK support remote HTTP MCP servers?

Yes. Set type to http for Streamable HTTP servers, or sse for older ones, with a url and optional headers. Virlo is a hosted Streamable HTTP server, so type http with a bearer header is the full configuration. In .mcp.json and other JSON config files, streamable-http is accepted as an alias, but code should use http.

How does OAuth work for MCP in the Claude Agent SDK?

The SDK itself does not open a browser. Either pass a token in headers, which for Virlo is your API key, or complete OAuth in your own app and pass the resulting access token the same way. A server without credentials reports needs-auth.

Can a Claude Agent SDK agent research TikTok?

With Virlo allowed, yes. The agent can call tools for TikTok trends to copy, outlier videos ranked by Virality Score, trending and breakout sounds, hashtags, creator lookups and transcripts, and write the results to files in its working directory. That makes it easy to build up a research log that a later run, or a teammate, can read.

Can I reuse my Claude Code Virlo setup in the Agent SDK?

Yes, through .mcp.json. Put Virlo in that file at the project root and the SDK loads it with the project setting source, while Claude Code reads the same file. You still list mcp__virlo__* in allowedTools for the SDK agent. If you set settingSources yourself, include project, or the file is skipped.

How do I check that Virlo connected in the Claude Agent SDK?

Read the system init message at the start of the query. Its mcp_servers list shows a status for virlo: connected means it worked, needs-auth means the header is missing or wrong, and failed points to a network or URL problem. You can also poll the server status later in the session from the query object.

Can the agent post to TikTok through Virlo?

No. Virlo only reads public TikTok and Instagram data. The agent can research and write with it, and you publish with your own tools. Because the SDK agent can also write files, a common pattern is to save drafts to a folder that a person reviews before anything is posted.

Is the Claude Agent SDK the same as Claude Code?

They share the same agent loop. Claude Code is the interactive product you type into; the Agent SDK lets you run that loop from your own program. Both read .mcp.json, so one Virlo entry can serve both. The Claude Code guide covers the interactive setup.

Give your Claude agent a social media brain

One mcpServers entry and one allowedTools wildcard connect Virlo to any agent you build.