Install

Use the remote Streamable HTTP endpoint:

https://viralquery.com/mcp

Add to Claude or Cowork (no key needed)

In Claude or Cowork, open Settings → Connectors → Add custom connector, paste the URL above, and leave the OAuth fields blank. Claude signs in through ViralQuery's OAuth flow: you confirm the email on your account with a one-time code, and Claude receives its own access token. Connecting does not change or reveal your API key, and there is no client ID or secret to enter.

For clients that take a bearer header directly (Claude Code, Cursor), you can skip OAuth and paste a key instead — see below.

Have your secret manager inject the key as VIRALQUERY_API_KEY before adding it to a client configuration. For an interactive shell, use the non-echo CLI auth steps. Never type a literal key into shell history, paste it into chat, or commit it to source control.

Claude Code

claude mcp add --transport http --scope user viralquery https://viralquery.com/mcp \
  --header "Authorization: Bearer ${VIRALQUERY_API_KEY}"

Verify with claude mcp get viralquery, then ask Claude to set your workspace and rules before it runs the first scroll.

Project configuration

Claude Code and other clients that support environment expansion can use:

{
  "mcpServers": {
    "viralquery": {
      "type": "http",
      "url": "https://viralquery.com/mcp",
      "headers": {
        "Authorization": "Bearer ${VIRALQUERY_API_KEY}"
      }
    }
  }
}

Cursor

Create or update .cursor/mcp.json:

{
  "mcpServers": {
    "viralquery": {
      "url": "https://viralquery.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:VIRALQUERY_API_KEY}"
      }
    }
  }
}

Environment-variable syntax varies by client. If yours does not expand variables inside MCP headers, add the bearer header through that client's secure secrets UI.

Install the agent skill

The public ViralQuery skill adds the personalized research workflow:

npx --yes skills@1.5.17 add https://github.com/tfcbot/viralquery-skills/tree/083f6dac6b4cc2adb689aef99da55535bb4903b7/skills/viralquery --skill viralquery --copy

The command pins the exact reviewed skill commit published with v2.2.0; the skill can call ViralQuery's HTTP API directly and does not contain or store your API key.

Test the connection

Connect, then ask the client to call getWorkspace. A missing or invalid key is rejected before MCP initialization; a successful response confirms that the protected tenant tools are available. The MCP tool set mirrors the current tenant API, including research-brief updates, provenance filters, and tenant-owned video annotations.

• 401 unauthorized — the bearer header is missing or the key is invalid.
• 402 subscription_required — the key exists but has no active subscription.
• 429 rate_limited — honor Retry-After and retry the burst-limited request with backoff.
• 409 scroll_active_limit — wait for the current scroll to finish before starting another one.

ViralQuery has no monthly or per-scroll quota. Use getUsage to read daily and monthly AI-budget consumption as percentages.