Spyglasses MCP Server
Ask ChatGPT
Ask Claude
Ask Perplexity
Ask CopilotThe Spyglasses MCP server turns your Spyglasses account into a set of tools that AI assistants can call directly. Instead of copying data out of the dashboard, you connect an assistant once and then ask it questions in plain language — "how has my share of voice trended this quarter?", "which publishers are worth pitching?", "make this page more citable" — and it fetches the exact data it needs on demand.
Product overview: The Spyglasses MCP server — what you can query and why it's read-only.
MCP (the Model Context Protocol) is an open standard for connecting AI assistants to external tools and data. Any MCP-capable assistant — Claude, ChatGPT, Claude Code, and others — can use the Spyglasses connector.
Looking for the quick, one-shot version? To simply drop a single report into an assistant chat, use the Chat with this report buttons on any shared report — see Chat with your reports. The MCP server is for ongoing, interactive analysis across all of your data.
What you can do with it
Once connected, an assistant can:
- Read any Spyglasses report — pull the full AI Visibility report or Site Readiness audit behind a share link, including grounding gaps, citation breakdowns, and recommendations.
- Work across your whole account — list your organizations, properties, and projects; chart historical metrics; track how AI's description of your brand drifts over time.
- Score publishers and placements — evaluate any domain's AI Placement Value Score (AIPVS) or a prospective placement's AI Placement Quality Score (PQS).
- Bulk-score real coverage — paste a list of earned-media URLs with the brand each one is about and get a scored table back, for any brand, tracked or not.
- Optimize content for citation — run the score → revise → re-score loop on a page or draft until it's citation-ready, across several AI assistants at once.
- Brief a page before it's written — turn a keyword into a section-by-section writer brief built on the searches your assistants really run.
Read-only, with a short list of exceptions
Everything the connector exposes for reporting and analytics is read-only — nothing there creates, edits, deletes, or spends anything on your account. The tools below write, all of them inside your own account, and none of them publishes anything or touches your live pages:
| Tool | What it writes | Cost |
|---|---|---|
score_citation_audit / score_citation_pipeline / rescore_revision | A citation scoring run in your account. | Free of credits; counts against a monthly page allowance (a page counts once a month, and re-scoring a rewrite never counts) |
reweight_citation_audit | The platform weighting saved on one of your audits. | Free |
revise_citation_audit / revise_content | A draft rewrite (never published, never applied to a live page). | Spends credits |
generate_citation_outline | A keyword brief in your account. | Spends credits |
score_placement_urls | A coverage group, a hidden scoring-only brand record for any brand you name that your organization doesn't already track, and one placement per (brand, URL) — then fetches each page and runs the classifiers. | Free today; a monthly cap applies where one is configured |
add_pitch_list_publishers | Rows on one of your pitch lists, creating the list first if you name a new one, plus a publisher record for any domain Spyglasses hasn't seen yet. New publishers are queued for enrichment: traffic and logo within minutes, Domain Rank within a few hours. | Free; spends no credits |
Everything else creates, edits and spends nothing.
Access is scoped to what you can already see: you sign in with your own Spyglasses account (via OAuth), and every account tool checks your membership of the relevant organization or property before returning anything.
Two surfaces
The connector exposes two distinct surfaces. Which tools you reach for depends on what you have in hand:
| Surface | Identified by | Access | Use it when |
|---|---|---|---|
| Public reports | A report's public token (from a share URL) | Anyone with the token | You want to analyze a single shared AI Visibility report or Site Readiness audit — yours or someone else's. |
| Your account data | A propertyId (from list_properties), or an organizationId (from list_my_organizations) for bulk placement scoring and organization pitch lists | Your organization/property membership | You want to work across your own properties, projects, metrics, and history — or score coverage for brands that aren't properties at all. |
The public-report tools are covered in Reports; the account-scoped tools start from list_properties and run through Account data, Scoring, and the Citation Optimizer. Bulk placement scoring and organization-level pitch lists are the organization-scoped surfaces: they start from list_my_organizations instead, because the brands they score against need not be properties on your account.
Prompts vs. tools
The server exposes two kinds of things:
- Tools are the low-level primitives — one call fetches one slice of data (
get_metrics_history,score_publisher_value, and so on). - Prompts are task-oriented starting points that show up in your assistant's prompt or slash menu. Each one orchestrates the right sequence of tool calls for a complete task — "Analyze a report", "What should I fix first?", "Track message drift". They're the recommended way to begin.
Start from a prompt when one fits your task; drop down to individual tools when you want something specific.
Tool catalog
Every tool the server exposes, grouped by the page that documents it:
Reports (public token)
| Tool | Purpose |
|---|---|
get_ai_visibility_report | Full AI Visibility report: share of voice, citations, per-platform breakdown, recommendations. |
get_ai_visibility_grounding | Every grounding gap, ranked — searches where competitors rank but the brand doesn't, plus the site:-scoped searches reported separately as authority evidence. |
get_ai_visibility_citations | Citation breakdown by media type, authority, format, and page, plus most-cited pages. |
get_ai_visibility_recommendations | Role-categorized recommendations (SEO/AEO, PR, technical, brand consistency). |
get_site_audit_summary | AI Site Readiness audit summary: overall + per-dimension scores, priority issues. |
list_site_audit_pages | List a site audit's analyzed pages (paginated, sortable, filterable). |
get_site_audit_page | Full per-page audit detail: dimension scores, findings, chunk/citation readiness. |
list_my_organizations | The organizations you belong to, and your role in each. |
list_reports | An organization's reports and audits, with their public tokens. |
Account data (property)
| Tool | Purpose |
|---|---|
list_properties | The properties on your account — the entry point for every account tool. |
list_projects | A property's projects (time-bound tracking efforts) with status and goals. |
get_project_insights | A project's metric deltas, weekly trend, goals with hit counts and influence rates, and annotation timeline. |
get_metrics_history | AI visibility metrics over time: share of voice, mentions, citations, per platform. Brand-wide, or sliced by stage, platform, prompt tag, project or tracked market. |
list_prompt_tags | The tags, categories, and use-cases on a property's prompts — the vocabulary for every theme-scoped slice. |
get_answer_drilldown | One day explained: the raw prompt text, which brands each answer named, on which platform and model, with an optional brand lens and the full answer text for one prompt. |
get_site_consultations | Which sites AI consulted directly with a site: search — yours, a competitor's, a third party's — window vs previous window, with suspected wrong domains flagged. |
list_locations | Per-market share of voice for a brand's tracked locations, with an equal-weighted rollup. |
get_competitor_share_of_voice | Ranked share of answers for the brands AI names, pooled over a 7/30/90-day window and sliceable by stage, platform, prompt tag, project or market, with gap prompts and an optional per-day series. Every focal-subject figure is null for CATEGORY properties, which track a market with no focal brand; rank the brands only. |
get_recommendation_categories | How AI recommends your brand and every other brand it names in daily tracking answers: top choice, one of many, generic mention or cautioned against, with Share of recommendation across the market, the reasons AI steers buyers away, and who AI says you are best for. Pass a persona to read the answers asked as that buyer. |
list_personas | A property's buyer personas: role, company, tech stack, priorities and constraints, the exact context sent in front of each question, and the projects each is on. |
get_persona_lens | How AI answers each buyer persona (or a group sharing a role, segment, company size or seniority) compared with the baseline over the same prompts and platforms: mention, top-choice, recommended and cautioned rates with intervals, plus who AI recommends to that buyer. |
get_consistency_history | Brand-consistency score over time, overall and per platform. |
get_brand_prompt_health | Per-prompt health for brand/comparison prompts: expected-message coverage, unwanted-message incidence, theme drift. |
get_comparison_verdicts | Head-to-head outcomes from comparison prompts: who's favored, verdict shapes, strengths/weaknesses per brand. |
get_message_tracking | Key-message pull-through rate into AI answers over time. |
get_answer_summaries | The full weekly answer text for one tracked query, to narrate message drift, with the candidate prompts narrowable by tag, stage, project or market. |
get_citation_intelligence | The mix of sources AI cites over time, with breakdowns, top sources, the cited-vs-evaluated split, and earned-media content mentions. |
get_coverage_citations | The AI citations a coverage group's placement URLs earned: funnel, cited-vs-uncited comparison, and per-citation hits with the prompt, platform, and answer-text context. |
get_project_goal_citations | The citations behind a project goal's hit count, each classified by brand relevance (attributed / mentions brand in content / unrelated), with a hidden-earned-media breakdown. |
Scoring
| Tool | Purpose |
|---|---|
score_publisher_value | AI Placement Value Score (AIPVS) for one or more publisher domains. |
score_placement_quality | AI Placement Quality Score (PQS) for a prospective placement, optionally × AIPVS. |
Placement scoring (organization)
| Tool | Purpose |
|---|---|
score_placement_urls | Bulk-score earned-media URLs against any brand, tracked or not. Writes: creates a coverage group, a hidden scoring-only brand record per untracked brand, and one placement per (brand, URL). Fire-and-poll. |
get_coverage_group | The poll target: a group's items with brand, placement status, PQS + tier, and optional AIPVS, plus per-status counts and a done flag. |
list_coverage_groups | An organization's coverage groups — cross-brand scoring batches by default, per-client coverage groups on request. |
Pitch lists
| Tool | Purpose |
|---|---|
list_pitch_lists | A property's pitch lists, or an organization's organization-level lists. |
get_pitch_list | One pitch list's rows: publisher, Est. Traffic, Domain Rank, status, note, AI citation counts for a 30, 90 or 365-day window, Placed suggestions, and optionally AIPVS. |
add_pitch_list_publishers | Add publisher domains to a pitch list, creating the list if needed. Writes: list rows and new publisher records, queued for enrichment. Spends no credits. |
Citation Optimizer
| Tool | Purpose | Cost |
|---|---|---|
list_tracked_fanouts | A property's real tracked fan-out queries to optimize for. site:-scoped queries and queries naming a competitor but not this brand are excluded by default (evidence only — they can never be scored); includeSiteScoped: true / includeCompetitorNamed: true show them. Comparison queries naming both brands are always included. | Free |
match_pages_for_fanout | Rank a property's pages by how well they match a query. | Free |
list_property_pages | List/search a property's pages to resolve one the user names. | Free |
list_placements / get_placement | Find a PR placement and read its content to score. | Free |
score_citation_audit | Start here. Score a page, URL, or draft against a whole query set on every assistant your plan covers (fire-and-poll). | Free of credits; uses one page of the monthly allowance |
get_citation_audit | The poll target: combined score with its range, each assistant's checks, the merged recommendation list, and the readiness verdict with its STOP rules. | Free |
reweight_citation_audit | Change how much each assistant counts and recompute the score and verdict. | Free |
revise_citation_audit / get_revision | Generate and fetch a rewrite grounded in every assistant's findings at once. | Spends credits |
rescore_revision | Re-score a revision to measure improvement and close the loop — as a child audit, or as a run when that's what it came from. | Free |
generate_citation_outline / get_citation_outline | Turn a keyword into a section-by-section writer brief, before the page exists. | Spends credits |
score_citation_pipeline / get_pipeline_run | The single-query, ChatGPT-only shape of scoring. Still supported; the free plan's shape. | Free of credits; uses one page of the monthly allowance |
revise_content | Rewrite from a single run's findings. | Spends credits |
Get started
Connect the server to your assistant and sign in with your Spyglasses account.
Start from a prompt — e.g. "List my organization's reports" or "Track message drift" — or ask a question directly.
Drill in with tools as the conversation gets specific. The reference pages document every parameter.
Related
- Chat with your reports — the instant, one-shot way to put a single report in front of an assistant
- API access — the REST API for programmatic, code-driven integrations
- Setup — connect the server and complete OAuth