brainvi-mcp

Cortical scoring for agents. brainvi-mcp is a Model Context Protocol server that gives any MCP-capable agent (Claude Code, Claude Desktop, Cursor, …) the ability to predict the neural and emotional response to media — video, image, or audio — using BrainVI's cortical model trained on real human fMRI.

Given a piece of media it returns the full neural-score breakdown — engagement (hook), sustained attention, emotional resonance, memory encoding, aesthetic quality, cognitive accessibility — plus key moments and specific, actionable improvement notes. Use it to judge whether content will land before you ship it, and to close the create → score → refine loop.

Quickstart (Claude Code)

claude mcp add brainvi -e BRAINVI_API_KEY=sk_live_your_key_here -- npx -y brainvi-mcp

That's it. Restart Claude Code and ask it to "score this video with BrainVI: https://…/clip.mp4". The server is fetched from npm on demand — nothing to clone or build.

Get a key: mint one in the BrainVI dashboard → API Keys (or ask whoever shared this with you). It's sent as the X-API-Key header.

{
  "mcpServers": {
    "brainvi": {
      "command": "npx",
      "args": ["-y", "brainvi-mcp"],
      "env": { "BRAINVI_API_KEY": "sk_live_your_key_here" }
    }
  }
}

Claude Desktop: claude_desktop_config.json. Cursor: ~/.cursor/mcp.json (or .cursor/mcp.json in a project).

| Env var | Required | Default | Notes | | ------------------------- | -------- | --------------------------------------------------- | -------------------------------------------------- | | BRAINVI_API_KEY | ✅ | — | Sent as X-API-Key. | | BRAINVI_API_URL | ❌ | https://neuropeer-api-production.up.railway.app | Point at a self-hosted backend. | | BRAINVI_SCORE_TIMEOUT_MS| ❌ | 45000 | How long a score waits inline before handing back a job_id (see below). |

How scoring works (read this — it's the one gotcha)

Cortical scoring runs on a GPU and takes ~1–4 minutes (longer on a cold start). MCP hosts abort a tool call after ~60s, so a single blocking call can't return a minutes-long result. brainvi-mcp handles this with a simple submit → poll pattern:

1. score_video / score_image / score_audio waits up to ~45s. If the score finishes (warm/cached), you get the full report inline. Otherwise it returns:

   { "status": "processing", "job_id": "…", "stage": "inferring",
     "message": "Call get_report with job_id … in ~1 minute." }

2. get_report({ job_id }) fetches the finished report (or tells you it's still processing). Call it again in 30–60s until the neural_score comes back.

Agents handle this naturally — they submit, then poll get_report until the score is ready. No configuration needed.

Tools

All scoring tools take a public media url. Scores are 0–100 (higher is better).

score_video({ url, content_type? })

Full neural-score breakdown for a video.

// input
{ "url": "https://cdn.example.com/clip.mp4", "content_type": "instagram_reel" }
// output (when finished)
{
  "job_id": "…",
  "content_type": "instagram_reel",
  "duration_seconds": 6.4,
  "neural_score": {
    "total": 35.9, "hook_score": 21.9, "sustained_attention": 93.2,
    "emotional_resonance": 24.5, "memory_encoding": 44.4,
    "aesthetic_quality": 14.5, "cognitive_accessibility": 61.1
  },
  "key_moments": [{ "timestamp": 2, "type": "best_hook", "label": "Best Hook", "score": 90.9 }]
}

score_image({ url, content_type? })

Score a still image / UI screenshot. Note: the model is trained on video/audio, so static images are out-of-distribution — treat image scores as directional (good for relative A/B ranking, not absolute claims).

score_audio({ url, content_type? })

Score audio/voice for emotional resonance and arousal — A/B voiceovers or music beds.

score_and_iterate({ url, goal?, content_type? })

The score plus a structured interpretation bundle for the agent to act on: ranked weakest/strongest cortical dimensions and brain-region metrics (each with its neural mechanism + go-to-market proxy), key moments, and the backend's own AI report as a baseline. It does not hand you canned advice — apply the bundled interpret-cortical-scores skill to turn the raw signals into content-specific, brain-region-grounded fixes (your own model does the analysis, the way the backend augments its minimax reporter). Re-run after edits to confirm the lift.

cortical_embeddings({ url, modality })

Raw cortical embedding vector — the primitive behind every score. modality: video | image | audio | text.

get_report({ job_id })

Fetch a submitted score by job_id (the async poll target — see above).

health()

Check backend reachability and that the API key is accepted.

content_type hint

Optional. The backend recognizes exactly these presets: instagram_reel, product_demo, youtube_preroll, conference_talk, podcast_audio, feature_film, custom. Any other value (e.g. ad_creative) is treated as custom — it won't error, it just uses generic weighting.

Bundled skills

The package ships agent skills under skills/:

• rate-creative-content.md — judge whether content will land emotionally / creatively.
• website-aesthetic-loop.md — screenshot the UI → score_image → fix the weakest dimensions → re-score.
• voice-emotion-check.md — score a voice/audio clip before/after edits for emotional resonance.
• score-and-iterate.md — the general create → score → refine loop.
• interpret-cortical-scores.md — the rubric for turning a raw neural-score report into specific, brain-region-grounded fixes (no generic advice). Used by score_and_iterate.

Errors

• Missing key → server exits at startup telling you to set BRAINVI_API_KEY.
• Auth failure (401/403) → tools return an isError response with a clear message.
• Backend 4xx/5xx → surfaced verbatim (status + body) so the agent can react.

Programmatic use

import { BrainViClient, loadConfig } from 'brainvi-mcp';

const client = new BrainViClient(loadConfig());
const result = await client.scoreAndWait('https://cdn.example.com/clip.mp4', 'instagram_reel');

License

MIT