# Spyglasses MCP Server

The 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.

MCP (the [Model Context Protocol](https://modelcontextprotocol.io)) 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.

<Callout>
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](/docs/ai-visibility-guides/chat-with-your-reports). The MCP server is for ongoing, interactive analysis across all of your data.
</Callout>

## 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).
- **Optimize content for citation** — run the score → revise → re-score loop on a page or draft until it's citation-ready.

## Read-only by design

Everything the connector exposes for reporting and analytics is **read-only** — nothing lists here creates, edits, deletes, or spends anything on your account. The one exception is the [Citation Optimizer](/docs/mcp/citation-optimizer) loop, which generates new scoring runs and **draft** rewrites inside your account so you can iterate on content — but it never publishes, edits your live pages, or changes any of your existing data.

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`) | Your organization/property membership | You want to work across your own properties, projects, metrics, and history. |

The public-report tools are covered in [Reports](/docs/mcp/reports); the account-scoped tools start from `list_properties` and run through [Account data](/docs/mcp/account-data), [Scoring](/docs/mcp/scoring), and the [Citation Optimizer](/docs/mcp/citation-optimizer).

## 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](/docs/mcp/prompts) 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) — [full reference](/docs/mcp/reports)

| 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. |
| `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) — [full reference](/docs/mcp/account-data)

| 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, and annotation timeline. |
| `get_metrics_history` | AI visibility metrics over time: share of voice, mentions, citations, per platform. |
| `get_consistency_history` | Brand-consistency score over time, overall and per platform. |
| `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. |
| `get_citation_intelligence` | The mix of sources AI cites over time, with breakdowns and top sources. |

### Scoring — [full reference](/docs/mcp/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. |

### Citation Optimizer — [full reference](/docs/mcp/citation-optimizer)

| Tool | Purpose |
|---|---|
| `list_tracked_fanouts` | A property's real tracked fan-out queries to optimize for. |
| `match_pages_for_fanout` | Rank a property's pages by how well they match a fan-out query. |
| `list_property_pages` | List/search a property's pages to resolve one the user names. |
| `list_placements` / `get_placement` | Find a PR placement and read its content to score. |
| `score_citation_pipeline` | Score a page, URL, or draft for AI citation readiness (fire-and-poll). |
| `get_pipeline_run` | A run's score, per-gate results, and a readiness verdict. |
| `revise_content` / `get_revision` | Generate and fetch a citation-improved draft. |
| `rescore_revision` | Re-score a revision to measure improvement and close the loop. |

## Get started

<Steps>

<Step>
**[Connect the server](/docs/mcp/setup)** to your assistant and sign in with your Spyglasses account.
</Step>

<Step>
**Start from a [prompt](/docs/mcp/prompts)** — e.g. "List my organization's reports" or "Track message drift" — or ask a question directly.
</Step>

<Step>
**Drill in with tools** as the conversation gets specific. The reference pages document every parameter.
</Step>

</Steps>

## Related

- [Chat with your reports](/docs/ai-visibility-guides/chat-with-your-reports) — the instant, one-shot way to put a single report in front of an assistant
- [API access](/docs/api) — the REST API for programmatic, code-driven integrations
- [Setup](/docs/mcp/setup) — connect the server and complete OAuth