OpenAI Agents SDK MCP: give your agents live TikTok and Instagram data

Updated

Virlo is social listening for TikTok and Instagram Reels. Agents written with the OpenAI Agents SDK can plan, hand off and call tools, yet no built-in OpenAI tool reports how TikTok and Instagram videos are performing this week. Give the agent Virlo as an MCP tool and it can pull trends to copy, hooks, sounds and outlier videos from a database of 23.1M viral videos. The OpenAI Agents SDK is OpenAI's open-source library for building agents with tools, handoffs, guardrails and tracing, in Python or TypeScript.

  • `HostedMCPTool`: OpenAI calls Virlo for you
  • `MCPServerStreamableHttp`: your process holds the connection
  • Same setup in Python and in TypeScript with `@openai/agents`

Part of Virlo's AI assistant guides. Want an agent inside ChatGPT instead of your own code? See ChatGPT agent. Coding with OpenAI's terminal agent? See Codex.

How do I add the Virlo MCP server to the OpenAI Agents SDK?

Six steps. Python and TypeScript each get a full example; use whichever language your agent runs 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 OpenAI Agents SDK

    In Python, the openai-agents package installs the agents module with the hosted MCP tool and the MCP server classes. In TypeScript, the same pieces ship in @openai/agents.

    Terminal
    pip install openai-agents
    # or
    npm install @openai/agents
  3. Step 3: Set both keys in your environment

    The SDK reads OPENAI_API_KEY for the model. Add a Virlo key from the developer dashboard beside it; Virlo keys start with virlo_tkn_.

    Terminal
    export OPENAI_API_KEY=sk-...
    export VIRLO_API_KEY=virlo_tkn_YOUR_KEY
  4. Step 4: Attach Virlo as a hosted MCP tool

    HostedMCPTool hands Virlo's address to the Responses API, which lists Virlo's research tools and calls them on OpenAI's side. Set require_approval to never for unattended runs, or leave approvals on while you test.

    agent.py
    import asyncio, os
    from agents import Agent, HostedMCPTool, Runner
    
    virlo = HostedMCPTool(tool_config={
        "type": "mcp",
        "server_label": "virlo",
        "server_url": "https://dev.virlo.ai/api/mcp/mcp",
        "headers": {"Authorization": f"Bearer {os.environ['VIRLO_API_KEY']}"},
        "require_approval": "never",
    })
    
    agent = Agent(
        name="Trend researcher",
        instructions="Research TikTok and Instagram with Virlo. Cite a source video for every idea.",
        tools=[virlo],
    )
    
    async def main():
        result = await Runner.run(agent, "What are the top 3 trends to copy in [your niche] this week?")
        print(result.final_output)
    
    asyncio.run(main())
  5. Step 5: Or do it in TypeScript

    The TypeScript library exposes the hosted route as hostedMcpTool, with camelCase options and an optional headers record for the Virlo key. run() returns the final output once the agent is done.

    agent.ts
    import { Agent, run, hostedMcpTool } from '@openai/agents'
    
    const agent = new Agent({
      name: 'Trend researcher',
      instructions: 'Research TikTok and Instagram with Virlo. Link a source video for every idea.',
      tools: [
        hostedMcpTool({
          serverLabel: 'virlo',
          serverUrl: 'https://dev.virlo.ai/api/mcp/mcp',
          headers: { Authorization: `Bearer ${process.env.VIRLO_API_KEY}` },
          requireApproval: 'never',
        }),
      ],
    })
    
    const result = await run(agent, 'Which Instagram Reels sounds are trending in [your niche] this week?')
    console.log(result.finalOutput)
  6. Step 6: Run the agent with a research question

    Run the script. The OpenAI traces dashboard shows each Virlo call the agent made, its arguments and the data that came back.

    Your first prompt
    Find the 10 TikTok videos about [topic] with the highest Virality Score this month and tell me which hook type they share.

Every agent you define can carry the Virlo tool, and handoffs let a research agent pass its findings to a writer agent that has no Virlo access of its own.

HostedMCPTool vs MCPServerStreamableHttp: which Agents SDK route should I use?

RouteWhere the Virlo connection livesCodeBest for
HostedMCPToolOn OpenAI's servers, through the Responses APItools=[HostedMCPTool(tool_config={...})]Short scripts and serverless jobs with no long-lived connection
MCPServerStreamableHttpIn your own processmcp_servers=[MCPServerStreamableHttp(...)] inside async withApps that log, filter or cache every Virlo call
hostedMcpTool() in TypeScriptOn OpenAI's servershostedMcpTool({ serverLabel: 'virlo', serverUrl, headers }) from @openai/agentsNode backends
MCPServerStreamableHttp in TypeScriptIn your own Node processnew MCPServerStreamableHttp({ url, name, requestInit }) with connect() and close()Node services that need per-request control

All four reach the same Virlo server and the same research tools. The difference is only who holds the connection.

