# Install (/docs/mcp/install)



Use the remote Streamable HTTP endpoint:

```text
https://viralquery.com/mcp
```

## Add to Claude or Cowork (no key needed) [#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](/docs/cli/auth). Never
type a literal key into shell history, paste it into chat, or commit it to source control.

## Claude Code [#claude-code]

```bash
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 [#project-configuration]

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

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

## Cursor [#cursor]

Create or update `.cursor/mcp.json`:

```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 [#install-the-agent-skill]

The public ViralQuery skill adds the personalized research workflow:

```bash
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 [#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.