> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siteline.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Connect your AI tools to Siteline using MCP

<Note>
  The MCP server is currently in **beta** and available on paid plans only. To activate it for your
  team, contact us at [team@siteline.ai](mailto:team@siteline.ai).
</Note>

The Model Context Protocol (MCP) is a standard for connecting Large Language Models (LLMs) to platforms like Siteline. Once connected, your AI assistants can query Siteline prompt and agent analytics on your behalf.

## MCP installation

<Steps>
  <Step title="Follow our security best practices">
    Before connecting the MCP server, read the [security risks](#security-risks) section to understand what to review before giving an AI tool access to Siteline analytics.
  </Step>

  <Step title="Configure your AI tool">
    Choose your Siteline team and MCP client, then follow the installation instructions below.
  </Step>
</Steps>

### Installation

<Tabs>
  <Tab title="Codex">
    Add the MCP server with:

    ```bash theme={null}
    codex mcp add siteline --url https://mcp.siteline.ai/mcp
    ```
  </Tab>

  <Tab title="Claude Code">
    Add the MCP server with:

    ```bash theme={null}
    claude mcp add --transport http siteline https://mcp.siteline.ai/mcp
    ```

    Then authenticate from Claude Code:

    ```text theme={null}
    /mcp
    ```
  </Tab>

  <Tab title="Claude">
    In Claude or Claude Desktop, open **Settings** > **Connectors**, then add a custom connector:

    ```text theme={null}
    Name: Siteline
    URL: https://mcp.siteline.ai/mcp
    ```

    After saving the connector, use Claude's connector authentication flow to log in to Siteline
    and approve read-only analytics access for your team.
  </Tab>

  <Tab title="Cursor">
    In Cursor, add Siteline as a remote MCP server from **Settings** > **Tools & Integrations** >
    **MCP**, or add this project configuration to `.cursor/mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "siteline": {
          "url": "https://mcp.siteline.ai/mcp"
        }
      }
    }
    ```

    Cursor will open the OAuth flow when it first connects or when you run a Siteline tool.
  </Tab>

  <Tab title="JSON">
    Alternatively, add this configuration to `.mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "siteline": {
          "type": "http",
          "url": "https://mcp.siteline.ai/mcp"
        }
      }
    }
    ```
  </Tab>
</Tabs>

After configuring the MCP server, authenticate using your MCP client's authentication flow.

##### Authentication

Some MCP clients automatically prompt you to log in during setup, while others require manual authentication steps. Authentication opens a browser window where you log in to Siteline and grant read-only analytics access for the selected team.

<Info>
  Siteline MCP does not require you to generate or paste a public API key into the MCP client.
</Info>

### Next steps

After you log in, check that the MCP server is connected. Depending on the client, you may need to restart it to connect and detect all tools after authorization.

To verify the client has access to the MCP server tools, ask it to query Siteline using natural language. For example: "Summarize prompt performance for my product using Siteline MCP."

## How the MCP server works

Siteline MCP is a hosted, read-only MCP server available at:

```text theme={null}
https://mcp.siteline.ai/mcp
```

MCP clients connect over Streamable HTTP at `POST /mcp` and authenticate with browser-based OAuth 2.0 Authorization Code with PKCE. During authorization, Siteline asks you to choose the team whose analytics the client can read. The MCP access token is then resolved on the server side to that team's Siteline public API access; the token and public API key are never passed as tool arguments.

After authorization, the server exposes tools that proxy Siteline's public product analytics API. Product-scoped tools can discover the available product and website for the connection. When a request is underspecified, the tool returns `structuredContent.selectionRequired` with choices the client should show to you before retrying the same tool.

The server asks for a selection when:

* More than one product is available and `productId` was omitted
* More than one website is available and `domain` was omitted
* `dateFrom` or `dateTo` is omitted
* A prompt-performance tool needs one or more platforms

Missing date ranges return the same presets used in the app: `7D`, `30D`, `3M`, `6M`, `12M`, plus `Custom` for explicit RFC3339 `dateFrom` and `dateTo` values.

## Available tools

The Siteline MCP server exposes seven read-only tools for product discovery, prompt analytics, citations, and agent analytics traffic.

| Tool                                   | Use it to                                                                                          |
| -------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `list_products`                        | List authorized primary products, product IDs, and domains for the MCP connection.                 |
| `list_product_websites`                | List active website domains and website IDs for a product.                                         |
| `list_product_tracked_prompts`         | List tracked prompt rows with platform, domain, position, visibility, rank, run count, and labels. |
| `summarize_product_prompt_performance` | Summarize aggregate prompt visibility, position, rank, and competitor count.                       |
| `analyze_product_prompt_trends`        | Analyze daily prompt visibility, position, and rank trends.                                        |
| `list_product_citations`               | List citation source pages, source domains, or mentioned products.                                 |
| `analyze_product_analytics_timeseries` | Analyze AI crawler and referred human traffic timeseries.                                          |

<CardGroup cols={2}>
  <Card title="Product discovery" icon="search">
    Use `list_products` and `list_product_websites` first when you do not know which
    `productId` or domain the MCP connection can access.
  </Card>

  <Card title="Prompt performance" icon="chart-no-axes-combined">
    Use `list_product_tracked_prompts`, `summarize_product_prompt_performance`, and
    `analyze_product_prompt_trends` to inspect visibility, rank, position, and competitors.
  </Card>

  <Card title="Citations" icon="link">
    Use `list_product_citations` to inspect top cited pages, citation source domains, or mentioned
    products.
  </Card>

  <Card title="Agent analytics" icon="activity">
    Use `analyze_product_analytics_timeseries` to inspect AI crawler traffic and referred
    human traffic over time.
  </Card>
</CardGroup>

### `list_products`

Use this discovery tool when you do not know which Siteline products the authorized MCP connection can read.

**Prompt input example:** "Which Siteline products can this MCP connection access?"

**Tool input:** none.

```json theme={null}
{}
```

**Expected return:** `structuredContent.products`, an array of products.

Each product includes:

* `id`: Product ID to pass as `productId` to product-scoped tools
* `name`: Product name
* `website`: Product website URL
* `domain`: Primary domain
* `partnerWebsites`: Website domains and website IDs linked to the product

### `list_product_websites`

Use this discovery tool when you know a `productId` and need the active website domains attached to that product.

**Prompt input example:** "Which websites belong to product 6330?"

**Tool input:**

<ResponseField name="productId" type="number" required>
  Siteline product ID returned by `list_products`.
</ResponseField>

**Expected return:** `structuredContent.websites`, an array of product websites.

Each website includes:

* `domain`: Bare hostname, such as `example.com`
* `websiteId`: Website ID used internally for product analytics

### `list_product_tracked_prompts`

Use this prompt-performance tool to inspect individual tracked prompt rows for a product, website, date range, and platform set.

**Prompt input example:** "List tracked prompts for product 6330 on `example.com` for the last 30 days on ChatGPT and Gemini."

**Tool input:**

<ResponseField name="productId" type="number">
  Siteline product ID. Omit it only when the MCP server should auto-select the only available
  product or ask you to choose one.
</ResponseField>

<ResponseField name="domain" type="string">
  Bare hostname, such as `example.com`. Omit it only when the MCP server should auto-select the only
  available website or ask you to choose one.
</ResponseField>

<ResponseField name="dateFrom" type="string">
  Inclusive RFC3339 timestamp. If omitted, the tool asks you to choose a preset or provide a custom
  range.
</ResponseField>

<ResponseField name="dateTo" type="string">
  Inclusive RFC3339 timestamp. Must be after `dateFrom`; date windows can be up to 366 days.
</ResponseField>

<ResponseField name="platforms" type="string[]">
  One or more of `chatgpt`, `perplexity`, `google`, `google_ai_overviews`, `google_ai_mode`,
  `gemini`, `chatgpt_impl1`, or `claude`. If omitted, the tool asks you to choose one or more
  platforms.
</ResponseField>

<ResponseField name="labelIds" type="number[]">
  Optional prompt label IDs to filter results.
</ResponseField>

**Expected return:** `structuredContent.prompts`, an array of tracked prompt rows.

Each row includes:

* `promptText`: The tracked prompt text
* `platform`: Platform that produced the row
* `domain`: Product domain used for the metric
* `position`: Average position of the product within AI response text for this prompt. For example, a position of 1 means it was mentioned first. `null` when no data is available.
* `visibility`: Percentage of AI responses in which the product appears for this prompt, expressed as a decimal (e.g. `0.42` = 42%). `null` when no data is available.
* `rank`: Product's ranking by visibility compared to all products appearing in this prompt's results. A rank of 1 means highest visibility. `null` when no data is available.
* `runCount`: Number of prompt runs recorded in the selected period, or `null` when unavailable
* `labels`: Applied prompt labels with `id` and `name`

### `summarize_product_prompt_performance`

Use this prompt-performance tool when you want one aggregate summary across a product, website, date range, and platform set.

**Prompt input example:** "Summarize prompt performance for product 6330 on `example.com` over the last 30 days."

**Tool input:** same as `list_product_tracked_prompts`: `productId`, `domain`, `dateFrom`, `dateTo`, optional `platforms`, and optional `labelIds`.

**Expected return:** `structuredContent.summary`, a single prompt summary object.

The summary includes:

* `position`: Average position of the product within AI response text across all matching prompts. `null` when no data is available.
* `visibility`: Aggregate percentage of AI responses in which the product appears across all matching prompts, expressed as a decimal. `null` when no data is available.
* `rank`: Product's ranking by visibility compared to all competing products across matching prompts. `null` when no data is available.
* `totalCompetitors`: Total number of distinct competitor products appearing across matching prompt results.

### `analyze_product_prompt_trends`

Use this prompt-performance tool when you want daily trend rows for visibility, position, and rank.

**Prompt input example:** "Show daily Gemini prompt visibility trends for product 6330 on `example.com` in April 2026."

**Tool input:** same as `list_product_tracked_prompts`: `productId`, `domain`, `dateFrom`, `dateTo`, optional `platforms`, and optional `labelIds`.

**Expected return:** `structuredContent.trends`, an array of daily prompt trend rows.

Each row includes:

* `date`: Trend date
* `platform`: Platform for the row
* `domain`: Product domain used for the metric
* `visibility`: Percentage of AI responses in which the product appears on this day, expressed as a decimal. `null` when no data is available.
* `position`: Average position of the product within AI response text on this day. `null` when no data is available.
* `rank`: Product's ranking by visibility compared to all competing products on this day. `null` when no data is available.

### `list_product_citations`

Use this citation tool to inspect where a product is cited, which source domains cite it, or which products are mentioned in answers.

**Prompt input example:** "List top cited pages for product 6330 on `example.com` over the last 30 days."

**Tool input:**

<ResponseField name="productId" type="number">
  Siteline product ID. Omit it only when the MCP server should auto-select the only available
  product or ask you to choose one.
</ResponseField>

<ResponseField name="domain" type="string">
  Bare hostname, such as `example.com`. Omit it only when the MCP server should auto-select the only
  available website or ask you to choose one.
</ResponseField>

<ResponseField name="dateFrom" type="string">
  Inclusive RFC3339 timestamp. If omitted, the tool asks you to choose a preset or provide a custom
  range.
</ResponseField>

<ResponseField name="dateTo" type="string">
  Inclusive RFC3339 timestamp. Must be after `dateFrom`; date windows can be up to 366 days.
</ResponseField>

<ResponseField name="platforms" type="string[]">
  Optional platform filters. Supported values are `chatgpt`, `perplexity`, `google`,
  `google_ai_overviews`, `google_ai_mode`, `gemini`, `chatgpt_impl1`, and `claude`.
</ResponseField>

<ResponseField name="labelIds" type="number[]">
  Optional prompt label IDs to filter citations.
</ResponseField>

<ResponseField name="groupBy" type="string">
  `page`, `property`, or `product`. Defaults to `page`.
</ResponseField>

**Expected return:** `structuredContent.citations`, grouped according to `groupBy`.

When `groupBy` is `page`, the return includes `byPage` rows with:

* `domain`: Citation source domain
* `url`: Citation source page URL
* `products`: Mentioned products with `name` and `domain`
* `count`: Citation count
* `isMentioned`: Whether the selected product is mentioned

When `groupBy` is `property`, the return includes `byProperty` rows with source `domain`, mentioned `products`, `count`, and `isMentioned`.

When `groupBy` is `product`, the return includes `byProduct` rows with product `name`, product `domain`, `count`, and `isMentioned`.

### `analyze_product_analytics_timeseries`

Use this agent analytics tool to inspect AI crawler traffic and referred human traffic for product-owned websites over time.

**Prompt input example:** "Show weekly OpenAI bot visits and AI-referred human visits for product 6330 over the last 30 days."

**Tool input:**

<ResponseField name="productId" type="number">
  Siteline product ID. Omit it only when the MCP server should auto-select the only available
  product or ask you to choose one.
</ResponseField>

<ResponseField name="dateFrom" type="string">
  Inclusive RFC3339 timestamp. If omitted, the tool asks you to choose a preset or provide a custom
  range.
</ResponseField>

<ResponseField name="dateTo" type="string">
  Inclusive RFC3339 timestamp. Must be after `dateFrom`; date windows can be up to 366 days.
</ResponseField>

<ResponseField name="interval" type="string">
  `day` or `week`. Defaults to `day`.
</ResponseField>

<ResponseField name="metrics" type="string[]">
  Optional metrics: `bot_visits`, `human_visits`, `referred_human_visits`,
  `ai_referred_human_visits`, `unique_human_visitors`, `unique_pages`, `unique_human_pages`,
  `unique_human_platforms`, or `bot_user_agents`.
</ResponseField>

<ResponseField name="groupBy" type="string[]">
  Optional dimensions: `platform`, `botType`, `urlPath`, `normalizedUrlPath`, or `urlPathDirectory`.
</ResponseField>

<ResponseField name="platforms" type="string[]">
  Optional platform filters, such as `openai`.
</ResponseField>

<ResponseField name="botTypes" type="string[]">
  Optional bot type filters, such as `chatgpt-user`.
</ResponseField>

<ResponseField name="urlPath" type="string">
  Optional normalized URL path filter.
</ResponseField>

<ResponseField name="websiteId" type="string">
  Optional website ID returned by `list_product_websites`. If omitted, analytics are returned across
  all active websites for the product.
</ResponseField>

<ResponseField name="page" type="number">
  Result page. Defaults to `1`.
</ResponseField>

<ResponseField name="perPage" type="number">
  Rows per page. Defaults to `20`; maximum is `500`.
</ResponseField>

<ResponseField name="topLimit" type="number">
  Optional top-N row limit per time bucket, ordered by the first requested metric.
</ResponseField>

**Expected return:** `structuredContent.timeseries`, a paginated timeseries result.

The timeseries result includes:

* `previousPage`, `currentPage`, `nextPage`, `totalPages`, `totalItems`, and `perPage`
* `items`: Timeseries rows with optional dimensions like `platform`, `botType`, `urlPath`, `normalizedUrlPath`, and `timestamp`
* Metric fields such as `botVisits`, `humanVisits`, `referredHumanVisits`, `aiReferredHumanVisits`, `uniqueHumanVisitors`, `uniquePages`, `uniqueHumanPages`, `uniqueHumanPlatforms`, and `botUserAgents`

## Configuration options

<Info>
  The Siteline MCP server does not currently expose URL query configuration options. Access is
  read-only and scoped through OAuth to the Siteline team you authorize.
</Info>

## Manual authentication

<Info>
  The Siteline MCP server uses dynamic client registration and browser-based OAuth. Manual public
  API key authentication is not supported for MCP clients.
</Info>

## Security risks

Connecting any data source to an LLM carries inherent risks. Siteline MCP is read-only, but AI tools can still retrieve and summarize analytics data that your team has access to.

### Prompt injection

<Warning>
  Prompt injection can trick an AI assistant into treating untrusted content as instructions. Review
  MCP tool calls before allowing them, especially in clients that can run tools automatically.
</Warning>

### Recommendations

* Review tool calls before approving them
* Connect only MCP clients you trust
* Use a Siteline team with the minimum data access needed
* Remove the MCP server from clients that no longer need access
* Revoke or reconnect the MCP client if you suspect a client token was exposed