OpenAI agent on its own vs with Virlo

What you ask the agentWithout VirloWith Virlo
Which TikTok formats are taking off?Web search results about trends in generalTrends to copy with creators this week and an example video each
Write hooks for our launchHooks invented by the modelHooks adapted from real openers on videos that beat their usual views
How is @[competitor] doing on Instagram?No direct way to checkTheir recent Reels with the ones that broke out flagged
Pick a sound for this ReelPopular songs it remembersSounds trending on Instagram Reels over the last 7 days

What would an OpenAI agent see when it asks Virlo for trends?

The first call most OpenAI agents make is the trends lookup. These cards are the live answer: each trend with how many creators posted it this week.

In Virlo's data, 659 creators posted "My moon my man couple montage" in the last 7 days, the most of any trend to copy as of November 19, 2026.

As of November 19, 2026 at 13:07 UTC

  1. Example video for the My moon my man couple montage trend by @haleyybaylee

    1. My moon my man couple montage

    Fresh · 659 creators this week

  2. Example video for the While they're out partying btw trend by @larpniverse

    2. While they're out partying btw

    Rising · 346 creators this week

  3. Example video for the He wanna pay full price SNL trend trend by @anereslaila1

    3. He wanna pay full price SNL trend

    Fresh · 175 creators this week

  4. Example video for the But you're not a Buddhist trend trend by @nicolo.contrada

    4. But you're not a Buddhist trend

    Fresh · 158 creators this week

  5. Example video for the Shoulder carry mirror selfie trend trend by @thecapcutterx

    5. Shoulder carry mirror selfie trend

    Fresh · 158 creators this week

What would an OpenAI agent see when it asks Virlo for trends?
TrendStageCreators this weekCreators last week
My moon my man couple montageFresh659new this week
While they're out partying btwRising346115
He wanna pay full price SNL trendFresh175new this week
But you're not a Buddhist trendFresh15833
Shoulder carry mirror selfie trendFresh158new this week

See all 39 trends to copy

Recipes, 30-day charts, client fit and every example video are in the Virlo app.

Open Trends to copy

How this sample is made

Source
Virlo's Trends to copy: formats found by Virlo's trend detector and published only after the team checks each one.
Window
Creators who posted each trend in the last 7 days, counted from TikTok and Instagram videos only. Trends made with an AI tool are left out.
Method
Ranked by creators posting this week. Stages: Fresh, Rising, Peaking, Fading.
As of
November 19, 2026 at 13:07 UTC. Refreshes every hour.
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, “OpenAI Agents SDK MCP: give your agents live TikTok and Instagram data”, virlo.ai/openai-agents-sdk

How do I move an Agent Builder workflow with Virlo to the Agents SDK?

OpenAI has scheduled its Agent Builder canvas to shut down on 30 November 2026 and recommends the Agents SDK for workflows that should keep running as code. Moving a Virlo-powered workflow takes a few minutes:

  • Open the workflow in Agent Builder and click Code to copy the generated Agents SDK version.
  • Find the MCP node in the exported code; it becomes a hosted MCP tool or an MCP server entry.
  • Replace any inline token with a read from VIRLO_API_KEY so the key lives in your environment.
  • Run the exported agent once with a known question and compare its answer with the canvas preview.
  • Deploy it where your other services run, or keep serving it in a chat window through ChatKit.

Nothing changes on the Virlo side during the move: same server URL, same key, same research tools.

When should I keep the Virlo connection in my own process?

MCPServerStreamableHttp opens the connection from your code instead of OpenAI's. Choose it when you want to log every Virlo request, filter which tools the agent can see, or cache the tool list between runs. The connection is managed by the async with block, so it closes cleanly when the run ends.

Python example: from agents import Agent, Runner from agents.mcp import MCPServerStreamableHttp async with MCPServerStreamableHttp( name="virlo", params={ "url": "https://dev.virlo.ai/api/mcp/mcp", "headers": {"Authorization": f"Bearer {os.environ['VIRLO_API_KEY']}"}, }, ) as virlo: agent = Agent(name="Trend researcher", mcp_servers=[virlo]) result = await Runner.run(agent, "...")

What can an OpenAI agent research with Virlo?

Pass these to Runner.run in Python or run() in TypeScript. Replace the brackets.

  • Weekly trend brief

    List the 5 trends to copy with the most creators in [your niche] this week, with what to keep, what to swap and one example video each.

  • Handoff to a writer

    Research the top 3 outlier TikTok videos about [topic], then hand off to the copywriter agent to draft one script per video for [your brand].

  • Guardrailed creator check

    Look up @[creator] on TikTok and Instagram and report how often their videos beat their usual views. Refuse if the handle is not found.

  • Sound picker

    Which sounds are breaking out on TikTok this week? Return three that suit a [tone] product video, with the number of videos using each.

  • Hook swipe file

    Collect 15 spoken hooks from videos in [your niche] scoring 18 or more on Virality Score and group them by hook type.

  • Transcript rebuild

    Get the transcript of [TikTok link] and rebuild it as a 30-second script for [your product] with the same beats.

  • Structured output

    Return the trending Instagram Reels sounds as JSON with title, artist and Reels in the last 7 days, matching my output schema.

  • ChatKit assistant

    You answer questions from our content team. For every question about TikTok or Instagram, use Virlo first and link the videos you used.

