MCP Server

Beta: The Pierview MCP server is in active development. Exact tool names, parameters, and response formats may evolve over time.

Overview

The Pierview MCP server lets AI tools like Claude Desktop and Claude Code query your AI visibility data directly. Ask questions about your citations, key metrics, and competitor mentions without leaving your workflow. You can also read and edit your brand kit — have Claude structure your brand guidelines and save them back to Pierview. Authentication is secured using OAuth with OIDC with PKCE.

Prerequisites

A Pierview account with an active subscription

Setup

Claude Desktop
Claude Code
Agent SDK

Open Claude Desktop settings

Go to Claude Desktop > Customize > Connectors > + > Add custom connector.

Add the MCP server

Add the following details as prompted:

Name: Pierview
Remote MCP Server URL: https://mcp.pierview.ai

Authenticate

Click the Connect button, follow the authentication steps which will request access to your Pierview data on behalf of Claude.

Add the MCP server

Run the following command in your terminal:

claude mcp add pierview --transport http https://mcp.pierview.ai

Start Claude Code

Run claude in your terminal. You will be prompted to sign in with your Pierview account on first use.

Authenticate

Run the /mcp command in your Claude Code instance. This will allow you to select the pierview mcp server. On authentication, it’ll prompt you to login via the browser.

Use Anthropic’s Claude Agent SDK to build custom AI agents that query your Pierview data programmatically. Requires a Pierview API key and an Anthropic API key.

Activating your API token

Go to your organization settings at https://www.pierview.ai/dashboard/configuration and create an API key. This will be used to authenticate your requests.

Install the Agent SDK

npm install @anthropic-ai/claude-agent-sdk

Set your Anthropic API key

export ANTHROPIC_API_KEY="your-anthropic-api-key"

Run your agent

import { query } from "@anthropic-ai/claude-agent-sdk";
const prompt = `You are a content strategist analyzing AI search visibility data.

1. Call list_organizations to find available organizations.
2. For the organization found, pull all data:
   - get_key_metrics
   - get_citations_by_host
   - get_citations_by_page
   - get_visibility_timeseries
   - get_competitor_llm_breakdown
3. Synthesize the data into a content strategy report.`;

async function main() {
  for await (const message of query({
    prompt,
    options: {
      mcpServers: {
        pierview: {
          type: "http",
          url: "https://mcp.pierview.ai/api-key",
          headers: {
            Authorization: "Bearer YOUR_PIERVIEW_API_KEY",
          },
        },
      },
      allowedTools: ["mcp__pierview__*"],
    },
  })) {
    const msg = message as any;

    if (msg.type === "assistant" && Array.isArray(msg.content)) {
      for (const block of msg.content) {
        if (block.type === "text") {
          console.log(block.text);
        } else if (block.type === "tool_use") {
          console.log(`[tool] ${block.name}(${JSON.stringify(block.input)})`);
        }
      }
    }

    if (msg.type === "result" && msg.subtype === "success") {
      console.log(msg.result);
    }
  }
}

main().catch(console.error);

Available Tools

All data tools accept an optional organizationId parameter. If omitted, your default organization is used. Call list_organizations first to see your available organizations.

`list_organizations`

List all organizations you have access to. Call this first to discover available organization IDs. Parameters: None Returns: Array of organizations with organizationId, organizationName, workspaceName, and role.

`get_key_metrics`

Get mention rate, average ranking, and share of voice for your organization (same as the Key Metrics cards on the dashboard). The previous period of equal length is computed automatically for comparison. Parameters:

Parameter	Type	Required	Description
`startDate`	`string`	No	Start of the window in `YYYY-MM-DD` format. Defaults to 14 days before `endDate`
`endDate`	`string`	No	End of the window in `YYYY-MM-DD` format. Defaults to today. If both dates omitted, uses the past 14 days
`organizationId`	`number`	No	Organization to query (defaults to your default org)

Returns:

Field	Type	Description
`mention_rate`	`number \| null`	Percentage of LLM responses that mention your organization
`average_ranking`	`number \| null`	Mean ranking position when mentioned (lower is better)
`share_of_voice`	`number \| null`	Your mentions as a percentage of all competitor mentions

`get_citations_by_host`

Get top cited hosts/domains with citation counts and per-LLM breakdown. The previous period of equal length is computed automatically for comparison. Parameters:

