Wire Vizzybl into Claude Code, Cursor, or VS Code — the Claude Skill, the custom MCP connector, the MCP server, and the REST API, in one page.
Last updated
Connect Vizzybl to your coding agent once, and it can answer questions about how your brand appears inside AI answers without you opening a dashboard.
Vizzybl measures the output side of AI search: what ChatGPT, Claude, Gemini, Perplexity, Grok, Copilot, Google AI Overviews and Google AI Mode actually say about your brand, which sources they cite, and where a competitor gets named instead.
Connect the MCP server (30 seconds, below), then paste this into your agent:
Read https://vizzybl.ai/llms.txt for background, then use the Vizzybl MCP server
to show me our share of voice across every AI engine for the last 30 days, and
the competitor domains that get cited where ours doesn't.
Your agent calls get_visibility_stats and citation_gap, and answers from your real workspace data. Neither tool spends credits.
You need:
vzbl_live_ and is shown only once.Start read-only. A key holds only the scopes you grant, and
read:*covers every read scope and no write scope. A read-only key cannot run an audit, create a prompt, or spend a credit — the write tools return 403 naming the missing scope. Addwrite:auditsorwrite:promptslater, deliberately.
| Path | Use it when | Setup |
|---|---|---|
| Claude Skill | You work in Claude Code and want slash commands plus the full API reference loaded in context | /plugin install |
| Custom connector | You use claude.ai or Claude Desktop and want 1-click OAuth with no key to store | Paste one URL |
| MCP server | You use Cursor, VS Code, or any other MCP client | One JSON block |
| REST API | You are writing code, a CI job, or a script | curl |
The skill and the MCP server reach the same data by different routes. Skill, MCP, or both? below explains when to pick which.
The skill teaches Claude to call the Vizzybl REST API directly, and ships a full endpoint reference and an OpenAPI spec alongside it.
Claude Code — as a plugin. Add the marketplace once, then install:
/plugin marketplace add vizzybl-ai/claude-plugins
/plugin install vizzybl-geo@vizzybl
Updates arrive automatically — Claude Code checks the marketplace in the background.
Claude Desktop or claude.ai. Upload the packaged skill (.zip) under Settings → Features → Skills, then allow the skill to reach us: turn on Allow network egress and add vizzybl.ai under Domain allowlist → Additional allowed domains. Without that, every request fails with a network error.
Set your key and you are done:
export VIZZYBL_API_KEY="vzbl_live_..."
Five commands cover the common workflows:
| Command | What it does |
|---|---|
/vizzybl-geo:pulse [days] | Week-over-week share of voice, rank, and sentiment |
/vizzybl-geo:answers [topic] | The verbatim AI answers for your prompts, grouped by engine |
/vizzybl-geo:gaps [domain] | Citation gaps — cited domains where yours isn't |
/vizzybl-geo:scorecard [days] | Per-engine visibility breakdown |
/vizzybl-geo:audit <url> | Run a GEO audit — spends credits |
/vizzybl-geo:audit is marked user-invoked only, so Claude can never trigger an audit on its own. Full setup detail lives in Claude Skill.
One remote server exposes 27 tools — reads, workflow recipes, and four metered actions.
https://mcp.vizzybl.ai/v1/mcpClaude Desktop or claude.ai — the custom connector. Go to Settings → Connectors → Add custom connector, paste https://mcp.vizzybl.ai/v1/mcp, and complete the OAuth consent in the browser. No key to copy or store: consent mints a key named MCP: <client> under Settings → API Keys, and revoking it there disconnects the client immediately.
Claude Code. One command, then approve the OAuth prompt:
claude mcp add --transport http vizzybl https://mcp.vizzybl.ai/v1/mcp
Cursor. Add the server to ~/.cursor/mcp.json:
{"mcpServers":{"vizzybl":{"url":"https://mcp.vizzybl.ai/v1/mcp"}}}
VS Code. Add the server to .vscode/mcp.json in your project:
{"servers":{"vizzybl":{"type":"http","url":"https://mcp.vizzybl.ai/v1/mcp"}}}
For a client without OAuth support, or a headless setup, send an API key instead: Authorization: Bearer vzbl_live_....
The tool list, scope requirements, and token lifetimes are in MCP Server.
Every skill and MCP tool is a thin wrapper over the public REST API at https://vizzybl.ai/api/v1. Call it directly from code or CI:
curl -s https://vizzybl.ai/api/v1/stats \
-H "Authorization: Bearer $VIZZYBL_API_KEY"
See API Authentication for keys, scopes, and revocation, and API Endpoints for the full surface.
Point your agent at the index before it starts, so it reads our definitions instead of guessing at them:
| Resource | URL | What it gives an agent |
|---|---|---|
| Documentation index | https://vizzybl.ai/llms.txt | A curated llms.txt index of our concept and methodology pages, each linked to clean markdown |
| Clean markdown mirror | https://vizzybl.ai/api/md/xeTj7LieR96BGNXk8Eh5/{page}.md | Any indexed page as markdown, with no navigation chrome to burn tokens on |
| Blog markdown | https://vizzybl.ai/api/blog/{slug}/md | Any article as markdown; https://vizzybl.ai/rss.xml is the authoritative feed |
Note.
llms.txtindexes the concept pages — what GEO is, how the metrics are calculated, how to read the dashboard. It does not yet index the integration pages, so link those four directly when your agent needs them: Claude Skill, MCP Server, API Authentication, and API Endpoints.
Reading the index first is the cheaper move. It is a few hundred tokens and tells the agent which pages exist, so it fetches two markdown files instead of crawling the HTML docs.
Both reach the same workspace data, so this is about where your agent runs.
Most of the surface is read-only and free. Four actions are not:
| Action | Tool / endpoint | Scope | Cost |
|---|---|---|---|
| Run a GEO audit | run_audit, POST /api/v1/audits | write:audits | Credits, settled when the audit completes |
| Poll an audit | get_audit, GET /api/v1/audits/{auditId} | read:brand | Free |
| Create monitored prompts | create_prompts, POST /api/v1/prompts | write:prompts | Free, up to 50 at a time |
| Re-scrape a prompt | scrape_prompt | write:prompts | Charges prompt_monitor_run |
MCP clients surface a confirmation before any non-read tool runs, and the skill is instructed to state the cost and check your balance with get_quota first. Audits and scrapes are asynchronous: you get an ID back immediately, so a "running…" answer before any score appears is expected, not a failure.
VIZZYBL_API_KEY, or re-authorize the connector.get_quota; retrying will not help.vizzybl.ai is missing from the domain allowlist.