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.
Step 1: Create your Virlo account for free
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.
Terminalnpm install @anthropic-ai/claude-agent-sdk # or pip install claude-agent-sdkStep 3: Set your Anthropic and Virlo keys
The SDK authenticates with
ANTHROPIC_API_KEY. Add a Virlo key from the developer dashboard asVIRLO_API_KEY. The SDK does not open a browser for MCP sign-in, so the header route is the one to use here.Terminalexport ANTHROPIC_API_KEY=sk-ant-... export VIRLO_API_KEY=virlo_tkn_YOUR_KEYStep 4: Register Virlo and allow its tools
Add Virlo under
mcpServerswithtype: 'http', the URL and an Authorization header, then listmcp__virlo__*inallowedTools. Without that wildcard the agent sees Virlo's tools but cannot call them.agent.tsimport { 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) } }Step 5: Run your first query
Run the file. Check the
systeminit message:virloshould reportconnected, and the agent's tool calls appear asmcp__virlo__...blocks.Your first promptFind 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?
| Route | Where it lives | Best for |
|---|---|---|
mcpServers in query() options | Your agent's source code | Agents you deploy, where config and code ship together |
.mcp.json at the project root | Loaded through the project setting source | Sharing 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 matches | Teaching the agent to rank by Virality Score and pick the right tool |
| Virlo CLI via the Bash tool | virlo trends digest --json run by the agent | Quick 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
| Task | Built-in tools only | With Virlo |
|---|---|---|
| Research a TikTok trend | WebSearch results about trends in general | Trends to copy with creator counts and example videos |
| Explain why a video worked | WebFetch of a page that hides the numbers | Hook, transcript, format and baseline comparison for that video |
| Write a sourced content plan | Plan based on model knowledge | Plan where every row links to a real outlier video |
| Monitor a competitor | A scraper you would have to build | Creator 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
| Sound | Artist | TikTok videos (7 days) | Usual week before |
|---|---|---|---|
original sound - Hani | Hani | 236 | 7 |
| ICKYSTICKY1.5 | MUTAYDOESNTGATEKEEP | 217 | 9 |
| original sound - thanks.forthemusic | por um propósito | 176 | 9 |
original sound | Raven | 178 | 21 |
oryginalny dźwięk | DavidBeSlime🌍 | 178 | 50 |
See all 300 breakout sounds on TikTok
Usage history and the TikTok videos behind every sound are in the Virlo app.
Open sounds in VirloHow 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.
| Form | Config |
|---|---|
| Python | import 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__*, plusReadandWriteso the agent can updateresearch/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 reportsneeds-authif the header is missing. - MCP tools need explicit permission: if the agent never calls Virlo, check that
mcp__virlo__*is inallowedTools. - 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.
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
- Mastra
- Vercel AI SDK


