Connecting the MCP server

View MarkdownAsk ChatGPT Ask Claude Ask Perplexity Ask Copilot

The Spyglasses MCP server lives at a single URL:

https://www.spyglasses.io/api/mcp

Add it as a custom connector in your assistant, then complete the one-time sign-in. After that, the assistant can call Spyglasses tools whenever it needs data.

Authentication (OAuth)

The connector authenticates with OAuth — the same account you use to sign in to the Spyglasses dashboard. The first time you add it, your assistant opens a browser window to sign in and authorize the connection. There's no API key to copy or paste.

Signing in this way means every tool runs as you:

Account tools (list_properties, get_metrics_history, and so on) only return data for organizations and properties you're a member of.
Public-report tools work with any report's public token — they're shareable by design.

The REST API uses a per-property API key instead, and is meant for code-driven integrations. The MCP server uses OAuth and is meant for interactive use inside an AI assistant. They're separate access paths — you don't need an API key to use the MCP.

Setup by assistant

Install the Spyglasses plugin. It wires up the connector and a skill that teaches the assistant how to read Spyglasses reports:

/plugin marketplace add orchestra-code/spyglasses-skills
/plugin install spyglasses@spyglasses-skills

The first tool call triggers the OAuth sign-in flow in your browser.

The Chat with this report buttons on a shared report cannot connect an MCP for you. Assistant connectors are added once, manually, in your assistant's own settings. The buttons are for instant one-shot chats; the MCP is for ongoing, interactive analysis. See Chat with your reports.

How access is scoped

There are two ways a tool decides what you're allowed to see:

Public token. Report tools take a publicToken from a share URL. Anyone holding the token can read that report — that's the point of sharing it. (An AI Visibility report must be unlocked to return data; a locked report returns an error.)
Membership. Account tools take an organizationId or propertyId. Before returning anything, the server checks that your signed-in account is a member. If you're not, you get an access error rather than data.

Because access mirrors your account, the safest way to start is list_my_organizations / list_properties — the assistant discovers exactly what you have access to, then works within it.

Working with your data

A typical account session starts by discovering IDs, then drilling in:

Find your properties. list_properties returns each property's id, domain, organization, and your role.

Pick a surface. Pass a propertyId to the account-data tools for trends and history, or to the scoring and citation optimizer tools for evaluation and content work.

Ask for a chart. Many tools return numeric series over time. Assistants build the visualization from that data — just ask for "a chart of share of voice over the last quarter."

Troubleshooting

"You are not signed in." The OAuth session hasn't completed or has expired. Re-run the connector's sign-in prompt in your assistant's connector settings.

"You are not a member of that organization / property." You passed an organizationId or propertyId you don't have access to. Call list_my_organizations or list_properties to see the IDs you can use.

"This AI Visibility report has not been unlocked yet." The report behind that public token is still locked. Unlock it in the dashboard, then retry.

OAuth won't complete / connector shows an error. Make sure you entered the full URL including /api/mcp. If your client caches connector metadata, remove and re-add the connector so it re-runs discovery against https://www.spyglasses.io.

MCP overview — what the server is and the full tool catalog
Prompts — guided starting points in your assistant's prompt menu
Chat with your reports — the instant, one-shot alternative