Parameter	Type	Required	Description
`limit`	`number`	No	Max hosts to return (default 50, max 500; the dashboard API caps at 200)
`startDate`	`string`	No	Start of the window in `YYYY-MM-DD` format. Defaults to 14 days before `endDate`
`endDate`	`string`	No	End of the window in `YYYY-MM-DD` format. Defaults to today. If both dates omitted, uses the past 14 days
`granularity`	`string`	No	`week` (default) compares this week vs last week; `month` compares calendar months. Ignored when both dates set
`cumulativeAsOf`	`string`	No	When set (`YYYY-MM-DD`), adds `cumulative_current`/`cumulative_previous` (all citations ever up to that date vs end of the prior calendar month)
`organizationId`	`number`	No	Organization to query

Returns: Cited hosts with total counts, period-over-period deltas, and per-LLM citation breakdowns.

`get_citations_by_page`

Get top cited pages (URLs) with period citation metrics and per-LLM breakdown. The previous period of equal length is computed automatically for comparison. Parameters:

Parameter	Type	Required	Description
`limit`	`number`	No	Max pages to return (default 50, max 500)
`startDate`	`string`	No	Start of the window in `YYYY-MM-DD` format. Defaults to 14 days before `endDate`
`endDate`	`string`	No	End of the window in `YYYY-MM-DD` format. Defaults to today. If both dates omitted, uses the past 14 days
`granularity`	`string`	No	`week` (default) compares this week vs last week; `month` compares calendar months. Ignored when both dates set
`organizationId`	`number`	No	Organization to query

Returns: Cited pages with URL, title, total counts, and per-LLM citation breakdowns.

`get_visibility_timeseries`

Get visibility trends over time by competitor. Returns at most 12 x-axis points and the top 5 competitors. Parameters:

Parameter	Type	Required	Description
`webSearch`	`boolean`	No	Filter by web search enabled responses (default `true`)
`granularity`	`string`	No	`auto` (default), `daily`, `weekly`, or `monthly`. `auto` picks the coarsest bucket that keeps ≤12 points
`organizationId`	`number`	No	Organization to query

Returns: Per-competitor time series with mention rates per time bucket.

`get_competitor_llm_breakdown`

Get which LLMs mention which competitors and at what percentage over the last 14 days. Parameters:

Parameter	Type	Required	Description
`webSearch`	`boolean`	No	Filter by web search enabled responses (default `true`)
`organizationId`	`number`	No	Organization to query

Returns: Per-competitor, per-LLM mention percentages with provider metadata.

`get_missed_prompts`

Recent visibility prompts where competitors appeared in LLM responses but your brand did not. Use this to identify content and topic gaps. Parameters:

Parameter	Type	Required	Description
`limit`	`number`	No	Max prompts to return (default 25, max 200)
`organizationId`	`number`	No	Organization to query

Returns: Array of missed prompts with the prompt text, which competitors appeared, and associated metadata.

`get_traffic_analytics`

Full website traffic analytics for your organization (same data as Dashboard → Traffic Analysis). Returns total visits, unique visitors, live users, top referrers, traffic sources breakdown, device breakdown, session metrics, bot vs human traffic analysis, UTM campaign analytics, and daily traffic time series. Parameters:

Parameter	Type	Required	Description
`startDate`	`string`	No	Start of the window in `YYYY-MM-DD` format. Defaults to 14 days before `endDate`
`endDate`	`string`	No	End of the window in `YYYY-MM-DD` format. Defaults to today. If both dates omitted, uses the past 14 days
`organizationId`	`number`	No	Organization to query

Returns:

Field	Type	Description
`totalVisits`	`number`	Total page visits in the period
`uniqueVisitors`	`number`	Unique visitor count
`liveUsers`	`number`	Currently active users
`topReferrers`	`array`	Top referrer domains with visit counts and percentages
`deviceBreakdown`	`object`	Split of mobile / tablet / desktop visits
`sessionMetrics`	`object`	Average session duration and bounce rate
`utmAnalytics`	`object`	UTM campaign, source, and medium breakdowns

`get_traffic_summary`

Quick traffic overview with key metrics only. Use this for a fast snapshot; use get_traffic_analytics for the full dataset. Parameters:

