AI assistant connector (MCP)

Let an AI assistant plan, draft and report in ViralDashboard for you. The connector speaks the Model Context Protocol and runs every action through the same public API, with the same permissions, plan limits and credits.

What it is

An MCP server is a single HTTPS endpoint an AI client can call to discover and use tools (actions), resources (read-only context) and prompts (ready-made workflows). ViralDashboard's server never works around the API: each tool call is one or more public API requests made as your key, so it can only do what that key could do over the API.

Who can use it

• Workspaces on the Creator, Pro, Business, Agency and White-Label plans, while admitted to the beta.
• You need an API key. Mint one in Settings → API & Webhooks → API Keys, and pick the scopes for the tools you want (table below). The secret is shown once.
• The key acts as the person who minted it: it sees only the brands that person can access.

Connecting

Point any MCP client that supports the Streamable HTTP transport at the endpoint and send your key as a bearer token. A typical client configuration:

{
  "mcpServers": {
    "viraldashboard": {
      "type": "http",
      "url": "https://viraldashboard.io/mcp",
      "headers": { "Authorization": "Bearer vd_live_your_key_here" }
    }
  }
}

To check a key by hand, ask the server to describe itself:

curl https://viraldashboard.io/mcp \
  -H "Authorization: Bearer $VD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: server/discover" \
  -d '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{
        "io.modelcontextprotocol/protocolVersion":"2026-07-28",
        "io.modelcontextprotocol/clientCapabilities":{}}}}'

Every request carries MCP-Protocol-Version and Mcp-Method, plus Mcp-Name on tools/call, resources/read and prompts/get; a header that disagrees with the body is rejected with 400. MCP clients set these for you.

Tools and the scopes they need

A tool is listed only when the key holds all of its scopes. A key without them simply doesn't see the tool; mint a key with the scope to add it.

Resources

Read-only context an assistant can load before it acts. Read with resources/read.

Prompts

The confirm step

Anything that reaches the outside world or can't be undone — publishing now, replying to someone, hiding a comment, deleting or disconnecting — is never done on the first call. The first call runs every check, changes nothing, and returns:

{
  "status": "confirmation_required",
  "preview": { "…": "what will happen" },
  "confirm_token": "…",
  "expires_in_seconds": 300
}

The assistant shows the preview to you, and only if you agree calls the tool again with the same arguments plus confirm_token. A token works once, for those exact arguments, for the key that asked for it, and expires after 5 minutes. Anything else returns confirmation_invalid. Drafts never need confirming.

Test keys are dry runs

With a vd_test_… key, reads return live data and every write is a dry run: it passes through every scope, brand, plan and validation check and then stops, returning "status": "dry_run" with what would have happened. Nothing is created, sent or charged. Use a test key to try a workflow safely, and a live key to do it.

Retries are safe

Every write carries an idempotency key. If the assistant repeats a call with identical arguments (after a dropped connection, say), it gets the original result back instead of a second post or a second charge. To do the same thing twice on purpose, pass a new idempotency_key argument.

Errors

Connection-level

These come back as an HTTP status with a JSON-RPC error, before any tool runs:

Tool errors

A tool that can't do what was asked returns a normal result with isError: true. Its structuredContent.error carries the public API's code, type and message unchanged, plus a remediation written for the assistant and whether a retryable retry can help:

{
  "isError": true,
  "structuredContent": { "error": {
    "code": "limit_reached", "type": "invalid_request_error", "http_status": 402,
    "message": "…", "remediation": "…", "retryable": false, "details": { }
  } }
}

A resource that can't be read returns a JSON-RPC error with the same object in data.error. A resource that doesn't exist, or that you can't access, is -32602.

Codes

The API's own codes are described in Errors.

Rate limits

• The connector accepts up to 120 requests a minute per key. Over that, it answers 429 with Retry-After.
• Each tool call also counts against the key's hourly API rate limit, once for every API request it makes (a tool that lists brands and their accounts makes one request per brand). A tool that hits that limit returns rate_limited with retry_after.
• AI tools spend the workspace's AI credits, exactly as the API does.

Support

Questions, beta access or a bug: [email protected].