> ## Documentation Index > Fetch the complete documentation index at: https://www.pierview.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # MCP Server > Connect AI coding tools to your Pierview data via the Model Context Protocol **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](#update-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](https://pierview.ai) account with an active subscription ## Setup Go to **Claude Desktop** > **Customize** > **Connectors** > **+** > **Add custom connector**. Add the following details as prompted: * **Name**: **Pierview** * **Remote MCP Server URL**: **[https://mcp.pierview.ai](https://mcp.pierview.ai)** Claude Desktop MCP connector Click the Connect button, follow the authentication steps which will request access to your Pierview data on behalf of Claude. Run the following command in your terminal: ```bash theme={null} claude mcp add pierview --transport http https://mcp.pierview.ai ``` Run `claude` in your terminal. You will be prompted to sign in with your Pierview account on first use. 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](https://github.com/anthropics/claude-agent-sdk) to build custom AI agents that query your Pierview data programmatically. Requires a Pierview [API key](#api-keys) and an [Anthropic API key](https://console.anthropic.com/). Go to your organization settings at [https://www.pierview.ai/dashboard/configuration](https://www.pierview.ai/dashboard/configuration) and create an API key. This will be used to authenticate your requests. ```bash theme={null} npm install @anthropic-ai/claude-agent-sdk ``` ```bash theme={null} export ANTHROPIC_API_KEY="your-anthropic-api-key" ``` ```typescript theme={null} 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 Go to your [Pierview dashboard](https://pierview.ai/dashboard/configuration) and select the **API Keys** tab. Click **Create API Key**, enter a descriptive name (e.g. "Production MCP" or "CI Pipeline"), then click **Create**. 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. ```bash theme={null} 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`): ```json theme={null} { "mcpServers": { "pierview": { "url": "https://mcp.pierview.ai/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` In your Cursor MCP settings (`.cursor/mcp.json`): ```json theme={null} { "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](https://pierview.ai/dashboard/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"