Connect AI agents with MCP

The viral.app MCP server lets AI assistants and coding agents work with your workspace: read analytics, manage tracking and tags, look up Creator Hub campaigns and creators, and run live lookups on TikTok, Instagram, YouTube, Facebook and Snapchat. It speaks the open Model Context Protocol, so the same server works in every client that supports remote MCP servers.

Every client connects to the same URL:

https://viral.app/api/mcp

You sign in with your viral.app account in the browser. No API key, client ID or client secret is needed.

Before you start

• API access: the MCP server uses the same access layer as the public API, so your plan needs API access. API access is included with all Ultra plans and above.
• One organization per connection: during sign-in you pick the organization the agent works in. The connection stays bound to it. To work in another organization, connect again and pick that one.

Connect your agent

ChatGPT

Open the viral.app plugin in ChatGPT and click Connect. Sign in to viral.app in the window that opens and choose the organization.

Claude and Claude Desktop

Add a custom connector: open Settings, go to Connectors, choose Add custom connector, name it viral.app, and paste the server URL. Leave the OAuth client ID and secret empty. Then click Connect and sign in.

Claude Code

Install the viral.app plugin, which adds the server and a skill that teaches Claude Code how to use the tools:

claude plugin marketplace add https://github.com/fmd-labs/viral-app-agents
claude plugin install viral-app@viral-app

Run /mcp, pick viral_app, and sign in. To add only the server: claude mcp add --transport http viral_app https://viral.app/api/mcp.

Codex

codex plugin marketplace add https://github.com/fmd-labs/viral-app-agents
codex plugin add viral-app@viral-app
codex mcp login viral_app

This needs Codex CLI 0.147 or newer.

Cursor, VS Code and GitHub Copilot

Use the one-click Add to Cursor or Add to VS Code buttons on the Agents page, or add the server to your MCP config:

{ "mcpServers": { "viral_app": { "type": "http", "url": "https://viral.app/api/mcp" } } }

VS Code uses servers instead of mcpServers in .vscode/mcp.json. The editor asks you to sign in when it first connects to the server.

Gemini CLI

gemini extensions install https://github.com/fmd-labs/viral-app-agents

Grok

On grok.com/connectors, click New Connector, choose Custom, paste the server URL, and sign in.

Other agents

Any client that supports remote MCP servers over streamable HTTP with OAuth works: point it at the server URL. The viral-app-agents repository lists the install command or config snippet for more clients, including Kiro, Devin, Factory, OpenCode, Amp, Goose, Zed, Warp and JetBrains Junie.

How sign-in works

The first time your agent calls viral.app, it opens a browser window:

1. Sign in to viral.app, if you are not signed in already.
2. Pick the organization the agent should work in.
3. Approve the connection. The consent screen lists what the agent may do: read analytics and data, write and delete data, and spend billable credits. For agents that use refresh tokens, as most do, it also lists Stay connected.

The agent then works as you, inside that one organization, with your role's permissions. With Stay connected, the connection stays active after you sign out of viral.app in the browser, until you revoke it in Security settings. Without it, the agent has to sign in again once its access expires, after an hour.

What agents can do

• Analytics: top accounts, videos and creators, KPIs over any date range, and the history of an account or video.
• Tracking: list tracked accounts and videos, add accounts, refresh them, and check tracking status.
• Tags and workflows: create and apply tags, and manage tag workflows.
• Creator Hub: read campaigns and creators.
• Live lookups: fetch fresh data for public accounts, videos and searches on TikTok, Instagram, YouTube, Facebook and Snapchat.

Start with read-only questions, such as "Show my top tracked videos from the last 7 days", before you let an agent make changes.

Credits

Live lookups and manual refreshes use extra credits. A credit-spending tool called without confirmation spends nothing: it returns a quote with the estimated credits and your remaining balance, and tells the agent to ask you before it calls again with confirm: true. Only that confirmed call spends credits. Across MCP and the Copilot together, each organization can make up to 60 confirmed credit-spending calls per hour.

Use an API key instead

OAuth binds a connection to one organization. If an agent needs to switch between several organizations, or your client cannot complete a browser sign-in, create an org-scoped key in API Keys and send it as an x-api-key header:

{
  "mcpServers": {
    "viral_app": {
      "type": "http",
      "url": "https://viral.app/api/mcp",
      "headers": { "x-api-key": "YOUR_API_KEY" }
    }
  }
}

Use one server entry per organization, each with its own key. Treat keys like passwords, see API and automation.

Troubleshooting

• The agent says API access is unavailable: your plan does not include API access. See plan limits.
• The agent works in the wrong organization: revoke the connection in Security settings, then connect again and pick the right organization.
• The client cannot open a browser sign-in: use an API key as described above.