Parameter	Type	Required	Description
`startDate`	`string`	No	Start of the window in `YYYY-MM-DD` format. Defaults to 14 days before `endDate`
`endDate`	`string`	No	End of the window in `YYYY-MM-DD` format. Defaults to today. If both dates omitted, uses the past 14 days
`organizationId`	`number`	No	Organization to query

Returns:

Field	Type	Description
`totalVisits`	`number`	Total page visits in the period
`uniqueVisitors`	`number`	Unique visitor count
`liveUsers`	`number`	Currently active users
`topReferrers`	`array`	Top 5 referrer domains with visit counts
`deviceBreakdown`	`object`	Split of mobile / tablet / desktop visits
`sessionMetrics`	`object`	Average session duration and bounce rate

`get_brand_sentiment`

Brand sentiment analysis derived from LLM visibility responses. Returns an average sentiment score, distribution across positive/neutral/negative/mixed responses, per-platform breakdown, and top brand strengths and weaknesses extracted by AI. Parameters:

Parameter	Type	Required	Description
`llmId`	`number`	No	Filter to a specific LLM by ID. Omit for all LLMs
`days`	`number`	No	Restrict to responses from the last N days. Omit for all time
`organizationId`	`number`	No	Organization to query

Returns: Average sentiment score (0–100), sentiment distribution counts, per-platform breakdown, and lists of top brand strengths and weaknesses.

`get_competitor_facts`

AI-extracted facts about your tracked competitors from LLM visibility responses. For each competitor, returns positive and negative facts along with a sentiment score. Parameters:

Parameter	Type	Required	Description
`llmId`	`number`	No	Filter to a specific LLM by ID. Omit for all LLMs
`days`	`number`	No	Restrict to responses from the last N days. Omit for all time
`organizationId`	`number`	No	Organization to query

Returns: competitorGroups — array of competitors, each with up to 15 extracted facts and a sentiment score.

`get_brand_facts`

AI-extracted facts about your own brand from LLM visibility responses. Returns a brand attribute breakdown by category (pricing, performance, usability, features, support, brand) with positive/negative signal counts, plus a list of specific brand facts with their polarity. Parameters:

Parameter	Type	Required	Description
`llmId`	`number`	No	Filter to a specific LLM by ID. Omit for all LLMs
`days`	`number`	No	Restrict to responses from the last N days. Omit for all time
`organizationId`	`number`	No	Organization to query

Returns: attributes — per-category breakdown with positive/negative counts; brandFacts — up to 40 specific extracted facts with polarity.

`get_brand_kit`

Read your organization’s brand kit — the structured brand guidelines used to keep generated content on-brand. This is your own authored content (not AI-extracted), edited from the Brand Kit section of the dashboard or via update_brand_kit. Parameters:

Parameter	Type	Required	Description
`organizationId`	`number`	No	Organization to query

Returns:

Field	Type	Description
`configured`	`boolean`	Whether a brand kit row exists yet for the organization
`brandDescription`	`string \| null`	What the brand/company does, in plain language
`brandVoice`	`string \| null`	Tone and voice guidelines
`authorPersona`	`string \| null`	The persona/POV content should be written from
`writingRules`	`string \| null`	Specific writing rules, style constraints, or do/don’t guidance
`productLines`	`array`	Product lines, each with a `title` and `description` (empty if none)
`updatedAt`	`string \| null`	When the brand kit was last updated

`update_brand_kit`

Write tool. Unlike the read-only data tools, update_brand_kit modifies your brand kit. It is annotated destructiveHint so MCP clients can prompt for confirmation before running it.

Update your organization’s brand kit / brand guidelines. Only the fields you provide are changed — omitted fields keep their current value. Use this to write structured brand guidance (e.g. distilled from documents or notes you share) into the brand kit. Provide at least one field. Parameters:

Parameter	Type	Required	Description
`brandDescription`	`string`	No	What the brand/company does, in plain language
`brandVoice`	`string`	No	Tone and voice guidelines, e.g. “confident, concise, no jargon”
`authorPersona`	`string`	No	The persona/POV content should be written from
`writingRules`	`string`	No	Specific writing rules, style constraints, or do/don’t guidance
`productLines`	`array`	No	Full replacement list of product lines, each `{ title, description }` — not merged with existing
`organizationId`	`number`	No	Organization to update

