# MCP server

> Connect Claude, Cursor, VS Code, Codex, Windsurf, or any other MCP app to Virlo. 65 tools for Content Research Agents, creator, video, sound and hashtag lookups, tracking, sounds, hooks, audience data, Topic Trends, Format Trends, and live raw data.

Source: https://dev.virlo.ai/docs/mcp
Markdown: https://dev.virlo.ai/docs/mcp.md
Section: For AI assistants

## About the Virlo API (applies to every page)

- Base URL: `https://api.virlo.ai/v1`. Every request needs the header `Authorization: Bearer YOUR_API_KEY` (keys start with `virlo_tkn_`).
- Responses are JSON inside a `data` field, except the `/v1/webhooks` endpoints, which return the object or array directly. Field names are snake_case.
- Prices are in US dollars from a prepaid balance. 1 credit = $0.01. The `X-Cost` response header on each successful response is the exact charge. Errors are free.
- Slow jobs return an ID. Check its status every 15 seconds (or whatever `retry_after_seconds` says) until `finalized` is `true`.
- All docs pages: https://dev.virlo.ai/llms.txt. Every page in one file: https://dev.virlo.ai/llms-full.txt. MCP server for AI assistants: https://dev.virlo.ai/api/mcp/mcp.

---

Let your AI assistant use Virlo for you. Ask Claude, Cursor, or another assistant to research a niche or find trending sounds, and it fetches the data itself.

**At a glance**

- **What it does:** Gives your AI assistant 65 Virlo tools. MCP (Model Context Protocol) is the standard way AI apps use outside tools.
- **You send:** Questions in plain words to your assistant, after a one-time setup.
- **You get back:** Answers built on real Virlo data, such as this week's top TikTok hooks for food content, each with its source video.
- **Cost:** Connecting and re-reading results are free. Quick data (Topic Trends, Format Trends, trending videos, hashtags, sounds, hooks) costs $0.05 to $0.25 a call, and live raw data $0.01 a call. New research or a lookup starts at $0.50.
- **How long:** Most tools answer in seconds. A Content Research Agent can take about 20 minutes; ask the assistant to check back.