OpenAI Agents SDK vs Agent Builder vs ChatGPT agent vs Codex: which OpenAI product is this?

OpenAI uses the word agent for several products. This page covers the developer library you build your own agent with.

OpenAI Agents SDK (this page)

The Python and TypeScript library for building, running and tracing your own agents. Virlo attaches as an MCP tool.

Agent Builder

The visual AgentKit canvas whose Code button exports workflows as Agents SDK code. The move section above shows how to carry a Virlo workflow over.

ChatGPT agent

The agent mode inside ChatGPT that browses and completes tasks for you. It uses Virlo through ChatGPT's apps, not through code.

OpenAI Codex

OpenAI's coding agent for the terminal and IDE. Add Virlo with codex mcp add.

ChatGPT

The chat assistant, where Virlo is added as an app in developer mode.

What are the limits?

  • Virlo only reads public TikTok and Instagram data. Your OpenAI agent can analyse and write with it, but it cannot post or sign in to accounts.
  • With HostedMCPTool, OpenAI holds the connection, so the Virlo key travels in the tool config; keep it in an environment variable, never in source.
  • With MCPServerStreamableHttp, restart or reconnect the server object to pick up new Virlo tools after a release; the hosted route discovers them on each run.
  • Trends to copy refresh every hour after a team check; sounds and outliers update through the day.
  • For what each Virlo plan includes, see pricing.

Frequently asked questions

How do I add an MCP server to the OpenAI Agents SDK?

Add a HostedMCPTool to the agent's tools with type mcp, a server_label, the server_url and any headers, or open an MCPServerStreamableHttp and pass it in mcp_servers. For Virlo, use the dev.virlo.ai MCP URL and an Authorization bearer header carrying your key, then call Runner.run.

Does the OpenAI Agents SDK support MCP?

Yes. The Agents SDK offers HostedMCPTool, which lets the Responses API call a remote server for you, and MCPServerStreamableHttp, which connects from your own process. Both accept an Authorization header, which is all Virlo needs. The TypeScript library, @openai/agents, offers the same two routes as hostedMcpTool and MCPServerStreamableHttp, so a team can mix languages without changing the Virlo side.

What is HostedMCPTool in the OpenAI Agents SDK?

A tool you add to an Agent with a tool_config naming the server: type mcp, a server_label, the server_url, optional headers and an approval policy. OpenAI then lists and calls that server's tools during the run, so your code holds no open connection.

How do I move an OpenAI Agent Builder workflow with Virlo to the Agents SDK?

Open the workflow, click Code and copy the generated Agents SDK version. Its MCP node becomes a hosted MCP tool; swap any inline token for a read from VIRLO_API_KEY, run it once against a known question and deploy it beside your other services. The Virlo URL, key and tools stay the same.

What is AgentKit from OpenAI?

AgentKit is OpenAI's set of tools for building and shipping agents: the Agent Builder canvas, ChatKit for embedding chat interfaces, and connections to the Agents SDK. Virlo connects to the code side of it as a remote MCP server, and an SDK agent built with Virlo can sit behind a ChatKit chat window for your team.

Can an OpenAI agent get TikTok data?

With Virlo attached, yes. The agent can request TikTok trends to copy, outlier videos ranked by Virality Score, trending and breakout sounds, hashtags, creator lookups and full transcripts, then use them in later steps or handoffs. A research agent can pass its findings to a copywriting agent, which never needs its own Virlo access.

How do I use Virlo with the OpenAI Agents SDK in TypeScript?

Install @openai/agents and add hostedMcpTool with serverLabel virlo, serverUrl set to the Virlo MCP address, and an Authorization header. For a connection from your own process, use MCPServerStreamableHttp with the same URL, pass the header through requestInit, and call connect before the run and close in a finally block afterwards.

Can an OpenAI agent post to Instagram through Virlo?

No. Virlo is read-only research on public TikTok and Instagram data, so the agent can rank, compare and write but never publish or comment. Pair it with whatever publishing service your team already uses, and keep a human approval step between the agent's draft and anything that goes live.

Is this the same as using Virlo in ChatGPT agent mode?

No. ChatGPT agent runs inside ChatGPT and reaches Virlo through apps you add there. The Agents SDK is for agents you build and host yourself, with your own code deciding when Virlo is called. The ChatGPT agent guide covers the in-app route for people who never touch code.

Give your OpenAI agent a social media brain

One HostedMCPTool entry connects Virlo to every agent you build with the Agents SDK.