Returns: The updated brand kit (brandDescription, brandVoice, authorPersona, writingRules, productLines, updatedAt).

`get_llm_referral_traffic`

Filters your website traffic to show only visits originating from AI/LLM platforms (ChatGPT, Claude, Perplexity, Gemini, Copilot, and others). Covers both direct referrer domains and UTM-tagged sources. Parameters:

Parameter	Type	Required	Description
`startDate`	`string`	No	Start of the window in `YYYY-MM-DD` format. Defaults to 14 days before `endDate`
`endDate`	`string`	No	End of the window in `YYYY-MM-DD` format. Defaults to today. If both dates omitted, uses the past 14 days
`organizationId`	`number`	No	Organization to query

Returns:

Field	Type	Description
`llmReferrers`	`array`	Referrer domains matched to known AI platforms
`llmUtmSources`	`array`	UTM sources matched to known AI platforms
`totalLlmVisits`	`number`	Combined visits from referrers + UTM sources
`totalLlmVisitors`	`number`	Combined unique visitors from AI sources
`referrerVisits`	`number`	Visits from referrer domains only
`utmVisits`	`number`	Visits from UTM sources only
`startDate`	`string`	Start of the window analyzed (`YYYY-MM-DD`)
`endDate`	`string`	End of the window analyzed (`YYYY-MM-DD`)

`list_ai_seo_crawls`

List full-site AI SEO crawls for the organization, most recent first. Each crawl audits an entire domain. Call this first to find crawl IDs before fetching specific audit results with get_ai_seo_audit_checks. Parameters:

Parameter	Type	Required	Description
`limit`	`number`	No	Max crawls to return (default 10, max 20)
`organizationId`	`number`	No	Organization to query

Returns: crawls — array of crawls with crawl ID, domain, status (running or completed), and score breakdowns.

`get_ai_seo_audit_checks`

Get AI SEO check results for your organization from a site crawl. Without auditId, lists recent crawls. With auditId (a crawl ID, e.g. from list_ai_seo_crawls), returns the crawl’s site-wide checks (e.g. robots_present, sitemap, llms_txt), post-crawl checks, and per-page individual checks (e.g. canonical, title_description, structured_data) with pass/fail status, scores, and details. Pages are returned worst-scoring first and capped at 100; totalPages reports the full count so you can tell when the list is truncated. Parameters:

Parameter	Type	Required	Description
`auditId`	`number`	No	Specific crawl ID to fetch checks for. Omit to list recent crawls
`limit`	`number`	No	Max crawls to list when `auditId` is omitted (default 10, max 20)
`organizationId`	`number`	No	Organization to query

Returns: When auditId is provided: crawl metadata (domain, status, scores), siteWideChecks, postCrawlChecks, totalPages (full page count), and pages — the worst-scoring pages first (capped at 100), each with its own checks (per-check pass/fail status, scores, and details). When omitted: crawls array of recent crawls with crawl ID, domain, status, and score breakdowns.

`get_prompt_mention_rates`

Per-prompt mention rate (share of responses mentioning your brand) for each tracked prompt, compared across two consecutive 14-day windows. Results are sorted by absolute change, descending. Parameters:

Parameter	Type	Required	Description
`asOfDate`	`string`	No	End date of the current 14-day window in `YYYY-MM-DD` format. Omit for today
`organizationId`	`number`	No	Organization to query

Returns: prompts — per-prompt current and previous mention rate (0–1 fractions) plus response counts per window; asOfDate and windowDays echoing the window used.

`generate_report`

Generate a complete performance report for your brand over any date range (a full month, a half month, or a custom span). Assembles five sections — visibility metrics, citation growth, content performance, prompt coverage wins, and technical — with display-ready numbers, deltas resolved against the equal-length window immediately before the range, and top movers pre-selected. Parameters:

Parameter	Type	Required	Description
`startDate`	`string`	Yes	Inclusive start of the reporting range in `YYYY-MM-DD` format
`endDate`	`string`	Yes	Inclusive end of the reporting range in `YYYY-MM-DD` format
`organizationId`	`number`	No	Organization to query

Returns: report — the assembled report object with all five sections; format_guide — guidance for narrating the report as prose.

API Keys