> **Note:** **Need an API key?** Not in **Claude Desktop, claude.ai, or Claude Code**. They sign you in to Virlo and create one for you. Other apps (**Cursor, VS Code, Windsurf, Codex**) need a key from your [dashboard](https://dev.virlo.ai/dashboard/api-keys), unless they offer to sign you in to Virlo. Keys start with `virlo_tkn_`.

## Quick setup

Pick your app's tab. If it uses an API key, paste the key first so the setup code includes it. Cursor then gets a one-click install button.

**Server URL:** `https://dev.virlo.ai/api/mcp/mcp`. Transport: streamable HTTP. Auth: `Authorization: Bearer YOUR_API_KEY`.

**Cursor** (\~/.cursor/mcp.json):

```json
{
  "mcpServers": {
    "virlo": {
      "url": "https://dev.virlo.ai/api/mcp/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

**VS Code** (.vscode/mcp.json):

```json
{
  "servers": {
    "virlo": {
      "type": "http",
      "url": "https://dev.virlo.ai/api/mcp/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

**Claude Code:**

```bash
claude mcp add --transport http virlo https://dev.virlo.ai/api/mcp/mcp --header "Authorization: Bearer YOUR_API_KEY"
```

## Any other MCP app

Any app that supports remote MCP servers can connect with:

| Setting | Value |
| - | - |
| Server URL | `https://dev.virlo.ai/api/mcp/mcp` |
| Transport | Streamable HTTP (some apps say "HTTP") |
| Header | `Authorization: Bearer YOUR_API_KEY` |

If your app supports MCP sign-in (OAuth), skip the header and sign in. If it only runs local servers, use the `mcp-remote` bridge on the Windsurf and Codex tabs.

**Details for developers**

- The server is stateless. Use `POST` (a `GET` returns `405`) and send `Accept: application/json, text/event-stream` (or get `406`).
- `401` means a missing `Authorization` header or a key without the `virlo_tkn_` prefix. `403 Origin not allowed` means a browser app sent an unapproved `Origin`. Native apps should send none.
- Tool errors come back as normal replies with the error text inside.
- OAuth discovery: `https://dev.virlo.ai/.well-known/oauth-protected-resource` (dynamic client registration, PKCE `S256`).

## If something goes wrong

- **Connected, but every tool says "Invalid or inactive API key".** Setup only checks the `virlo_tkn_` prefix. The real check comes on the first call. Copy the key again from your [dashboard](https://dev.virlo.ai/dashboard/api-keys).
- **Paid tools fail with error 402, free ones work.** Your balance is too low. Add funds on the [Billing page](https://dev.virlo.ai/dashboard/billing).
- **A filter does nothing.** Tools silently ignore settings they don't know, such as a misspelled name. Ask the assistant which settings it sent.

## Content Research Agents

A **Content Research Agent** collects and analyzes short-form videos on a topic you describe. It runs once, or on a daily, weekly, or monthly **cadence**. Each collection is a **run**.

For historical reasons, one-time agent tools say "keyword search" and recurring ones say "niche monitor". Both create [Content Research Agents](https://dev.virlo.ai/docs/agents).

### Getting good results from an agent

1. **Describe the goal in one sentence.** This **intent** is required. Say who it's for and what you want to learn, like "beginner skincare routines that name drugstore products." See the [Intent cookbook](https://dev.virlo.ai/docs/intent-cookbook).
2. **Get free keywords** from `suggest_keywords`: usually 7 to 12 phrases, plus words to exclude. If it flags the intent as weak, sharpen it.
3. **Start the agent** with the same intent and both lists (up to 50 keywords, same price).
4. **Wait for `finalized: true`**, then read `data_type: "summary"` first.

Reading results is free. Ask to filter by views, dates, platform, sort order, or country (beta).

**Data Intelligence** (+$1.00 per run): AI tags collected videos with 79 details (70 for slideshows), such as hook, format, and tone. Turn it on when you start the agent (`data_intelligence_enabled: true`), or later with `update_niche_monitor`. It never applies to past runs. See [Data Intelligence](https://dev.virlo.ai/docs/intelligence).

**More options**

- **Other languages.** Set `english_only: false`, and write the keywords and intent in that language.
- **Meta ads.** `enable_meta_ads: true` (`search_keywords`) or `meta_ads_enabled: true` (`create_niche_monitor`) adds Meta ads at no extra cost. Runs can then take longer, up to about 45 minutes.
- **Partial results.** Status `partial_failure` is usable: one platform or keyword failed.

## Available tools

Prices are per call.

### Topic Trends and hashtags (instant)

- `search_hashtags` ($0.05): top hashtags by uses or views.
- `get_hashtag_performance` ($0.05): views, likes, and comments for one hashtag.
- `get_trending_videos` ($0.25): the most-viewed videos from the last 48 hours.
- `get_trends` ($0.25): Topic Trends, news and pop culture topics with example videos, by date and region.
- `get_trends_digest` ($0.25): today's Topic Trends list for a region.
- `get_emerging_trends` ($0.25): new and rising topic trends ranked by momentum.

Trend regions are `global` (the default), `us`, `gb`, `au`, and `sg`.

### Format Trends

Video formats creators are copying right now, reviewed by the Virlo team before they are published. Topic Trends above are subjects people talk about; Format Trends are video formats you can make yourself. `get_content_trends` returns Format Trends. See [Format Trends](https://dev.virlo.ai/docs/content-trends).

- `get_content_trends` ($0.25): the published formats, live ones by default, with filters for stage, platform, client type, and brand safety.
- `get_content_trend` ($0.05): one format with all its example videos and its 30-day history.

### One-time agents

- `suggest_keywords` (free): turns an intent into graded keywords and exclude words. Creates nothing.
- `search_keywords` ($0.50, or $1.50 with Data Intelligence): starts a one-time agent. Needs `intent`.
- `list_keyword_searches` (free): lists them.
- `get_keyword_search_results` (free): reads results by `data_type`: `status` (the default), `summary`, `videos`, `slideshows`, `ads`, `outliers`, `analysis`, `trends`, or `sounds`.

**Outliers** are creators whose videos get far more views than their follower count predicts.

### Recurring agents

- `create_niche_monitor` ($0.50 per run, or $1.50 with Data Intelligence): runs `daily`, `weekly`, or `monthly`. Needs `intent`. The first run starts right away and is billed.
- `list_niche_monitors` (free): lists them.
- `get_niche_monitor_data` (free): reads results. Uses `overview` (the default) instead of `status`, and adds `hashtags`, `benchmarks`, `affinity` (related topics, beta), and `similar` (look-alike creators, beta).
- `update_niche_monitor` (free): changes settings. `is_active: false` pauses the agent, and `true` resumes it.
- `delete_niche_monitor` (free): deletes the agent for good and stops billing. It drops off your list, but past results stay readable by ID, so save it. To stop for a while, pause instead.
- `set_niche_monitor_autonomy` (free): turns autopilot on or off with `autopilot: true` or `false`.
- `get_niche_monitor_activity` (free): the change log. What the agent noticed, what autopilot changed, and why.
- `get_niche_monitor_events` (free): breaking stories in the niche, scored 0 to 10.
- `get_niche_monitor_proposals` and `review_niche_monitor_proposal` (free, deprecated): list and act on suggested changes. Autopilot now applies changes itself, so read the activity log instead.

**How autopilot works**

After each run, a recurring agent rewords its searches and adds keywords so it keeps finding new videos. Autopilot is on by default, with nothing to unlock. It never removes the keywords or exclude terms you set, never adds charges, and never changes the schedule. To turn it off, pass `autopilot: false` to `create_niche_monitor`, `update_niche_monitor`, or `set_niche_monitor_autonomy`. [More on autopilot](https://dev.virlo.ai/docs/agents/autopilot).

### Creator, video, sound, and hashtag lookups

A **lookup** is a one-time deep dive on one creator, video, sound, or hashtag, saved as a run you can re-read for free. Tool names say `satellite`, the internal name for lookups.

- `lookup_creator` ($0.50, up to $1.75): profile, recent videos, and top performers. Add-ons: `trend_analysis` (+$0.50), `data_intelligence` (+$0.25), and audience data (+$0.50).
- `batch_lookup_creators` ($0.50 per creator, free if looked up in the last 6 hours with at least the same options): up to 25 creators at once.
- `analyze_video` ($0.50): how far one video beat the creator's usual numbers.
- `lookup_sound` ($0.50, or $1.00 with trend analysis): up to 100 videos using a TikTok or Instagram sound, or about 300 with trend analysis. Takes the sound's `music_id` (the number at the end of its link) or a Virlo sound ID.
- `lookup_hashtag` ($0.50, up to $2.50 with [more videos and trend analysis](https://dev.virlo.ai/docs/satellite/hashtags)): videos and stats for a TikTok, Instagram, or YouTube hashtag. Repeats within 6 hours are free.
- `get_satellite_run` (free): re-reads a past lookup by `run_id`. Each paid lookup has its own run, so older ones stay.
- `list_satellite_runs` (free): past lookups. Check here before paying again.

### Tracking

Tracking checks a creator or video on a schedule (daily by default, from every 6 hours to monthly) and writes a short AI report.

- `track_creator` and `track_video` ($0.25 per check): start tracking. `collection_depth` also pulls a creator's older posts once, for $0.50 to $2.00.
- `list_tracked_items` (free): what you track.
- `get_tracking_report` (free): the latest AI report and snapshots.
- `get_tracking_signals` (free): alerts such as outlier videos and follower spikes.
- `list_creator_posts` (free): a tracked creator's posts and the sounds used.
- `collect_creator_posts` ($0.50, $1.00, or $2.00): pulls up to 50, 200, or 500 more posts now. Refunded if it finds none.
- `get_posting_cadence` (free): how often, and on which days, the creator posts.
- `update_tracking_settings` (free): pauses, resumes, or changes how often it checks. Paused items stay listed and stop costing.
- `untrack_creator` and `untrack_video` (free): stop tracking. Tracking a creator again restores the history. A video can't be tracked again.

### Audience

Audience data describes who comments on a creator's videos: age, gender, language, and location. It covers creators you track. For others, add it to `lookup_creator`.

- `refresh_creator_audience` ($0.50): makes a new snapshot, or returns one under 30 days old, or one still being made, for free. Refunded if data is too thin.
- `get_creator_audience_demographics` (free): age, gender, and language.
- `get_creator_audience_geography` (free): top countries and cities.

### Sounds

- `get_trending_sounds` ($0.25): sounds used in the most new videos in the last 7 days.
- `get_breakout_sounds` ($0.25): the fastest-growing sounds from a small start.
- `search_sounds` ($0.10): title search. Spelling must match; case doesn't.
- `get_sound_details` ($0.05): details and totals. `resolve: true` finds the original song for $0.10 more, the first time only.
- `get_sound_videos` ($0.25): videos using a sound, by views or date.
- `get_sound_usage_history` ($0.05): a daily snapshot of the sound's total use count and its daily growth.
- `get_creator_sounds` ($0.25): sounds a creator owns, and how many others use them.

`get_sound_details`, `get_sound_videos`, and `get_sound_usage_history` take Virlo's sound ID from `search_sounds` or `get_trending_sounds`. Agent-collected sounds are free with `data_type: "sounds"`.

### Hooks

A **hook** is a video's opening line or shot. They're ranked by **Virality Score**: how far a video beat its creator's follower count. See [Hooks](https://dev.virlo.ai/docs/hooks).

- `get_trending_hooks` ($0.25): the best opening lines right now, with source videos.
- `search_hooks` ($0.25): finds hooks by phrase or type.
- `get_hook_types` (free): which hook styles win most often.
- `get_hook_library` ($0.10): fill-in-the-blank hook templates.
- `get_agent_hooks` ($0.25, free with Data Intelligence or while the agent has no hooks): top hooks from your agent. Without Data Intelligence there are few or none, so use `get_trending_hooks`.

### Raw data

Live, unprocessed data from the platform, with the same fields on TikTok, YouTube Shorts, and Instagram Reels. Each call costs $0.01, even when it finds nothing. See [Raw data](https://dev.virlo.ai/docs/raw).

- `raw_search`: videos for a keyword.
- `raw_hashtag`: videos under a hashtag.
- `raw_video`: one video's details and counts right now.
- `raw_comments`: a video's comments.
- `raw_transcript`: what is said in a TikTok or YouTube video.
- `raw_creator`: a creator's profile and counts right now.
- `raw_creator_videos`: a creator's videos.

Lists come one page per call. To get the next page, the assistant passes the `next_cursor` it got back as `cursor`, and each page is charged.

### Job status and balance

- `check_job_status` (free): checks any background job.
- `get_credit_balance` (free): your balance in dollars and credits (1 credit = $0.01), plus prices.
- `build_virlo_skill` (free, no API call): writes a personal Virlo skill file (SKILL.md) from what the assistant knows about you, with install steps for Claude, ChatGPT, Cursor and Claude Code.

## Long-running jobs

Agents, lookups, post collection, and audience snapshots run in the background.

- `search_keywords`, `lookup_creator`, `analyze_video`, `lookup_sound`, and `lookup_hashtag` wait up to 25 seconds, checking every 2.5 seconds. If the job isn't done, you get `status: "processing"` and a job ID to check later with `check_job_status`, not in a loop.
- `create_niche_monitor`, `batch_lookup_creators`, `collect_creator_posts`, and `refresh_creator_audience` return an ID right away.

A job is done when `finalized: true`. `completed` can mean the AI report is still being written, so empty analysis fields mean "not yet". A video with `intelligence_status: "skipped"` is the exception: it was left out on purpose.

Half of agent runs finish collecting in under 8 minutes, and 9 in 10 in under 20. The AI report follows within minutes. Lookups take under a minute to about 3 minutes.

In a chat app, ask the assistant to check back in 10 to 20 minutes. Developers can use the `content_research_agent.run.completed` [webhook](https://dev.virlo.ai/docs/webhooks) instead.

## Guides your assistant can read

The server has four read-only guides (MCP resources). Many apps don't read them unprompted, so start big research with "Read Virlo's agent playbook and intent cookbook first."

- `virlo://docs/intent-cookbook`: how to write a good intent.
- `virlo://docs/agent-playbook`: which tool fits which question, and how to avoid wasted spend.
- `virlo://docs/api-overview`: the tool catalog.
- `virlo://docs/credit-costs`: the price of each tool.

The first two are also plain text for AI assistants ([`/intent-cookbook.txt`](https://dev.virlo.ai/intent-cookbook.txt), [`/agent-playbook.txt`](https://dev.virlo.ai/agent-playbook.txt)) and pages for people ([Intent cookbook](https://dev.virlo.ai/docs/intent-cookbook), [Research playbook](https://dev.virlo.ai/docs/agent-playbook)).

## Workflow prompts

These are built-in, multi-step research plans. Pick one from your app's menu or ask by name: "Use the full_niche_analysis prompt for viral cooking content."

- **`start`** (optional `website` and `goal`): a first-run tour. Checks what the assistant knows about you, reads your website, runs `suggest_keywords` (free), and asks before it spends anything. $0.50 if you say yes to the first research run.
- **`full_niche_analysis`** (you give `niche`): drafts keywords with `suggest_keywords` (free), runs a one-time agent, looks up the top 2 or 3 creators, and sets up a weekly agent. About $2.00 to $2.50, then $0.50 a week.
- **`creator_deep_dive`** (`platform`, `username`): looks up the creator and writes a profile, then asks before tracking them. $0.50, plus $0.25 per check if you track them.
- **`trend_scout`** (optional `platform`: `youtube`, `tiktok`, `instagram`, or `all`): turns emerging trends, today's digest, viral videos, and hashtag momentum into a trend report. About $0.90 to $1.25.
- **`genre_monitor`** (`genre`): drafts keywords with `suggest_keywords` (free), creates a weekly TikTok agent, and writes a genre brief. $0.50 a week until you stop it.
- **`competitor_landscape`** (`subject`, a creator or niche; optional `platform`): runs an agent with Data Intelligence, shortlists 3 to 5 competitors, looks each up after you confirm, and writes a positioning brief. About $3.00 to $4.50.

## What it costs

MCP tools cost the same as the Virlo API and draw from your prepaid API balance. It's separate from any Virlo app plan. Recurring agents and tracking bill every run until you pause or stop them.

MCP replies don't show what a call cost. Run `get_credit_balance` before and after, or open [Usage](https://dev.virlo.ai/dashboard/usage).

[Billing and pricing](https://dev.virlo.ai/docs/credits)

---

More in For AI assistants:

- [Connect an AI assistant](https://dev.virlo.ai/docs/ai-agents.md)
- [Research playbook](https://dev.virlo.ai/docs/agent-playbook.md)