# Connecting the MCP server

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](/app). 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.

<Callout>
The [REST API](/docs/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.
</Callout>

## Setup by assistant

<Tabs items={["Claude Code", "Claude.ai", "ChatGPT", "Other assistants"]}>

<Tab value="Claude Code">

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.

</Tab>

<Tab value="Claude.ai">

1. Open **Settings → Connectors** (or **Feature preview → Connectors**, depending on your plan).
2. Choose **Add custom connector**.
3. Enter the URL `https://www.spyglasses.io/api/mcp`.
4. Complete the sign-in (OAuth) prompt with your Spyglasses account.

</Tab>

<Tab value="ChatGPT">

1. Go to **Settings → Connectors** and add a custom / developer connector.
2. Enter the URL `https://www.spyglasses.io/api/mcp`.
3. Complete the sign-in (OAuth) prompt with your Spyglasses account.

The exact menu names vary by ChatGPT plan and whether custom connectors are enabled for your workspace.

</Tab>

<Tab value="Other assistants">

Any MCP-capable client can connect. Add `https://www.spyglasses.io/api/mcp` as a **Streamable HTTP** MCP server and complete the OAuth sign-in. The server supports OAuth discovery (RFC 8414 / protected-resource metadata), so compliant clients handle the handshake automatically.

</Tab>

</Tabs>

<Callout type="warn">
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](/docs/ai-visibility-guides/chat-with-your-reports).
</Callout>

## 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:

<Steps>

<Step>
**Find your properties.** `list_properties` returns each property's `id`, domain, organization, and your role.
</Step>

<Step>
**Pick a surface.** Pass a `propertyId` to the [account-data](/docs/mcp/account-data) tools for trends and history, or to the [scoring](/docs/mcp/scoring) and [citation optimizer](/docs/mcp/citation-optimizer) tools for evaluation and content work.
</Step>

<Step>
**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."
</Step>

</Steps>

## 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`.

## Related

- [MCP overview](/docs/mcp) — what the server is and the full tool catalog
- [Prompts](/docs/mcp/prompts) — guided starting points in your assistant's prompt menu
- [Chat with your reports](/docs/ai-visibility-guides/chat-with-your-reports) — the instant, one-shot alternative