API keys let you authenticate with the Pierview MCP server using a Bearer token instead of OAuth. This is useful for server-side integrations, CI/CD pipelines, or any environment where browser-based OAuth isn’t practical. Keys are scoped to your organization and can be created, viewed, and revoked from the Pierview dashboard.

Creating an API Key

Open Configuration

Go to your Pierview dashboard and select the API Keys tab.

Create a new key

Click Create API Key, enter a descriptive name (e.g. “Production MCP” or “CI Pipeline”), then click Create.

Copy your key

Your full API key will be displayed once. Copy it and store it securely, you won’t be able to see it again.The key starts with pv_ followed by 32 hex characters.

Store your API key in a secure location such as an environment variable or secrets manager. Never commit API keys to source control.

Using Your API Key

Pass the key as a Bearer token in the Authorization header when connecting to the MCP server.

Claude Code
Claude Desktop
Cursor

claude mcp add pierview --transport http https://mcp.pierview.ai/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

In your Claude Desktop configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "pierview": {
      "url": "https://mcp.pierview.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

In your Cursor MCP settings (.cursor/mcp.json):

{
  "mcpServers": {
    "pierview": {
      "url": "https://mcp.pierview.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Revoking a Key

To revoke an API key, go to the API Keys tab in Configuration and click the trash icon next to the key you want to disable. Revoked keys are immediately rejected by the server.

Security

API keys are hashed before storage, Pierview never stores your plaintext key
Each key is scoped to a single organization
Revoked keys cannot be re-activated; create a new key if needed
Rotate keys periodically as a best practice

Example Queries

Once connected, you can ask your AI tool questions like:

“What are my top cited pages this week?”
“What is my current mention rate and share of voice?”
“How has my visibility changed over the last two weeks?”
“Which LLMs mention my competitors the most?”
“Show me citation trends for my different organizations”
“Generate a performance report for last month”
“Which prompts gained or lost the most visibility over the last two weeks?”
“What’s in my brand kit?”
“Here are our brand guidelines — structure them and save them to my brand kit”
“Update my brand voice to be more concise and technical”

Get Started

Set up Your Project

Interpret Your Results

Content Creation

Integrations

AI Agent Analytics

Agency Partners

Overview

Prerequisites

Setup

Available Tools

`list_organizations`

`get_key_metrics`

`get_citations_by_host`

`get_citations_by_page`

`get_visibility_timeseries`

`get_competitor_llm_breakdown`

`get_missed_prompts`

`get_traffic_analytics`

`get_traffic_summary`

`get_brand_sentiment`

`get_competitor_facts`

`get_brand_facts`

`get_brand_kit`

`update_brand_kit`

`get_llm_referral_traffic`

`list_ai_seo_crawls`

`get_ai_seo_audit_checks`

`get_prompt_mention_rates`

`generate_report`

API Keys

Creating an API Key

Using Your API Key

Revoking a Key

Security

Example Queries

​Overview

​Prerequisites

​Setup

​Available Tools

​list_organizations

​get_key_metrics

​get_citations_by_host

​get_citations_by_page

​get_visibility_timeseries

​get_competitor_llm_breakdown

​get_missed_prompts

​get_traffic_analytics

​get_traffic_summary

​get_brand_sentiment

​get_competitor_facts

​get_brand_facts

​get_brand_kit

​update_brand_kit

​get_llm_referral_traffic

​list_ai_seo_crawls

​get_ai_seo_audit_checks

​get_prompt_mention_rates

​generate_report

​API Keys

​Creating an API Key

​Using Your API Key

​Revoking a Key

​Security

​Example Queries

Overview

Prerequisites

Setup

Available Tools

`list_organizations`

`get_key_metrics`

`get_citations_by_host`

`get_citations_by_page`

`get_visibility_timeseries`

`get_competitor_llm_breakdown`

`get_missed_prompts`

`get_traffic_analytics`

`get_traffic_summary`

`get_brand_sentiment`

`get_competitor_facts`

`get_brand_facts`

`get_brand_kit`

`update_brand_kit`

`get_llm_referral_traffic`

`list_ai_seo_crawls`

`get_ai_seo_audit_checks`

`get_prompt_mention_rates`

`generate_report`

API Keys

Creating an API Key

Using Your API Key

Revoking a Key

Security

Example Queries