MCP Server

Connect AI assistants to the Virlo API with our native Model Context Protocol (MCP) server. Supports Cursor, Claude Cowork, claude.ai, VS Code, Claude Code, Claude Desktop, and Windsurf with one-click or copy-paste setup.

Quick Setup

Enter your API key below to get personalized, ready-to-use configuration for your AI client. Cursor users get a one-click install button.

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

Available Tools

The MCP server exposes 36 curated tools that cover every capability of the Virlo API. Tools are named for what they do — not the HTTP endpoint underneath.

Analytics (instant results)

Orbit — Keyword Search (async)

Comet — Niche Monitoring

Satellite — Creator, Video & Sound Intelligence (async)

Tracking — Long-term Monitoring

Audience — Demographics & Geography (cache-first)

Audience snapshots profile a tracked creator's engaged audience — derived from analyzing the creator's commenters rather than the raw follower base. When commenter signal is sparse the pipeline falls back gracefully (a TikTok-only follower-list blend, or as a last resort a low-confidence hint synthesized from the creator's declared country/language/bio that is always refunded) — exact source mix exposed on data_source. Every snapshot carries data_source, signal_breakdown, and confidence_level so consumers can filter on quality. Snapshots are cached for 30 days by default. The refresh tool is cache-first: it returns the cached snapshot for free if it's within the freshness window, otherwise queues a new job (charged on dispatch) and fires the audience.snapshot.completed webhook when ready.

lookup_creator (Satellite) also accepts audience_demographics, audience_geography, and freshness_days for one-shot enrichment of untracked creators — same pricing. It also accepts trend_analysis=true to run an LLM over the creator's body of work (forces a 100-video deep fetch, +$0.50 surcharge). The returned trends block has the same shape as sound trends — time_windows[], resurged, momentum, and evidence_video_ids that map back to videos[] in the same response. Re-reading via get_satellite_run is free.

Sounds — Audio Intelligence

Sound data is also available via get_keyword_search_results and get_niche_monitor_data using data_type: "sounds" (free).

Platform field availability: TikTok has the richest sound data (title, duration, cover_url, usage_count, is_commerce_music). YouTube has title, cover_url, owner info. Instagram has title and owner_nickname only. Fields unavailable for a platform return null.

Utility

Async Operations

Some tools queue background jobs — keyword searches (Orbit), creator lookups (Satellite), video analysis (Satellite), and post collection (Tracking). These tools handle the complexity for you:

1. The tool queues the job and automatically polls for up to 55 seconds
2. If the job finishes quickly, you get full results in one call
3. If the job is still running, you get a job_id and job_type with instructions
4. Use check_job_status with those values to poll later — the AI agent handles this automatically

This means most fast operations complete in a single tool call, while long-running scrapes gracefully hand back control so the agent can do other work while waiting.

Workflow Prompts

The MCP server includes three pre-built workflow prompts that guide AI agents through multi-step research:

full_niche_analysis

End-to-end niche research workflow:

1. Keyword search with Orbit
2. Review top videos and creator outliers
3. Deep-dive on top creators with Satellite
4. Set up automated Comet monitoring
5. Summary with actionable insights

Example: "Use the full_niche_analysis prompt for viral cooking content"

creator_deep_dive

In-depth analysis of a specific creator:

1. Profile lookup with Satellite
2. Content pattern analysis
3. Optional long-term tracking setup

Example: "Run creator_deep_dive for @khaby.lame on TikTok"

trend_scout

Discover what's trending right now:

1. Today's trend digest
2. Top viral videos
3. Rising hashtag analysis
4. Actionable trend report

Example: "Use trend_scout to see what's trending across all platforms"

Credit Costs

Pay-as-you-go prepaid balance. Add funds (minimum $10) at Dashboard Billing. Balance never expires. Auto top-up available.