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: 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
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);
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
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”