Viomba MCP Server

Overview

Viomba MCP Server exposes Viomba’s AI-powered ad analytics capabilities to any Model Context Protocol-compatible AI client. Connect the AI tools you already use to powerful creative intelligence — no custom integrations required.

Key Features

• Works with any MCP-compatible AI client — Claude, Cursor, VS Code, and more
• Powered by Viomba’s infrared eye-tracking AI — 500M+ real fixation-level gaze samples from Tobii hardware, not modelled or simulated attention
• Predicts Seen % and Viewtime (ms) per ad creative, format, and device — before a single impression is served
• Returns gaze heatmaps as inline images directly in your AI client
• Simple invite-based onboarding — get started in minutes
• Secure OAuth 2.1 authentication — no static API keys to manage
• Built-in usage history and analytics tools included with every account

Compatible AI Clients

Viomba MCP works with any MCP-compatible AI client or agent framework:

What Can You Do With Viomba MCP?

Layer 1 — Ad creative intelligence

• Ask an AI assistant to predict the attention KPIs of a display ad creative before it goes live — Seen % and expected Viewtime against real infrared eye-tracking benchmarks
• Generate gaze heatmaps across multiple ad variants and compare them side-by-side directly in your AI client
• Slice an animated HTML5 or DCO ad into timed frames and feed them into a creative prediction pipeline automatically

Layer 2 — Media Attention scoring

• Score any ad creative against Viomba’s 500M+ Tobii infrared benchmark database — by format (display, social, video), device (mobile, desktop), and placement context
• Understand precisely where human eyes are predicted to fixate, how long they will hold, and how your creative ranks against category benchmarks
• Choose between mobile_display, desktop_display, mobile_display_context, and desktop_display_context model variants for placement-aware scoring

Layers 3–5 — Inventory curation, campaign optimisation, and outcome reporting

• Available on Growth, Scale, and Enterprise tiers — domain attention analysis, DSP line item packaging, AttN Pulse publisher tools, and real-time campaign outcome reporting
• Contact mcp@viomba.com to discuss access

System intelligence

• Query your tool usage history, latency breakdowns, and per-tool analytics without leaving your chat interface
• Automate creative evaluation by integrating Viomba tools into AI workflows at any scale

Setup Instructions

Prerequisites

• An MCP-compatible AI client
• An invite link from a Viomba administrator

Getting Started

VS Code / GitHub Copilot

Add the following to your VS Code settings.json (or your workspace .vscode/mcp.json):

{
  "mcp": {
    "servers": {
      "viomba": {
        "type": "http",
        "url": "https://mcp.viomba.com/mcp"
      }
    }
  }
}

VS Code will open the OAuth flow automatically on first use.

Claude Desktop

Add the following block to your claude_desktop_config.json:

{
  "mcpServers": {
    "viomba": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.viomba.com/mcp",
        "--client-id", "<your-client-id>",
        "--client-secret", "<your-client-secret>"
      ]
    }
  }
}

Cursor / Windsurf

In Cursor go to Settings → MCP Servers → Add Server and enter:

• Server URL: https://mcp.viomba.com/mcp
• Auth type: OAuth 2.0
• Client ID / Secret: your registered credentials

Manual OAuth Flow (CLI / custom clients)

For headless or custom clients, complete the standard Authorization Code + PKCE exchange:

# 1. Generate a PKCE code verifier and challenge
code_verifier=$(openssl rand -base64 64 | tr -d '=+/' | head -c 96)
code_challenge=$(echo -n "$code_verifier" | openssl sha256 -binary | base64 | tr '+/' '-_' | tr -d '=')

# 2. Open the authorization URL in your browser
open "https://mcp.viomba.com/oauth/authorize\
  ?response_type=code\
  &client_id=<client_id>\
  &redirect_uri=<redirect_uri>\
  &scope=tools:read+tools:execute\
  &code_challenge=$code_challenge\
  &code_challenge_method=S256\
  &state=random_state"

# 3. Exchange the code for tokens
curl -X POST https://mcp.viomba.com/oauth/token \
  -d "grant_type=authorization_code" \
  -d "code=<code>" \
  -d "redirect_uri=<redirect_uri>" \
  -d "client_id=<client_id>" \
  -d "client_secret=<client_secret>" \
  -d "code_verifier=$code_verifier"

Available Tools

The tools currently available on all tiers cover Layers 1 and 2 of Viomba’s 360° Attentive Campaign Intelligence pipeline — ad creative slicing, attention KPI prediction, and gaze heatmap generation. All three tools are powered by Viomba’s proprietary AI, trained on fixation-level infrared eye-tracking samples collected at 250,000 samples per week from real panellists using Tobii infrared hardware across Finland, Denmark, Germany, France, Poland, and the United Kingdom.

Tools available to you depend on your account tier. Call viomba_my_usage to see your full list of enabled tools.

Dekaani — Ad Intelligence

System Tools

Platform management and analytics tools included with every account tier.

Authentication

Viomba MCP uses OAuth 2.1 — the current industry standard for secure delegated access. No static API keys are stored or transmitted. Access tokens expire after 15 minutes and are refreshed automatically by all supported MCP clients.

Viomba MCP uses OAuth 2.1. All /mcp requests require a valid bearer token in the Authorization header.

Token Format

Authorization: Bearer <access_token>

OAuth Endpoints

• Authorization: https://mcp.viomba.com/oauth/authorize
• Token: https://mcp.viomba.com/oauth/token
• Revocation: https://mcp.viomba.com/oauth/revoke

Token Lifetimes

• Access token: 15 minutes
• Refresh token: 30 days

API Endpoints

Troubleshooting

Authentication Failures

• Verify your access token is included as Authorization: Bearer <token>
• Tokens expire after 15 minutes — ensure your client is refreshing them automatically
• Check that your client_id and client_secret are correct
• Confirm your redirect URI exactly matches what was registered during invite redemption

Tool Not Available

• Call viomba_my_usage to see your full list of enabled tools
• Tools are gated by tier — contact Viomba support if you need access to additional tools

Dekaani Tool Errors

• Always call dekaani_ad_slicer first — the other Dekaani tools require S3 image URLs as input
• Ensure pageUrl or htmlTag is provided (not both, not neither)
• For auto-sizing creatives, always provide explicit width and height
• Increase timeout_seconds for large or complex ads (max 300)
• Enable use_webhook if polling times out — requires the server to be publicly reachable

Rate Limiting

• Call viomba_my_usage to check your current usage
• If you are being rate limited, wait a moment and retry — your client should handle this automatically
• Contact Viomba support if you need higher limits for your use case

Understanding attention scores

• Seen % represents the predicted probability that a human gaze fixation (200ms+ fixation event) will occur on the ad creative in the specified format and device context — not just that the ad was technically viewable
• Viewtime (ms) represents the predicted average gaze dwell time on the ad across fixating impressions — distinct from technical viewable time
• mobile_display_context and desktop_display_context model variants produce placement-aware scores — use these when scoring against a specific publisher domain or section context for more accurate campaign-level predictions
• Scores are benchmarked against Viomba’s empirical database of 500M+ Tobii infrared eye-tracking observations — not modelled, simulated, or webcam-estimated attention
• A preview attention score is returned for standalone creative evaluations. A full attention score — including placement-level prediction and full benchmark comparison — is available when the creative is linked to an active Viomba campaign activation