# ViralSky MCP server

Hosted Streamable HTTP MCP at `https://viralsky.ai/api/mcp`.

**Gate:** active Max (Stripe) or AppSumo T3. Credit costs match `/api/v1/*`. Ultra and AppSumo T1/T2 can schedule in the browser, but they cannot call the public API or this MCP server.

HTML help for the same feature: https://viralsky.ai/help (section “MCP server”). REST reference: https://viralsky.ai/docs/api.md.

## OAuth 2.1 (recommended)

Sign in on a Max or AppSumo T3 account, add the server URL, and approve the consent screen. The client stores its own access token. No API key paste.

- Authorization code + PKCE S256, with refresh-token rotation
- Audience bound to `https://viralsky.ai/api/mcp`
- Disconnect a connected app at https://viralsky.ai/settings/api

**Claude:** Settings → Connectors → Add custom connector → `https://viralsky.ai/api/mcp`.

**ChatGPT:** Settings → Apps / Connectors → add an MCP server with `https://viralsky.ai/api/mcp`.

**Cursor:** Settings → MCP → Add new MCP server → type URL → `https://viralsky.ai/api/mcp`. Leave headers empty. Cursor completes OAuth in the browser.

## API key alternative

Use this when a client cannot run OAuth and only sends a static header.

1. Create a key at https://viralsky.ai/settings/api.
2. Send `Authorization: Bearer vs_…`.

New keys include `generate`, `credits`, `webhooks`, `scheduler:read`, and `scheduler:write` unless you uncheck scopes. Older keys keep the scopes they were created with and cannot call scheduler tools until you create a new key or reconnect with OAuth.

Cursor example:

```json
{
  "mcpServers": {
    "viralsky": {
      "url": "https://viralsky.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer vs_YOUR_KEY"
      }
    }
  }
}
```

## Tools

| Tool | REST | Credits | Scope |
|------|------|---------|--------|
| `generate_thread` | `POST /api/v1/generate/thread` | 2 | `generate` |
| `generate_ideas` | `POST /api/v1/generate/ideas` | 1 (0 cache) | `generate` |
| `generate_news` | `POST /api/v1/generate/news` | 2 | `generate` |
| `generate_image` | `POST /api/v1/generate/image` | 5 / 10 | `generate` |
| `get_credits` | `GET /api/v1/credits` | 0 | `credits` |
| `list_social_accounts` | `GET /api/v1/scheduler/accounts` | 0 | `scheduler:read` |
| `how_to_connect_socials` | `GET /api/v1/scheduler/connect-instructions` | 0 | `scheduler:read` |
| `schedule_post` | `POST /api/v1/scheduler/posts` | 1 per X part, 0 for LinkedIn/Facebook | `scheduler:write` |
| `publish_now` | `POST /api/v1/scheduler/posts/publish` | 1 per X part, 0 for LinkedIn/Facebook | `scheduler:write` |
| `list_scheduled_posts` | `GET /api/v1/scheduler/posts` | 0 | `scheduler:read` |
| `cancel_scheduled_post` | `DELETE /api/v1/scheduler/posts/:id` | Refunds credits only for rows moved pending → canceled | `scheduler:write` |

Rate limit: 60 requests / minute per API key or per connected OAuth app (shared with REST).

## What you can publish

Scheduler tools publish to LinkedIn, X, and Facebook Pages. Connecting those accounts happens in the browser at https://viralsky.ai/scheduler. The agent cannot start that connection. Threads stays locked.

Scheduler tools also require the same scheduler plan as the website (Ultra, Max, or any active AppSumo tier, plus the scheduler flag for Stripe). Because the public API itself is Max / AppSumo T3, only those accounts can reach MCP.

X posts cost 1 ViralSky credit per thread part, charged when the post is created. LinkedIn and Facebook cost 0. Cancel refunds only posts this request atomically moves from `pending` to `canceled`.

## Discovery

- `GET /.well-known/oauth-protected-resource`
- `GET /.well-known/oauth-protected-resource/api/mcp`
- `GET /.well-known/oauth-authorization-server`

The public origin comes from `NEXTAUTH_URL`.
