What is MCP?
The Model Context Protocol (MCP) is an open standard that lets AI assistants connect to external tools and data sources. Searchable’s MCP server lets you ask AI assistants questions about your AI visibility, site audits, and content — without leaving the assistant. Compatible clients include:- Claude (Claude.ai, Claude Desktop and mobile) and Claude Code — add as a connector
- ChatGPT, Codex and dots — via ChatGPT’s plugin directory; Codex also from its CLI
- Gemini — via custom Connected Apps; Gemini CLI — via the Searchable extension
- Grok — via custom MCP connectors
- Cursor, VS Code, Windsurf / Devin and Muse Code
- Microsoft 365 Copilot agents and Microsoft Copilot Studio
- Slack and Microsoft Teams agents — through Claude Tag, Slackbot, Copilot Studio and Microsoft 365 Copilot; see Use Searchable in Slack and Microsoft Teams
- Perplexity Enterprise, Mistral, and other MCP-compatible clients
Ask questions like “What’s my brand’s visibility score on ChatGPT?” or “What critical AEO
issues does my site have?” and the assistant will query Searchable for live data.
Plan requirement: MCP integration requires a paid Searchable plan. Both connection methods —
signing in with OAuth and API keys — are unavailable on the Free plan.
How authentication works
The Searchable MCP server uses OAuth 2.1 with PKCE. It supports the current MCP client-metadata discovery flow, plus Dynamic Client Registration for clients that still require it. Public clients use PKCE; compatible enterprise clients can use a dynamically issued client secret. This means a new standards-compatible assistant can connect without Searchable adding a provider-specific OAuth integration first. You do not paste an API key into your MCP client’s config — you sign in and approve access, just like connecting any other app:- You add the server URL to your client (
https://app.searchable.com/api/mcp-server/mcp). - On first use, the client opens Searchable in your browser and asks you to log in (or reuses your existing session).
- A consent screen shows which application is connecting and lets you choose:
- Which projects it can access — only the projects you can open in Searchable are listed; pick specific ones, or leave all selected (all also covers projects you create later).
- Whether to turn on Allow write access. It is off by default, so the connection stays read-only until you switch it on. Projects you can only view are marked View only, and when every selected project is view-only the switch is not offered at all: the connection is read-only.
- You click Authorize. Your client receives an OAuth access token scoped to exactly what you approved and uses it for subsequent requests.
Setup
Server URL:
https://app.searchable.com/api/mcp-server/mcp — the same address for every
client below.Step 1: Add the server to your client
Chat assistants
- Claude
- ChatGPT
- Gemini
- Grok
Works in Claude.ai and the Claude Desktop app:
- Open Customize → Connectors.
- Click + Add, then Add custom connector.
- Name it
Searchableand enter the URL:https://app.searchable.com/api/mcp-server/mcp - Click Continue, keep the recommended sign-in options, and click Add. Claude opens the Searchable sign-in and consent page — continue with Step 2.
Coding tools
- Claude Code
- Codex
- Cursor
- VS Code
- Gemini CLI
- Muse Code
- Windsurf / Devin
Add the server from your terminal:Then inside a session run A Searchable connector you added in Claude.ai also appears in Claude Code when you sign in to Claude Code with your Claude account.
/mcp, pick searchable → Authenticate — your browser opens the Searchable sign-in and consent page. Continue with Step 2.Or install the Searchable plugin, which adds the same server:https://app.searchable.com/api/mcp-server/mcp. Searchable publishes OAuth discovery metadata, so
choose OAuth or automatic authentication when the host asks. The exact menu name and availability
are controlled by the host product.
Step 2: Log in and authorize
The first time your client connects, Searchable opens in your browser:- Log in to Searchable (or continue with your existing session).
- On the consent screen, choose which projects the client may access. Leave Allow write access off (the default) for read-only access, or switch it on to allow write tools.
- Click Authorize. Your browser returns to the client, now connected — no API key to copy or paste.
Your login is the identity for this flow. To connect a script or a client that only accepts a
static bearer token, use the legacy API-key path below instead.
Step 3: Verify the connection
Once connected, ask:Connect with an API key (legacy)
The OAuth login flow above is the recommended path for interactive MCP clients. For scripts, headless clients, or any client that only accepts a static bearer token, a Searchable API key works as a bearer token directly — the samesea_ key the REST API accepts.
1
Create an API key
In Manage Account → Integrations → MCP → Access tokens, click Generate access token,
name it, and copy the token (starts with
sea_). Store it securely — you won’t see it again. A
token can cover all your projects or be limited to a single project. It’s read-only unless you
turn on Allow write access, which lets it use every write tool, including the ones that need
a capability. A token’s access can’t be changed later, so create a new one to add write access.2
Send it as a bearer token
Configure your client to send
Authorization: Bearer sea_... on every request to
https://app.searchable.com/api/mcp-server/mcp. No login or consent screen is involved on this
path.Available tools
The Searchable MCP exposes 58 primary tools — 31 read-only and 27 write (60 with the Associated Sources feature enabled, one more of each), plus 4 deprecated names kept callable through their sunset window (see Deprecated tool names). A reseller’s owner and staff are also offeredmove_pitch_to_client, a write tool, while the reseller is in its rollout. Every read tool is annotated readOnlyHint: true. Every tool that operates on a project takes a required projectId (get IDs from list_projects), and most read tools also accept an optional response_format — "concise" (default, summary + capped rows) or "detailed" (fuller rows, same shape).
Two kinds of write tool. The original three (Write actions below) need at
most the write scope from your connection (
generate_report only read). The write tools
under Project and prompt management, import_prompts and
manage_source_classification_rule each need a connection minted with a specific named
capability instead (e.g. prompt:draft, knowledge:manage) — a plain read-and-write
connection does not automatically reach any of them.
An API key carries exactly the scopes it was created with: write and every capability when
Allow write access was on, read-only otherwise. An OAuth connection gets a capability only
when the connecting client asked for that exact capability at authorization and you granted it
on the consent screen: Allow write access grants every capability the client asked for, and
Customise permissions picks them one by one. Calling one without the right capability returns
missing_scope, distinct from forbidden (the connection has the capability, but your own role
in the workspace doesn’t allow the action) and not_found (the project isn’t visible to this
connection at all, or the feature isn’t enabled for it) — the three read differently on purpose,
so you know which of “wrong grant,” “wrong role,” or “wrong project” to fix.searchable://glossary (compact index) and searchable://glossary/full (complete definitions) — metric and concept definitions with the tools that read each one, for hosts that attach resources as reference context.
get_visibility, get_share_of_voice, and get_sentiment additionally accept compare: "previous_period" | "previous_year" — the response gains a comparison block with the previous window’s metrics and current-minus-previous deltas, so period-over-period questions are one tool call.
Absolute date ranges. The core analytics reads accept
from and to (inclusive, UTC) as an
alternative to the relative days — from: "2026-03-01", to: "2026-03-31" answers “how did March
go” without arithmetic against today. Both bounds are required together, and they are mutually
exclusive with days: sending both is an invalid_argument error rather than a silent
precedence rule. Bare YYYY-MM-DD and full ISO timestamps are both accepted (the UTC day is what
counts). An over-long days is clamped to the tool’s maximum, but an over-long explicit range is
rejected — narrowing a range you spelled out would answer a different question than the one
you asked. Supported on get_visibility (every group_by), get_share_of_voice,
get_sentiment, get_topic_analysis, get_ai_traffic (every report), and investigate, plus
the matching REST endpoints. Tools not in that list — get_competitors,
get_shopping_visibility, get_ads, get_page_metrics, get_query_fanout,
get_prompt_answers, and the source reads — still take days only. (get_gsc_performance has
always had its own startDate / endDate.)Filter echo. Every filterable read echoes an
appliedFilters object: the platform / brand /
topic / location filters that call actually narrowed by, or {} when it was unfiltered. That
covers get_visibility, get_share_of_voice, get_competitors, get_topic_analysis,
list_prompts, get_sentiment (every view), get_source_trends, and get_shopping_visibility
(summary view). All of them except get_topic_analysis also return availableFilters (the
project’s topics and countries) so a client can offer the next filter without a second round-trip
— on get_visibility that rides along on the summary and platform views, on
get_share_of_voice on the summary view, and on get_competitors on the list view. Use
appliedFilters to state what a number covers rather than presenting a filtered figure as the
whole picture.Write actions are MCP tools too:
trigger_audit, refresh_sitemap, add_pages,
remove_pages and update_site_issues are available to keys/grants with the write scope, and
generate_report to any connection, read-only included, as sharing a report is in the app.
generate_report, refresh_sitemap, add_pages, remove_pages and update_site_issues require
an explicit confirm: true argument — without it they return a dry-run preview and change nothing.
trigger_audit starts straight away, as the app’s button does; pass dryRun: true to preview it
first. The REST equivalents (e.g. POST /api/mcp/projects/{projectId}/reports) remain available;
see Advanced API Usage.Orientation
Four tools exist purely to make assistants reliable, and are worth calling early in a session. None of them takes aprojectId.
get_current_date
The server’s current UTC date and time (
utcDate, utcDateTime, dayOfWeek, isoWeek) plus pre-computed window starts — yesterday, last7Days, last30Days, last90Days, last365Days. Call it before interpreting relative time like “last month” so date math is never guessed. Needs no scope.Parameters: nonewhoami
Who this connection is authenticated as, its scopes, whether it is limited to specific projects, the workspaces it can reach, and the project roster it can see. Each workspace lists your role, whether you can create projects there (
canCreateProjects), and the ids of its projects. Call it when unsure what the connection can access, and before create_project, which needs one of those workspace ids. Over REST, GET /api/mcp/workspaces returns the same list.Parameters: nonesearch_docs
Keyword search over this documentation, so questions like “how is the visibility score calculated?” are answered in-chat, from the source. Returns each hit’s
slug, title, description and a snippet — follow up with read_doc. Needs no scope.Parameters: query (required), limit (default 8, max 25)read_doc
One documentation page by its slug (from
search_docs, e.g. recipes/visibility-drop), optionally narrowed to one heading with section. A section that doesn’t match returns the whole page with sectionNotFound and the page’s availableSections; an unknown slug returns not_found. Needs no scope.Parameters: slug (required), section (optional)Diagnostics
investigate
Answers a whole diagnostic question in one call, by running its multi-read chain server-side
and in parallel. Prefer it over chaining the granular tools yourself for “why did X change” and
“where do we stand” questions.
question="visibility_drop" (default) returns the score trend with its largest report-to-report
fall (spanDays says how many days that covers when reports aren’t daily), per-platform movement
against the previous window, the share-of-voice shift with which competitors gained, and the five
weakest of the ten topics you’re mentioned in most. "competitive_position" returns your standing
with ranks and deltas, your score trend, and up to five topics — of the 15 you’re mentioned in
most — where a rival currently leads. "citation_gap" returns your citation trend, the domains AI
answers actually cite in your space, and per-engine citation share.Takes the usual narrowing arguments — days or from/to, platform, topicId, unbranded /
branded, country / locationId — but not every part of the answer honors all of them: the
score trend takes only unbranded / branded, and the topic figures ignore topicId and
location.It reports measurements, never a cause. It will tell you ChatGPT fell 38 points while Gemini
held; it will not tell you why, because the reason is usually outside the data — a rebrand, a
campaign ending, a competitor launch. Every response carries an interpretation list naming what
the numbers cannot settle. A signal whose upstream failed appears in unavailable with a reason
rather than as a zero, so missing data is never mistaken for a finding.Each question has a companion recipe explaining how to read the result and when it misleads:
visibility drop, competitive position,
citation gap. Load one in-chat with
read_doc("recipes/visibility-drop").Parameters: projectId (required), question ("visibility_drop" by default,
"competitive_position", or "citation_gap"), days (default 30, max 365), from/to,
platform, topicId, unbranded, branded, country, locationId (all optional except
projectId)Projects
list_projects
List all projects this connection can access — names, domains, IDs, and
dataAvailableFrom (the earliest date with visibility data, null while a project has none yet). Archived projects are listed too, marked “(archived)”. Call this FIRST: every project-scoped tool needs a projectId, and dataAvailableFrom tells you how wide a window is worth requesting.Parameters: response_format (optional)Visibility & share of voice
get_visibility
AI visibility for a project.
group_by selects the view: summary (overall visibility score), platform (per ChatGPT/Claude/Gemini/Perplexity breakdown), prompt (per-prompt breakdown, paginated), location (per country, state or city), or date (the per-report time series — trend, uplift, before/after analysis; default 90-day window). The unbranded/branded, topicId, country and locationId filters work on summary, platform, prompt and location, and date accepts only unbranded/branded (anything else is an invalid_argument). The platform filter narrows only group_by=prompt|location — on summary/platform the figures stay all-platform. An interactive Visibility Snapshot card also renders automatically beside the answer on Apps-capable clients — see below.include attaches optional extra blocks (comma-separated): industry_ranking adds the competitive leaderboard — the top 25 entities by visibility, with your own rank, share of voice, and change (visibility in the window minus the equal-length window before it; null, shown as ”—”, when that earlier window has no responses or nothing is mentioned in this one; comparisonRange names the earlier window) — to group_by=summary|platform (hasMore flags a longer field; brandRankStatus distinguishes ranking below the cutoff from being unranked, and totalEntities is null when truncated); annotations adds the dated markers (campaign launches, migrations) overlapping the window to group_by=date, so a spike comes back with its explanation attached. An include a view cannot attach is an invalid_argument error on every view — including group_by=prompt and group_by=location, which attach no blocks at all — never a response that quietly lacks the block.Parameters: projectId (required), group_by ("summary" | "platform" | "prompt" | "location" | "date", default summary), days (default 30, or 90 for group_by=date; max 365, or 180 for group_by=prompt), from/to (same maximums), include (industry_ranking on summary/platform, annotations on date), compare (summary/platform only), unbranded, branded, platform (group_by=prompt|location), topicId, limit (group_by=prompt, default 100, max 500), offset (group_by=prompt), country, locationId, response_format, render (all optional except projectId)get_topic_analysis
Per-topic AI visibility — the brand’s mention rate in each topic, its competitive rank within that topic, how many of its tracked prompts were answered in the window, and the AI-identified attribute strengths and gaps behind the number. This is the only per-topic view: use it for any question about topics, subject areas, or categories, including where a brand is winning or losing and what to fix. Replaces the removed
get_visibility (group_by:"topic"). An interactive Topic Analysis card also renders automatically beside the default view=topics answer on Apps-capable clients — see below.view="prompts" drills into ONE topic (topicId required): every prompt assigned to it with your average rank, its visibility, and which competitors outrank you — the “which specific questions are we losing” view behind a weak topic. A prompt you never appeared for reports rank: null, never 0.view="heatmap" returns average brand position per topic x AI platform — where you’re strong on one engine and absent on another. There is deliberately no platform filter on this view: the platform axis is the answer.Parameters: projectId (required), view (topics default, prompts, heatmap — platform is rejected on heatmap, whose axis IS platform), topicId (required for view=prompts, optional on heatmap; rejected on the default view, which lists every topic), days (default 30, max 365), from/to, limit (view=topics, default 15, max 50 — keeps the topics with the most brand mentions), platform, unbranded, branded, response_format, render (all optional except projectId)get_visibility_history
Deprecated — call
get_visibility with group_by: "date" instead (same data, same parameters). This name keeps answering with an identical payload until its removal date; see Deprecated tool names.Parameters: projectId (required), days (default 90, max 365), unbranded, branded, response_format (all optional except projectId)get_share_of_voice
Brand vs competitor share of voice — mention-share percentage and rank among all tracked entities (the brand plus the top 50 competitors;
totalCompetitors gives the full count), plus each entity’s point change against the equal-length window just before the requested one (null when either window has no mentions). mentions/citations aren’t part of this view (mirrors the in-app Share of Voice sheet) — use get_competitors for those. An interactive Share of Voice card also renders automatically beside the answer on Apps-capable clients — see below.group_by="date" returns the daily share series instead — your share and your top 10 competitors’, one point per day. That is the “is our share growing?” view; include="annotations" adds the dated markers explaining any jump. compare is not supported there (the series already shows the movement), and the interactive card hides itself on it.Parameters: projectId (required), group_by (summary default, or date), days (default 30, max 365), from/to, include ("annotations", group_by=date only — any include on the summary is an invalid_argument), platform, topicId, unbranded, branded, country, locationId, compare (summary only), response_format, render (all optional except projectId)Competitors
get_competitors
The project’s real/tracked competitors, ordered by rank (highest visibility first) — visibility, share of voice, sentiment score, average mention position, all-time mention count (
mentions) and in-window mention count (mentionsInWindow), plus a brand block carrying the same metrics for the project itself so the two sit on one ruler. Each row’s id is what update_competitor takes. Pass competitorId for a head-to-head against one competitor instead: headToHead.brand vs headToHead.competitor, each with visibility %, share of voice %, sentiment (0–100) and average position (a rank — lower is better), plus the phrases each is known for; for the competitor it also returns its rank, per-day history, and up to 10 recent prompts it was mentioned in. competitorId accepts either the competitor’s ID or its name exactly as the list shows it (competitorId: "Nike"), so you can drill in straight from the list. A null metric means unmeasured in that window, not zero. visibility/sov/sentimentScore/avgPosition/mentionsInWindow honor the filters; the list view’s mentions (the brand block’s included) is all-time and ignores them. On the head-to-head, citations (inline citations on responses mentioning the competitor) and history[].domainSources (source URLs — pages used for generation, not inline citations — on the competitor’s own domain) are different metrics; history[] honors days only, and the competitor’s mention and citation totals cover at most its 500 most recent in-window mentions. An interactive Competitor Ranking card also renders automatically beside the answer on Apps-capable clients, in whichever shape matches the call — see below.Parameters: projectId (required), competitorId (optional — ID or name; switches to the head-to-head view), days (default 30, max 365), platform, topicId, unbranded, branded, country, locationId, limit (list view, default 20, max 100), offset (list view), response_format, render (all optional except projectId)Sources & citations
search_sources
Top cited source domains from AI answers — rank, citation counts, usage %, models, and top content types. Paginated and sortable. Use to find which external sites AI models cite most; drill in with
get_source_detail. A domain split by source classification rules appears once, with types (the types of its parts, most used first), ruleCount, and parts: each part’s scope, type, numbers and ruleId (null for the rest of the domain when no domain-wide rule decides it). The text answer adds one line per split domain listing its parts and rule ids. withRules: true lists only the split domains, like the Sources page’s Domains with rules filter. Once the project has had rules, the answer also carries rulesApplying: true while a rule change is still being applied across the project, history included, when the numbers may still change and the text answer says so in a closing line; false once they reflect every rule. Wait for false before reporting numbers as updated after a rule change. A project that never had rules gets no rulesApplying.Parameters: projectId (required), sort (citations | usage | avgCitations, with a - prefix for descending; default "-citations"), limit (default 20, max 1000), offset, days (default 30; rounded up to 7, 30, 90 or 365), platform, topicId, sourceType (comma-separated: brand, competitor, editorial, social, forum, review, institutional, third_party, other), unbranded, branded, country, locationId, withRules, response_format (all optional except projectId)get_source_detail
Drill into cited sources.
level="domain" (+ domain): domain summary (for a domain split by source classification rules, also its parts, each with its scope, type, numbers and ruleId, listed in the text answer too), or include="urls" (cited URLs on it) / include="responses" (AI responses citing it). level="url": with url → single-page citation analytics, or include="content" → cached page markdown + entity mentions (never triggers a live scrape); without url → all cited URLs across the project (optionally filtered by contentType). A missing domain (or a missing url with include="content") returns not_found.Parameters: projectId (required), level ("domain" | "url", default domain), include ("urls" | "responses" on level=domain; "content" on level=url), domain (required for level=domain), url (level=url; with include="responses" it narrows to responses citing that one page), contentType, limit (default 20, max 1000), offset, cursor, days (default 30; rounded up to 7, 30, 90 or 365), platform, topicId, sourceType, unbranded, branded, country, locationId, response_format (all optional except projectId)get_source_trends
How the project’s top source domains trend over time — a per-domain time-series of the external sites most used as sources in AI answers, over the window (default 30 days). An interactive Sources card renders beside the answer on Apps-capable clients: the trend line inline, expanding to the top source URLs.Parameters:
projectId (required), days (window; default 30 — pass 7/90/365 for a different one), platform, topicId, sourceType, unbranded, branded, country, locationId, response_format, render (all optional except projectId)Sentiment
get_sentiment
Brand sentiment across AI platforms.
view selects: summary (default) — overall score + positive/neutral/negative split + per-platform breakdown, plus analysis (the weekly brand-perception write-up for the platform that mentions you most, or the one you filter to with platform) and analyses (every platform’s write-up, or only the filtered platform’s when platform is set); history — the daily sentiment trend (default 90-day window); competitors — head-to-head vs competitors, the brand flagged by isBrand. topicId is not accepted on competitors, compare only on summary, and include (annotations) only on history; each is an invalid_argument elsewhere. The interactive Sentiment Profile card renders on summary answers only.Parameters: projectId (required), view ("summary" | "history" | "competitors", default summary), days (default 30, or 90 for view=history; max 365), from/to, platform, topicId, limit (view=competitors, default 10, max 50), include ("annotations", view=history only), compare ("previous_period" | "previous_year", view=summary only), unbranded, branded, country, locationId, response_format, render (all optional except projectId)get_sentiment_history
Deprecated — call
get_sentiment with view: "history" instead (same data, same parameters). Keeps answering identically until its removal date; see Deprecated tool names.Parameters: projectId (required), days (default 90, max 365), platform, topicId, unbranded, branded, country, locationId, response_format (all optional except projectId)get_sentiment_competitors
Deprecated — call
get_sentiment with view: "competitors" instead (same data, same parameters). Keeps answering identically until its removal date; see Deprecated tool names.Parameters: projectId (required), days (default 30, max 365), platform, limit (default 10, max 50), unbranded, branded, country, locationId, response_format (all optional except projectId)Query fanout
get_query_fanout
The sub-queries AI models generate when answering tracked prompts. Without
prompt_id: the project aggregate (most frequent fanout queries, per-prompt counts, per-model stats; paginated). With prompt_id: every deduped sub-query for that one prompt, with per-query frequency and query type. Paid feature — returns plan_upgrade_required if not entitled.Parameters: projectId (required), prompt_id (optional — note the snake_case; the prompt’s id from list_prompts, a unique id prefix, or its text; omit for the project aggregate), days (default 30, max 180), platform, topicId, unbranded, branded, limit (aggregate, default 50, max 50), offset (aggregate; rounded down to a multiple of limit), topQueriesLimit (aggregate, default 50, max 200), response_format (all optional except projectId)Brand profile & authority
get_brand_profile
The project’s knowledge-base brand profile (name, website, category, positioning, description, topics, business type, reach, language, exact match, disambiguation note, connected entities,
alternativeNames — the other names that count as the brand, as the app’s Alternative names field lists them — competitor geography), its two writing documents — tone (the Knowledge Base’s Tone / Writing Style) and memory (its Memory) — plus the latest batch of AI-observed brand facts — statements AI platforms actually make about the brand, each with its id, platform and verification status (update_brand_fact_status marks one correct or incorrect). Pass include: "domain_authority" to also get the Moz domain-authority block (latest DA/PA/spam/linking-domains snapshot + roughly-monthly 365-day history) in the same call. Call this first for brand context in any analysis. profile is null until onboarding creates one; tone and memory are "" until written, and are always whole in the structured result, while the text shows an excerpt of a long one unless you pass response_format: "detailed"; facts come from the weekly sentiment job.Parameters: projectId (required), platform, verificationStatus ("unverified" | "pass" | "fail"), include ("domain_authority"), response_format (all optional except projectId)get_domain_authority
Deprecated — call
get_brand_profile with include: "domain_authority" instead (same data; the REST endpoint keeps custom days windows). Keeps answering identically until its removal date; see Deprecated tool names.Parameters: projectId (required), days (default 365, max 1095) (all optional except projectId)Prompts
list_prompts
The project’s prompt catalog as configured — tracked prompts (type, intent, branded flag, topics, tracked locations, keyword volume/difficulty), paused (untracked) prompts, or the AI-suggested review queue (
status="suggested" — proposals from research runs and the agent that nobody has accepted or rejected yet, each with the reason it was proposed). Configuration data, not performance — use get_visibility group_by=prompt for per-prompt visibility scores. The summary always reports all three counts, so pending suggestions surface from any call. Tracked and paused rows carry each prompt’s full id, which the prompt-scoped tools accept. An interactive Prompts card also renders automatically beside the answer on Apps-capable clients.Parameters: projectId (required), status ("tracked" | "untracked" | "suggested" | "all" — tracked + untracked, never suggested; default tracked), topicId, search (case-insensitive substring of the prompt text), limit (default 50, max 1000), offset, days (metrics window, default 30, max 365), sortBy (prompt | volume | difficulty | branded | intent | recency, default recency — performance columns like visibility/position/sentiment are computed per page and are not server-sortable), sortDir ("asc" | "desc", default desc; the default recency sort is always newest first), unbranded, branded, response_format, render (all optional except projectId; status="suggested" honors only topicId, search, limit and offset, newest first)get_prompt_answers
Raw, per-response AI-answer data for one prompt (Profound-parity) — platform, response date, response text, whether the brand was mentioned, competitors mentioned, and the source URLs the engine consulted (
sources[] — pages used for generation, not inline citations), one entry per AI response. Each answer also shows the exact wording it was asked (asked_as, location included), which can differ from the prompt’s current wording after an edit; an older answer whose wording was not recorded is marked when the prompt has been reworded since. Not an aggregate — use get_visibility or get_share_of_voice for scores/rankings. The default concise table shows a 120-character snippet per answer; response_format: "detailed" prints every answer in full (inline base64 images removed, 50,000-character safety cap). promptId takes the prompt’s id from list_prompts, a unique id prefix, or the prompt’s text (matched ignoring case, spacing and trailing punctuation, and also when cut short with a trailing … the way list_prompts and the other tables print it); text matching several prompts returns invalid_argument listing their ids, and one matching none returns not_found.Parameters: projectId (required), promptId (required — note the camelCase, unlike get_query_fanout’s prompt_id), days (default 30, max 365), platform, limit (default 10, max 50), offset (pass the previous call’s nextOffset to page), response_format (all optional except projectId and promptId)Site health & audits
get_site_health
Technical + AEO site health.
view="pages" (default) = the monitored-page inventory, one server-paginated page at a time (audited pages first) — every page (audited or not) with its latest technical/AEO scores, open-issue count, last-audited date, and 30-day traffic (Google Search Console clicks and impressions, GA4 page views, Bing clicks and impressions, refreshed daily), plus pagination.total and trafficSyncedAt (each source’s last sync; null means not connected or not synced yet, so that source’s zeros are not real); page with limit/offset, filter server-side with search (URL/slug/title), reorder with sortBy, and omit the header aggregates with includeSummary=false; view="audits" = per-page technical/AEO scores for audited pages + averages; view="issues" = issues grouped by severity (filter status; each issue carries paused and pausedUntil, null meaning paused until resumed); view="issue_details" = open issues grouped by type with fix guidance (filter issueType; covers the first 1,000 open issues). An interactive Site Audit card renders beside the answer on Apps-capable clients: pages/audits show the inventory with a search box + Prev/Next paging (both server-side), a per-page Audit button (calls trigger_audit for that page), a per-page Issues button (that page’s open and resolved issues), and a Sync website button (calls refresh_sitemap); issues/issue_details show the findings ranked by severity, each expanding to its description and affected pages (plus fix guidance on issue_details).Parameters: projectId (required), view ("pages" | "audits" | "issues" | "issue_details", default pages), status (view=issues: "open" | "paused" | "unresolved" | "resolved" | "all", default open; open leaves out issues paused with update_site_issues, paused lists only those, unresolved is both), pageId (view=issues / issue_details: scope to one monitored page — the card’s Issues button), issueType (view=issue_details: "technical" | "content"), includeIssues (view=audits, boolean), search (view=pages: server-side filter by URL / slug / title), sortBy (view=pages: "audited" | "technical" | "aeo" | "issues" | "traffic", default audited-first; "traffic" ranks by the combined GSC clicks + GA4 views + Bing clicks), includeSummary (view=pages, boolean, default true), limit (view=pages default 12, max 100; view=issues default 1000, max 5000), offset (view=pages / view=issues), response_format, render (all optional except projectId)Content & articles
list_articles
List articles / content pieces for a project (merges content-v2 + legacy), most recently updated first. Shows title, status, type, word count, and source, plus total and per-status counts. Not paginated: one call returns at most 100 rows.Parameters:
projectId (required), status ("draft" | "published" | "editing" | "all", default all — all excludes archived pieces), limit (default 50, max 100), response_format (all optional except projectId)get_article
Full article content — HTML/markdown body, SEO metadata (meta title and description, OG image, schema markup), FAQs, internal links, and all metadata. Legacy articles also carry an outline, TL;DR, summary, alt text, and external links; content-v2 pieces return those empty.Parameters:
articleId (required — the id from list_articles)Opportunities
get_opportunities
Actionable opportunities Searchable surfaced for the project — prioritized fix / write / audit / setup suggestions derived from visibility, mentions, sentiment, sources, traffic, prompts, prompt research, site health, articles, and platform setup. Returned in the product’s priority order (status, then impact, then newest). Defaults to active opportunities; blocked for active pitch projects. Each row carries its
id, which update_opportunity_status takes.Parameters: projectId (required), status ("active" | "completed" | "dismissed" | "auto_resolved", default active only), includeResolved (boolean — with no status, returns every status), source ("visibility", "mentions", "sentiment", "sources", "traffic", "prompts", "prompt_research", "site_health", "articles", "platform"), impact ("critical" | "high" | "medium" | "low"), limit (default 100, max 500), offset, response_format (all optional except projectId)GA4 / Traffic
This tool requires a GA4 property you can see on the project. When the project has none visible to you, the backing endpoint returns a
409 error with { code: "ga4_not_connected", message, howToFix } — the howToFix field points at Settings → Integrations in Searchable, where you can connect GA4 and then retry, or ask the teammate who linked it to share it with the project.get_ga4_traffic
Google Analytics 4 website traffic.
report="ai_referrals" (default; per-LLM-host AI Source Visitors from ChatGPT/Copilot/Gemini/Perplexity/DeepSeek and more — use for AI-referral attribution), "trend" (daily users/sessions/pageviews), "top_pages" (top landing pages by sessions), or "sources" (channel-group + source breakdown). Reads every GA4 property of the project you can see; properties[] reports per-property status (a failed property is error, the rest are still returned); usersIsUpperBound is true when users were summed across several properties or sources.Parameters: projectId (required), report ("ai_referrals" | "trend" | "top_pages" | "sources", default ai_referrals), weeks (default 12, max 52), limit (top_pages/sources, default 20, max 100), response_format (all optional except projectId)Search Console (GSC)
This tool requires a linked Google Search Console site. When the project has none, the backing endpoint returns a
409 error with { code: "gsc_not_connected", message, howToFix } — the howToFix field points at Settings → Integrations in Searchable, where you can connect GSC and then retry.get_gsc_performance
Live Google Search Console organic performance.
report="overview" (default): clicks/impressions/CTR/average position plus a prior-period comparison. "top_queries" / "top_pages" / "countries" / "devices": ranked rows for that dimension. "trend": daily timeseries with window totals. "opportunities": quick-win queries (ranking position 4-15, ≥100 impressions, under 5% CTR), sorted by impressions and drawn from the site’s top 250–1,000 queries. "position_buckets": query-count distribution across top 3 / page 1 / page 2 / beyond 20, over the top 1,000 queries. Pass period ("7d"|"28d"|"30d"|"90d"|"16m", default "30d"; an unrecognized value falls back to "30d") or an explicit startDate+endDate (YYYY-MM-DD, both together, start on or before end — otherwise invalid_argument). GSC data lags ~3 days: an explicit range is clamped to the last day Google has published and to its 16-month retention, and the response’s window then carries clamped/requestedTo (or truncatedStart/requestedFrom).Parameters: projectId (required), report (default overview), period, startDate, endDate, limit (top_queries/top_pages/countries/opportunities only; defaults 25/25/100/20, max 250/250/250/100), response_format (all optional except projectId)AI Traffic
First-party AI-traffic measurement from the tracker/CDN pipeline — Searchable’s flagship differentiator, distinct from GA4 above (which reads Google’s own analytics). Six
get_ai_traffic reports (overview, crawlers, referrals, top_cited_pages, human, correlation) need any connected source — crawler logs, a CDN integration, the Searchable tracker, or a linked GA4 / Search Console / Bing site; sitemap_coverage, attribution, and logs need a crawler-log or CDN source specifically. When the required source is missing, the backing endpoint returns a 409 error with { code: "traffic_not_connected", message, howToFix } — the howToFix field points at AI Traffic → Setup in Searchable, where you can connect a source and then retry. get_page_metrics degrades instead of failing: a block it can’t read comes back as available: false with a reason.get_ai_traffic
First-party AI-crawler and AI-referral traffic.
report="overview" (default): crawler + AI-referral totals by platform, plus the top crawled pages. "crawlers": per-page AI-crawler activity, capped by limit (no deep pagination at the tool layer — use the REST endpoint’s offset for that). "referrals": daily AI-referral session timeseries by platform. "top_cited_pages": top pages driving AI-referral traffic for one platform — platform is required for this report. platform is validated strictly, and an unrecognized value returns an error rather than a silent empty result: crawlers and referrals accept all eight platform IDs (openai, anthropic, google, perplexity, microsoft, deepseek, xai, meta), while top_cited_pages accepts only the first five. platform filters only crawlers, referrals, and top_cited_pages — overview always returns every platform, and the five further reports below ignore it too, so filter with crawlers or referrals instead. Long-tail vendors that can appear in output rows (e.g. amazon, you.com) are deliberately not filterable.overview, crawlers, and correlation take groupBy="platform" | "botCategory" | "botName". This extends the same tool rather than adding traffic tools. Omitting it preserves the legacy response; botCategory adds byCategory, botName adds byBot (name, ID, vendor, and category), and platform adds correlation’s per-page byPlatform crawl split. Overview and crawlers keep their existing byPlatform arrays with every grouping.The public bot categories are ai_training, ai_search, ai_assistant, ai_agent, and search_engine. ai_assistant is the distinct user-triggered class for ChatGPT-User, Claude-User, and Perplexity-User. A per-page ai_training → ai_search → ai_assistant view is therefore possible, but ai_search means retrieval/search crawling — actual answer citation remains a separate visibility metric.Five further reports cover the rest of the AI Traffic surface:sitemap_coverage— per bot (named, with vendor and category): how often it fetched your sitemap, how many listed pages it discovered, and the median lag from a page appearing in the sitemap to its first crawl. It answers how fast and how completely each crawler is picking your sitemap up; it does not enumerate individual uncrawled URLs.human— real human sessions that arrived FROM an AI assistant, split by platform. The conversion half of the funnel the crawler reports open. ChecksummarySource: site-wide totals come from the first-party tracker while the AI figures fall back to GA4 when no tracker is installed — in that split state everysummaryfield andpercentOfTotalarenull(not0), and a failed GA4 read surfaces asaiReferral.sourceErrorrather than as zeroes.correlation— per page, crawls and AI-referred sessions over the same window, joined by path. Its optional grouping classifies the crawl side only. This is co-occurrence, not attribution: nothing establishes that a session followed a crawl or came from a named bot. Ranked by sessions, but the ranked population is the upstream union of the top-500 crawled and top-500 human-traffic pages —pagesConsideredis a floor, andpopulationTruncatedtells you when pages are certainly missing.attribution— traffic by UTM tuple, referrer domain, and bot category. The underlying query stops at 100 rows;truncated: truemarkstotalRowsas a floor.logs— the raw request feed, filterable bypath,statusCode,botsOnly, andhost, cursor-paginated: pass a page’snextCursorback as bothcursorTimestampandcursorEventId(over MCP, sending only one half is ignored and page one comes back again; the REST endpoint rejects it). Row-capped (25 default, 100 max) because it is the one row-level report.ip_addressanduser_agentare never returned — the IP is personal data with no analytical value oncecountryis present, and the user-agent is superseded by the resolved bot identity.
host narrows any report to specific hostnames (comma-separated) — useful on multi-domain projects where “blog versus docs” is the question.Parameters: projectId (required), report (default overview), days (default 30, max 365), from/to, host, platform (required for top_cited_pages; used only by crawlers / referrals / top_cited_pages), groupBy (overview/crawlers/correlation only), limit (default 20 for crawlers, 10 for top_cited_pages, 25 for correlation / attribution / logs; max 100), plus path / statusCode / botsOnly / cursorTimestamp / cursorEventId for report=logs, response_format (all optional except projectId)get_page_metrics
The per-URL rollup: one page’s AI citations (
inlineCitations — answers linking it in their text — and sourceUses — answers that consulted it), AI-referral sessions by platform, and AI-crawler visits by bot, as daily buckets in one call. url takes a full URL or a bare path such as /pricing, resolved against the project’s domain. Each block degrades on its own to available: false with a reason — traffic_not_connected, external_url (the host isn’t one of the project’s verified domains), or citation_lookup_failed — and a page that was never cited returns zeros, not an error. An empty or invalid URL, or a bare path on a project with no domain, returns invalid_argument.Parameters: projectId (required), url (required), days (default 90, max 365), response_format (all optional except projectId and url)Shopping visibility
Requires a plan with Shopping Analytics — every Brand and Agency plan, plus legacy
Professional and Scale; Free and Starter don’t include it. On the default
summary view,
get_shopping_visibility returns available: false (not an error) when the project simply has no
shopping/product data yet — that’s a data-presence state, not a plan or connection problem, and
needs no setup step; there the plan gate only surfaces once there’s data to fetch. The
timeseries view and a productId lookup check the plan first, and with no data return an empty
series or not_found rather than available: false.get_shopping_visibility
AI shopping/product visibility (Peec-parity) — products surfaced in AI shopping/product-carousel responses.
view="summary" (default): ranked product list (rank, mentions, dominant platform) plus an activation-rate summary. view="timeseries": daily activation-rate/product-count trend. Pass productId (the id from a summary row — the product’s title) for full detail on one product instead: occurrences, vendor/pricing rows, a real per-platform breakdown, and up to 50 recent responses that surfaced it — productId overrides view. The summary view accepts the brand / topic / location filters and echoes appliedFilters + availableFilters. An interactive Shopping Shelf card also renders automatically beside the answer on the summary view for Apps-capable clients — see below.Parameters: projectId (required), days (default 30, max 365), platform (comma-separated; every view), productId (optional — switches to detail view; an unknown product returns not_found), view ("summary" | "timeseries", default summary), limit (summary view, default 50, max 100), offset (summary view), topicId, unbranded, branded, country, locationId (the brand / topic / location filters apply to the summary view only), response_format, render (all optional except projectId)AI ads
Ad data appears once tracked prompts surface sponsored ad units. An empty result means either that
nothing has been captured yet or that a filter matched nothing.
topicId and locationId
each take one ID — a name, a list, or anything else that isn’t a well-formed ID is refused with
invalid_params, while a well-formed ID that matches nothing returns an empty result (promptId
also takes the prompt’s text, and text matching no prompt returns not_found rather than an empty
result). platform takes a comma-separated list: a mixed list silently returns just the
recognized platforms, and a list with none recognized matches nothing. Retry without filters
before reporting that a project has no ad data, and state that the retried figures are unfiltered.
adCount/appearances count ads we scraped in AI answers, not ad-platform impressions, and
commercial ad libraries don’t publish spend, so there are no cost or impression figures.get_ads
Sponsored ads surfaced in AI answers.
view="advertisers" (default): who is running ads, ranked by ad volume with share % and a competitor flag, plus your own brand’s ad share-of-voice and rank. view="creatives": the individual ad creatives (advertiser, headline, appearances, prompts) — narrow with advertiserKey, promptId (a prompt id or the prompt’s text), or search. view="prompts": which tracked prompts surface the most ads, with ad coverage %. view="timeseries": per-advertiser ad-frequency trend.Parameters: projectId (required), view ("advertisers" | "creatives" | "prompts" | "timeseries", default advertisers), days (default 30, max 365), filter ("all" | "competitors", view=advertisers), advertiserKey (view=creatives/timeseries), promptId + search (view=creatives), sortBy (promptText|adUnits|coveragePct|engines|totalResponses, default adUnits) + sortDir (view=prompts), limit (advertisers default 20/max 100, creatives 25/200, prompts 50/500), platform, topicId, locationId, unbranded, branded, response_format (all optional except projectId)Write actions
trigger_audit, refresh_sitemap, add_pages, remove_pages and update_site_issues require a
grant/key with the write scope; generate_report works on any connection. generate_report,
refresh_sitemap, add_pages, remove_pages and update_site_issues don’t execute without confirm: true — omit it and the tool returns a dry-run preview (what would happen; for
generate_report, whether your plan allows sharing and white-label) with no side effect.
trigger_audit starts straight away; pass dryRun: true to preview it first (page count and
audit quota).generate_report
Generate + publish a shareable report and return its public URL.
reportType=sentiment|visibility|combined (default sentiment). Works on a read-only connection, as sharing does in the app; the workspace’s sharing policy and a plan with report sharing still apply. Note the Only suffix on the brand filters here — unbrandedOnly/brandedOnly — unlike every read tool’s unbranded/branded.Parameters: projectId (required), reportType, timeRange ("7d"|"30d"|"90d"|"365d", default 30d), platforms, topicIds, locationIds, unbrandedOnly, brandedOnly, title, status ("published"|"draft", default published), whiteLabel (requires a white-label-entitled plan), confirm (all optional except projectId)trigger_audit
Start a technical + AEO site audit for the given
pageIds or a selection (pinned pages, the whole site, a path with exclusions, or page types); returns the job id. With neither, no audit starts: it returns selectionRequired: true with the choices (pinned count, whole-site count, largest sections, the per-audit limit), so the assistant can ask which scope you want. A selection audits at most the smaller of the plan’s per-audit limit and the audits left this month (pinned pages first, then never-audited pages (most visitors where known, from GA4 page views, then shallowest path), with a fifth of the rest kept for re-auditing the oldest audits; skippedOverCap counts the rest), and leaves out error pages unless they are pinned. Results land on get_site_health (view="audits"). Needs write access to the project, as starting an audit in the app does (a workspace viewer gets forbidden). Consumes the monthly audit quota (one unit per page) and is capped per plan in pages per audit — over the cap returns bulk_limit_exceeded, so pass a smaller pageIds list. Unknown pageIds are skipped (no_pages when none remain). Pages already being audited are skipped too and counted in skippedInFlightCount; when every page is already being audited, nothing starts and it returns alreadyInProgress: true with pageCount: 0 and no job id. If another audit of the project is starting at that moment, it waits briefly, then returns an audit_lock_busy error and starts nothing; retry after a few seconds. The plan cap counts every requested page; the quota counts only the pages it starts. Blocked for pitch projects; an archived project returns project_not_runnable.Parameters: projectId (required), pageIds (optional), selection (optional — { kind: "pinned" | "all" | "path_scope" | "page_types", includePath?, excludePaths?, pageTypes?, subdomain? }), dryRun (optional)refresh_sitemap
Refresh the project’s sitemap. With no
urls or paths: a full refresh in the background — new sitemap pages are added, pages that left the sitemap are removed (soft, restorable), and pages you added or removed yourself are left alone; returns the job ids. With urls and/or paths (path prefixes such as /product/, matched on whole segments): only those pages are added, and only if the project’s saved sitemap lists them; nothing is removed; the answer lists each page as added, restored, skipped or rejected with a reason (not_in_sitemap, no_sitemap_match, user_removed, …). For pages outside the sitemap use add_pages. Read the result with get_site_health (view="pages"). Needs write access to the project (a workspace viewer gets forbidden). Blocked for pitch projects; an archived project returns project_not_runnable.Parameters: projectId (required), urls (optional), paths (optional), confirm (optional)add_pages
Add up to 500 pages to Site Audit, whether or not the sitemap lists them: absolute URLs or paths on the project’s domain or its subdomains. They are added as your own, so a sitemap refresh never removes them; a page removed earlier is restored. Answers per URL (added / restored / skipped / rejected), with the page ids to pass to
trigger_audit. Needs write access to the project; blocked for pitch projects.Parameters: projectId (required), urls (required), pageType (optional), confirm (optional)remove_pages
Remove up to 500 pages from Site Audit by the
id column of get_site_health’s pages view. Removal is soft: audits and issues are kept, and add_pages restores a page. Returns the ids removed and those that were not this project’s current pages. Needs write access to the project; blocked for pitch projects.Parameters: projectId (required), pageIds (required), confirm (optional)update_site_issues
Rolling out: listed only on connections where it is enabled. Act on Site Health issues the way the app’s Issues tab does:
pause (for a week, a month by default, or until_resumed), resume, mark_fixed or reopen. Name issue titles to act on every page each issue affects (up to 50 titles at once), or issue ids for one issue on one page (up to 500). A paused issue leaves open counts and page issue counts until it is resumed or the pause ends; get_site_health lists it under status: "paused" with pausedUntil. Answers how many issues and pages changed. Without confirm: true it returns those counts and changes nothing. Needs write access to the project; blocked for pitch projects.Parameters: projectId (required), action (required), issueTitles or issueIds (one is required), pauseFor (optional), confirm (optional)Project and prompt management
Every write tool in this section needs a connection minted with the specific capability named on
its card — see the note under Available tools above.
create_project,
create_pitch and move_pitch_to_client need confirm: true: without it the call returns a
preview of what would happen (and current quota state) and changes nothing. manage_pitch needs
it for the actions that spend something or can’t be undone (extend, refresh, convert, and a
reactivate that would use the pitch’s extension). Every other write here acts straight away, as
the app’s own controls do; pass dryRun: true to preview one first.create_project
Create a project and set it up as the app’s Add project flow does: the project, its
competitors, brand profile, default location and onboarding record. It counts toward the
workspace’s project limit. The assistant interviews you first, one question at a time, each
with an answer it suggests from the brand’s website or a web search: the brand name and
summary, where the brand sells, its competitors (list your own or pick from its suggestions),
other names it goes by, and whether to generate prompts. Say “use your suggestions” to skip
the rest. The preview lists everything that will be saved.
generatePrompts: true writes up
to 50 tracked prompts in the background, as the app does, within your prompt allowance.
For a prospect or a trial, use create_pitch instead. Needs project:provision. A connection
scoped to specific project(s) can’t use this tool even with that capability — creating a
project is a workspace-level action outside what a project-scoped grant or key covers — and is
refused with forbidden.Parameters: workspaceId (from whoami’s workspaces, one with canCreateProjects: true), domain, brandName, brandSummary, reach (global, national-global, nationwide, regional or local), country (ISO code, e.g. GB), competitors (1–20 website domains, or { domain, name } entries), generatePrompts (all required), city and state (for regional or local reach: a state alone covers the whole state, a city is placed in its state, and a US city in more than one state needs state; one that can’t be placed leaves the default at the whole country, with a note), language, brandNameDisambiguation, brandAliases, name (defaults to the brand name), description, confirmarchive_project / reactivate_project
Archive or reactivate a project, as the app’s Archive and Reactivate actions do. An archived
project stops running its scheduled checks and keeps its data;
list_projects marks it
“(archived)”. A workspace keeps at least one active project, so archiving its only one is
refused with last_domain, and a pitch is refused with pitch_not_supported (manage_pitch
declines, hides and reactivates a pitch). An archived
(paused) project’s prompts do not count toward the workspace prompt quota, so reactivating one that
would take the workspace over it is refused with quota_exceeded. Both need
project:manage and write access to the project (a workspace viewer gets forbidden).Parameters: projectId (required), expectedRevision (fails with stale_revision if the project has changed since), dryRunlist_pitches
List the pitches this connection can see: 7-day trial projects run for prospects, on each
workspace’s shared pitch prompt allowance. It works like the app’s Pitches tab: every pitch,
whatever its status and converted ones included, in the tab’s four views. Each pitch carries
its status, expiry and
daysLeft, whether its one 7-day extension is used, its manual
refreshes (limit, used, remaining), whether it is hidden from the project picker, its
tracked prompt count, and whether it can be reactivated (canReactivate) or extended
(canExtend, only in its last 48 hours) right now. A converted pitch is a regular project now
and carries only its id, name, domain, workspace and convertedAt. Each workspace where you
can create pitches or read one also carries whether its plan has pitches (pitchesAvailable),
whether your role and plan allow creating them there (canCreatePitches), and its pitch
allowance (used, limit, remaining). A workspace whose API access is switched off is left
out. Pitch ids work with every project read tool. Bare read: no capability needed.Parameters: workspaceId (optional — an id from whoami’s workspaces), view (optional — open, closed, converted or all, the default), response_format (optional)create_pitch
Create a pitch: a 7-day trial project for a prospect, on the workspace’s pitch prompt
allowance. It is made as the app’s Add project flow makes one with the pitch option: the pitch,
its competitors, brand profile, default location and onboarding record, with 5 manual refreshes
and one 7-day extension. The assistant runs the same interview as for
create_project, plus
which workspace has pitches (list_pitches shows each workspace’s canCreatePitches). A
pitch’s prompts count against the workspace’s pitch allowance, never the plan’s prompt
allowance; generatePrompts: true writes up to 50 tracked prompts in the background, within
it. It needs a plan with pitches (an Agency plan or legacy Scale access) and a role that can
create projects (an owner, super admin or admin). If the domain is already a project or a
pitch of yours in any workspace, it is refused and says which one; when that workspace is one
this connection can’t reach, the refusal names no project and no workspace. Without
confirm: true it returns a preview and creates nothing. Needs project:provision; a
connection scoped to specific project(s) can’t use it and is refused with forbidden.Parameters: the parameters of create_project without description: workspaceId, domain, brandName, brandSummary, reach, country, competitors, generatePrompts (all required), city, state, language, brandNameDisambiguation, brandAliases, name, confirmmanage_pitch
Act on a pitch as the app’s pitch controls do.
action is one of:reactivate: bring back a paused or expired pitch. With days left it resumes its remaining time; with none it uses the pitch’s one 7-day extension. A pitch with no days left whose extension is used can’t be reactivated: convert it.extend: add 7 days to an active pitch, using its one extension, only in its last 48 hours.refresh: run a new visibility report for an active pitch, using one of its 5 manual refreshes. While a report is already running for it (its first report, or one an earlier refresh or an unfiltered Run report started), the refresh joins that report and uses none.convert: turn the pitch into a client project with every feature unlocked; its prompts move onto the plan’s prompt allowance. It can’t be undone. A convert the plan’s prompt allowance can’t take is refused withquota_exceededand the numbers, before any preview.decline: pause an active pitch. Its prompts stop running and its data is kept; its expiry keeps running, and it can be reactivated later.hide/unhide: take a paused or expired pitch out of the project picker, or put it back. It stays inlist_pitcheseither way.
extend, refresh, convert, and a reactivate that would use the extension need
confirm: true: without it they return a preview and change nothing. The other actions act
straight away; dryRun: true previews any action, even beside confirm: true. The roles follow
the app’s pitch routes: extending and refreshing need write access to the pitch; converting,
declining, hiding and unhiding need manage access to it; reactivating needs the right to create
projects in its workspace. Needs project:manage.Parameters: pitchId, action (both required), confirm, dryRunmove_pitch_to_client
Move a pitch into a client workspace, as the app’s convert dialog does for a reseller: into an
existing client workspace, or into a new one created for it. The pitch becomes a client project
with every feature unlocked, its prompts move onto that workspace’s plan allowance, and it can’t
be undone. To convert a pitch inside its own workspace use
manage_pitch with convert. Only
a reseller’s owner or staff are offered this tool, and only while the reseller is in the
rollout; it isn’t listed for any other connection. Three calls, in this order: (1) with just
pitchId it returns the options: the workspaces the pitch can move into
(eligibleDestinations), the roles you may give (assignableRoles) and the agency staff a new
client can take (staffOptions); (2) with a destination it previews that move and changes
nothing, listing what moves, the blockers and the warnings, and for an existing workspace
a previewSignature; (3) with confirm: true it moves the pitch. As in the app, only the user
may type the pitch’s domain (confirmDomain) and acknowledge each warning
(acknowledgedWarnings): the assistant shows them each one and never fills either in itself. A
preview goes stale when the pitch or the workspace changes (preview_stale): preview again. A
connection scoped to specific project(s) can’t use it, and a destination whose API access is
switched off is left out of the options. Needs project:manage.Parameters: pitchId (required), destination ({ "kind": "existing", "workspaceId" } or { "kind": "new", "name", "workspaceType": "brand", "staff" }), previewSignature, acknowledgedWarnings, confirmDomain, confirmadd_prompts
Add up to 10 prompts in one call. They’re tracked straight away, as when you add prompts in
the app: the project’s next scheduled run checks them, and they count toward your prompt
allowance. The whole batch is checked against the allowance first; if it doesn’t fit, nothing
is added (
quota_exceeded), so archive some prompts first or add fewer. The prompts are then
saved one at a time, so a later prompt that fails (for example on a topic id that isn’t one of
the project’s) leaves the earlier ones added. Needs prompt:draft.Parameters: projectId (required), prompts (required — array of { text, intentCategory?, isBranded?, topicIds? }, 1–10; text up to 2,000 characters, intentCategory one of informational, commercial, transactional, navigational, post_purchase, topicIds up to 20 existing topic ids), dryRunupdate_prompt
Edit a prompt’s wording, intent, branded flag, or keyword metrics. Does not archive or restore
it — use
archive_prompt / restore_prompt for that. Needs prompt:draft. Pass
expectedRevision to fail with stale_revision instead of overwriting a concurrent edit; the
REST endpoint behind this tool accepts the same guard as an If-Match header instead.Parameters: projectId, promptId (both required), text, intentCategory, isBranded, keywordSearchVolume, keywordDifficulty, expectedRevision, dryRunupdate_prompts
Bulk-edit existing prompts in place: read them with
list_prompts (each row carries its id
and currentRevision), change what you need, and send up to 500 rows back. Each row names a
prompt by promptId and gives the end state for any of text, isBranded, intentCategory,
topics and locations; a field you leave out is left alone, and a row that changes nothing
writes nothing. A reworded prompt keeps its id and past answers, and its old wording stays as a
revision. Pass each prompt’s expectedRevision so one edited since you read it comes back as
conflict instead of being overwritten. A dry run plans the edit but does not check the prompt
allowance; adding locations to tracked prompts can still be refused with quota_exceeded when
you apply. Result entries carry each prompt id trimmed and lower-cased, so match ids
case-insensitively. Needs prompt:draft.Parameters: projectId, prompts (both required — array of { promptId, expectedRevision?, text?, isBranded?, intentCategory?, topics?, locations? }, 1–500; locations items are { country, city?, state? }, at most 5 per prompt), dryRunarchive_prompt / restore_prompt
Archive or restore a prompt, as the app’s Archive and Restore actions do.
archive_prompt
stops tracking it; its history and metrics are kept. restore_prompt tracks it again, within
your prompt allowance. Both need prompt:activate — a different capability from
prompt:draft, so a connection that can only add and edit prompts can’t archive or restore
existing ones.Parameters: projectId, promptId (both required), expectedRevision, dryRunrestore_prompt_wording
Restore a prompt’s wording to an earlier revision by appending a new revision carrying that
text — history is never rewritten in place, so restoring revision 1 after edits to 2 and 3
produces revision 4. Only wording changes; tracking, topics, and locations are untouched. Needs
prompt:draft; expectedRevision is required, not optional.Parameters: projectId, promptId, revision, expectedRevision (all required), dryRunget_prompt_revisions
A prompt’s wording history, newest first, with its current revision number. Bare read — no
capability needed, and unaffected by the pitch freeze below (reads are never blocked, only
mutations are).Parameters:
projectId, promptId (both required), limit (default 50, max 200), beforeRevisionAn inactive pitch project (declined / expired / archived) refuses every prompt write above and
every brand-profile, default-location, competitor, topic, and source classification rule write below with
INACTIVE_PITCH_PROMPT_MUTATION (HTTP 409 over REST) — it’s a frozen sales-review snapshot, not a live project.
update_opportunity_status is different: an active pitch has no opportunities feature at all
(pitch_not_supported; 403 over REST), matching get_opportunities. All of them also enforce
your own role in the workspace — a connection without the tool’s capability gets missing_scope,
and one belonging to a workspace Viewer gets forbidden rather than a silent no-op.
add_competitors, update_competitor, update_brand_profile, set_default_location and
update_alternative_names (adding and removing names), like the in-app Knowledge Base and
Competitors tab, are open to Members on the project as well as Owners, Super Admins and Admins.update_brand_profile
Update the project’s knowledge-base brand fields — name,
positioning (the app’s Brand Context), description, category, influence (the reach:
global,
national-global, nationwide, regional or local), language (a code the app offers, e.g.
en-GB), website URL, case sensitivity (the app’s Exact match only), disambiguation text, and
topics (the brand’s products or services as short labels — not the prompt topics
create_topic makes). Also writes the Knowledge Base’s two writing documents: tone (Tone /
Writing Style — voice, brand adjectives, phrases to avoid, language to include) and memory
(Memory), free-form markdown the app’s agents follow when they write. A document is replaced
whole ("" clears it), so read it with get_brand_profile first to edit part of one; the
result’s updatedDocuments lists the documents written. Only the fields you pass change;
topics replaces the whole list. Does not touch connected entities (alternative names have
their own tool, update_alternative_names), E-E-A-T data, or the default location (that’s
set_default_location). Needs
knowledge:manage (a key scope name, not a role: Members on the project can use it too).Parameters: projectId (required), then any of name (up to 200 characters), positioning (up to 5,000), description (up to 5,000), category (up to 200), influence, language, websiteUrl (up to 2,000), caseSensitive, brandNameDisambiguation (up to 2,000), topics (up to 50 labels), tone (up to 100,000), memory (up to 100,000), plus dryRunset_default_location
Change an existing project’s default location: the Knowledge Base’s Location in the app. Send
the
country (an ISO code such as US), plus a state or city where it matters, the same
way create_project takes them. A country alone makes the whole country the default.The state or city is looked up, and the place found is saved, never the text you send: austin
with state: "TX" is saved as Austin, Texas. If a place can’t be found, nothing changes and the
error says why. location_not_placed covers a state or city that isn’t recognised, and a US
city found in more than one state when state is missing. location_lookup_failed means the
lookup itself was unavailable, so try again later.Prompts follow the change from their next run:- Tracked prompts that use the default move to the new place.
- So do prompts whose only location is the old default, even when it was set on the prompt itself.
- Prompts with any other location keep their locations.
- Answers already collected stay under the place they were collected for.
location (countryCode, city, region, label),
previousLocation, promptsMoved and promptsKeepingOwnLocation; changed is false when
the place already is the default. Needs knowledge:manage (Members on the project can use it
too).Parameters: projectId, country (both required), state, city (up to 200 characters each), dryRunupdate_alternative_names
Add, remove or replace the project’s alternative names: other names the brand goes by, such as
a former name or a local one, which count as the brand in every report. This is the app’s
Knowledge Base → Profile → Alternative names, and it behaves the same way. Send
add and/or
remove, or replace on its own to set the whole list of names you add (an empty list
removes every name you added). Names are matched ignoring case. A name the project already has
is left as it is and listed in alreadyPresent. Removing a name it doesn’t have is refused
with not_found, and nothing changes. A project holds up to 25 names you add, of up to 120
characters each. Everything is checked before anything is written, and the result lists the
names the project has now.Names added automatically. For the languages a project’s prompts run in, the names of the
brand (and of the alternative names you added) and of its direct competitors are looked up in
those languages. What is found for the brand is added to this list, so that answers in another
language count as the brand; what is found for a competitor counts for that competitor. The
brand’s automatic names are listed with the others and don’t count toward the 25, and
replace keeps them unless the name they translate is removed.Answers already collected follow the change, in the background:- An added name’s mentions filed under Other companies move to the brand, and its visibility and share of voice are recalculated.
- A removed name’s brand mentions, including any an earlier add moved, go to a competitor of that name, which is created if the project has none. That is not a round trip: mentions that sat under Other companies before the add end up with that competitor.
- A removed name that was added automatically goes the other way: its brand mentions move to Other companies, no competitor is created, and the name is not added again.
- Removing a name you added also removes the names added automatically as its translations.
The result lists them in
cascaded, and their brand mentions move to Other companies too. They can come back if the name is added again. A name you list inaddorreplacethat the removal strips is incascaded, not inalreadyPresent. - On a paused project, answers already collected are not moved; answers collected after it is resumed count the new list.
knowledge:manage.Parameters: projectId (required), add, remove, replace (up to 25 names each, each up to 120 characters), dryRunupdate_brand_fact_status
Mark one AI-observed brand fact, a statement AI platforms make about the brand, as correct
(
pass) or incorrect (fail), or clear the verdict (unverified). This is the app’s brand-facts
verification, and the app shows the result. Take the fact’s id from get_brand_profile; an id
that is not one of the project’s facts is refused with not_found, and nothing changes. The
result gives the fact with its new status, and previousStatus.On an active project on a paid plan, marked facts feed the daily update of the brand context
(the app’s Brand Context, positioning in get_brand_profile): correct facts are worked into
it, and incorrect ones are noted as not true. Clearing a verdict later doesn’t take back what an
earlier update wrote. Needs the Member role and knowledge:manage.Parameters: projectId, factId, status (all required), dryRunadd_competitors
Add 1–20 competitors, each by website domain and optionally named, to the project’s tracked set. With
source: "manual" and a single entry it also runs the duplicate check the in-app “add
competitor” dialog runs, refusing an existing domain, name, or name variation with conflict.
An entry matching an already-tracked competitor isn’t added twice — that competitor is updated
instead — and the project’s own domain is skipped. Needs competitor:match.Parameters: projectId (required), competitors (required — 1–20 entries, each a website domain such as example.com or {domain, name}; a company name alone is refused with invalid_params), source ("manual" or "ai_discovery"; omitted acts as ai_discovery), dryRunupdate_competitor
Edit a tracked competitor as the in-app competitor sheet does: rename it, change its website
domain, make it a direct or a SERP competitor (
isDirectCompetitor), and add or remove the
other names it goes by (name variations), which is how its mentions are recognised in AI
answers. Changing the domain, or making it direct, re-matches its past mentions in the
background. Everything is checked before anything is written: a variation that is another
competitor’s name is refused with conflict (merge the two in the app instead), and removing a
name it doesn’t have, adding and removing the same name, or a domain that isn’t a website
domain is refused with invalid_argument. A name confirmed on another competitor moves to this
one. The result lists its name variations, so a dry run with no fields shows them. Needs
competitor:match.Parameters: projectId, competitorId (both required — the id from get_competitors), name, domain, isDirectCompetitor, addVariations, removeVariations (up to 20 names each), dryRuncreate_topic
Create a user-authored prompt topic — the same row the in-app Topics tab creates. Needs
prompt:draft (topics organize prompts, so they share that surface’s capability). A name the
project already uses (ignoring case; archived topics excepted) is refused with conflict, dry
run included, and the error carries the existing topic’s id as existingTopicId.Parameters: projectId, name (both required; name up to 200 characters), description (up to 2,000), seedKeyword (up to 200), category ("blind_spot", "opportunity" or "strong"), dryRunupdate_topic
Edit a prompt topic as the in-app Topics tab does: rename it, change its seed keyword, archive
it (
status: "archived"), or restore an archived one (status: "active"). Archiving takes the
topic off every prompt it was on, and restoring it later does not put it back on them. A name
another live topic uses is refused with conflict and that topic’s existingTopicId, dry run
included — as is restoring a topic whose name a live topic has taken since. A call with none of
name, seedKeyword, or status returns invalid_params. Needs prompt:draft.Parameters: projectId, topicId (both required — the id from get_topic_analysis), name, seedKeyword, status ("active" or "archived"), dryRunupdate_opportunity_status
Mark an opportunity
completed or dismissed; a dismissal can carry a reason and feedback text,
which are ignored when completing. Needs opportunity:manage.Parameters: projectId, opportunityId, status (all required), dismissedReason, feedbackText (dismissals only, up to 2,000 characters each), dryRunPrompt Universe (lightweight)
This is the cheap, deterministic half of Prompt Universe — the buyer-question catalogue and code
gates, not the full research engine. You write the actual prompt text; these tools plan it,
then check and persist what you wrote. Both additionally need Prompt Universe to be available to
you and to the project’s workspace — an unavailable tenancy answers the same
not_found as a
project you can’t see, so a connection can’t tell “not offered here” from “doesn’t exist” by
comparing responses.get_prompt_brief
The buyer question types that matter at each funnel moment (first look, compare, buy, own) for
a business model, which are decisive, and how many prompts each moment and kind should carry.
Planning input only — calls no model, creates nothing. Bare read.Parameters:
projectId (required), businessModelId (e.g. 1.2; omit it and every question type is treated as optional), stages (any of tofu, mofu, bofu, post_purchase; default all four), count (default and max 500, capped by the workspace’s remaining prompt allowance)import_prompts
Add the prompts you wrote as tracked prompts, the same way
add_prompts does: the next
scheduled run checks them, within your prompt allowance. Starts no Prompt Universe run. Every
candidate is held to the Prompt Universe code gates before anything is written (no em/en dash,
no semicolon, the market’s spelling, no service request at the owning moment, no near-duplicate
of each other or of the project’s existing prompts), and one refusal refuses the whole batch
with invalid_params, naming each refused candidate and why. The whole batch is then checked
against the allowance (if it doesn’t fit, nothing is added: quota_exceeded); dryRun: true
runs both checks without adding anything. The writes themselves are not atomic: each
prompt commits on its own and re-checks your prompt quota, so a batch can still stop partway if
another write takes the room. Once writing starts, the response’s outcomes array says which
candidates actually landed (created, failed, or not_attempted) — retry only those that
aren’t created. Needs prompt:draft.Parameters: projectId, candidates (both required — 1–10 entries, each { text, stage, kind?, branded?, topicIds? }: text up to 2,000 characters, stage one of tofu, mofu, bofu, post_purchase, kind one of open, sentiment, competitor, topicIds up to 20 existing topic ids), market (US, the default, or GB; any other value skips the spelling check), dryRunSource classification rules
This tool needs the
source:classify capability, which write doesn’t include, and your own
role must let you edit the project: a Member on the project can, as in the app’s Source rules
page; a workspace Viewer gets forbidden.manage_source_classification_rule
Create, update or delete a source classification rule, or remove all of a project’s rules. A
rule sets the Source Type, and for a competitor rule the competitor, of every cited page under
a domain, a subdomain or a path: for example
linkedin.com/help and business.linkedin.com as
Owned (brand) while the rest of linkedin.com keeps its own type. The most specific rule
wins. Find rule ids in the parts that search_sources (withRules: true) and
get_source_detail return. An input the action doesn’t take is refused with invalid_params
rather than ignored, so remove_all with a ruleId changes nothing. It acts straight away, as
the Sources page’s editor does; pass dryRun: true first to preview how many stored citations
and answers would change type, and how. The response carries the rule, how many rules were
removed, that impact, and the project’s rule status. Numbers across the project, history
included, refresh within a few minutes, so don’t report them as updated until search_sources
returns rulesApplying: false. Refusals carry their own codes:
invalid_scope, host_outside_domain, missing_competitor, unknown_competitor,
duplicate_scope, rule_limit (200 rules per project), not_found for a rule id the project
doesn’t have, and forbidden. A pitch project that is no longer active refuses every action,
dry runs included, with INACTIVE_PITCH_PROMPT_MUTATION. Needs source:classify.Parameters: projectId and action (both required — create, update, delete or remove_all); create takes scope (a domain, subdomain, path or URL, e.g. linkedin.com/help) and citationType (brand, competitor, editorial, social, forum, review, institutional, third_party or other), plus optional withinDomain (the domain the scope must fall under) and competitorId (required for a competitor rule — the id from get_competitors); update takes ruleId and citationType, plus optional competitorId; delete takes ruleId; remove_all takes nothing. Every action takes dryRunRemoved tool names
Earlier iterations of this MCP shipped 35 individual tools. When those were consolidated, 26 of the old names stayed callable as deprecated aliases. Those aliases were removed in August 2026 — calling one of the names below now returns an unknown-tool error. Use the replacement.
Nine other pre-consolidation names kept their exact original name as a primary tool at the time. Six still do —
list_projects, list_articles, get_article, get_opportunities, get_sentiment, and get_query_fanout; the other three (get_visibility_history, get_sentiment_history, get_sentiment_competitors) were folded into selector views in August 2026 and are now deprecated names — see the next section.
The four
get_source_* breakdown rows above are the one case where the removed name did something
no MCP tool now does: breakdown (and get_source_trend’s group) were arguments only those
aliases accepted. get_source_trends returns the top-source-domain trend directly and has no
breakdown argument. For the content-type, source-type, or article-type breakdown, use the REST
endpoint.Deprecated tool names
The August 2026 family-grid consolidation folded four reads into selector parameters on their family’s primary tool. Unlike the removed aliases above, these four names still work — same handler, byte-identical payload — so existing scripts and scheduled jobs keep running. They are scheduled for removal after 2026-10-15 (the same ~60-day window the removed aliases got); move to the replacement call before then. The REST endpoints behind these reads (GET /visibility/history, GET /sentiment/history, GET /sentiment/competitors,
GET /domain-authority) are not deprecated — the 12-month REST deprecation
policy governs those, and nothing REST-side is scheduled for
removal.
Interactive cards
Nine tools render an interactive card beside their answer in MCP-Apps-capable hosts (Claude
web/desktop, ChatGPT, Goose, VS Code — all implement the same standard):
A card hides itself on a call whose answer it can’t draw honestly:
get_visibility on a
platform-filtered call and on group_by=prompt|location|date, get_share_of_voice on
group_by=date, get_sentiment on view=history|competitors, get_topic_analysis on
view=prompts|heatmap, and list_prompts on status="untracked"|"suggested". Each of these nine
tools also takes an optional render boolean: pass false when the assistant only needs the
numbers (to summarize or feed into another call) and no card should be drawn; omitting it draws the
card, as before. Hosts without MCP Apps support just see the normal text/JSON answer. Cards are
dark/light aware and have an Expand button for a fullscreen view.
Where a card has a period control you switch window inside the card rather than sending another
message — the card queries the tool itself and remembers each window it has already loaded, so
returning to one is instant.Pagination
Tools that return lists are paginated so you can read complete datasets without silent truncation. The one exception islist_articles: a call returns at most 100 rows, and summary.total gives
the full count.
Per-prompt visibility
get_visibility with group_by: "prompt" is fully paginated. Every response includes a pagination object that tells you whether more prompts exist and exactly how to fetch the next page:
- Call
get_visibilitywithgroup_by: "prompt"(defaults:limit100,offset0). - While
pagination.hasMoreistrue, call again withoffset=pagination.nextOffset. - Stop when
pagination.hasMoreisfalse.
limit accepts 1–500 prompts per page. The total number of prompts you can page through is unbounded — paging in fixed-size chunks scales to projects with thousands of prompts.
Other list tools
Other list-returning tools page withlimit + offset too: get_opportunities (default 100, max 500), search_sources (default 20, max 1000), get_source_detail with include: "responses", get_query_fanout’s project aggregate (default 50, max 50 — the prompt_id drill-down isn’t paginated), get_prompt_answers (default 10, max 50 — pass the previous call’s nextOffset back as offset), list_prompts, get_competitors (list view), get_site_health (view=pages|issues), and get_shopping_visibility (summary view). get_source_detail’s URL lists (include: "urls", or level: "url" without a url for the flat cross-project listing) are cursor-based: pass the previous response’s nextCursor as cursor until hasMore is false.
Example prompts
Visibility analysis
Site audit
Content
Use cases
Automated issue fixing
Pair the MCP with a coding assistant to retrieve AEO/SEO issues and apply fixes in your codebase:For developers
- Query AEO/SEO issues while debugging frontend code
- Check if code changes would impact page audit scores
- Review article content without leaving your IDE
For AEO/SEO teams
- Pull visibility summaries during standups
- Extract audit data for reports
- Track issue resolution progress
For content teams
- Review article status and metadata
- Pull full article content for editing
- Track content coverage across topics
Troubleshooting
Connection failed or 403 Forbidden
Connection failed or 403 Forbidden
- Confirm the server URL is exactly
https://app.searchable.com/api/mcp-server/mcp(browser-sentOriginheaders are validated against an allowlist — hosted connectors normally call server-side without one, so they’re unaffected). - Check your API key starts with
sea_and is enabled for MCP in Searchable settings. - Restart your MCP client after config changes.
The browser consent page won't complete
The browser consent page won't complete
- Make sure you’re logged in to Searchable in the same browser, then retry the connection from your client. - The authorization link is single-use and expires after a few minutes — if you left it open, restart the connection from your client to get a fresh one. - On the consent screen, select at least one project (or leave all selected) before clicking Authorize.
Legacy API key rejected (401)
Legacy API key rejected (401)
- Confirm the key starts with
sea_and hasn’t been revoked in Manage Account → Integrations → MCP → Access tokens. - Confirm the key’s workspace is on a paid Searchable plan — MCP is unavailable on the Free plan.
No projects returned
No projects returned
- Confirm you have projects in your Searchable account. - Check that the API key belongs to the correct workspace.
get_ga4_traffic fails with 'ga4_not_connected'
get_ga4_traffic fails with 'ga4_not_connected'
- The project has no GA4 property linked that you can see, so the tool call returns a
409error withcode: "ga4_not_connected". - Connect Google Analytics 4 under Settings → Integrations in your Searchable dashboard (the error’showToFixfield carries the direct link), or ask the teammate who linked it to share it with the project, then retry the tool call.
get_gsc_performance fails with 'gsc_not_connected'
get_gsc_performance fails with 'gsc_not_connected'
- The project has no Google Search Console site linked, so the tool call returns a
409error withcode: "gsc_not_connected". - Connect Google Search Console under Settings → Integrations in your Searchable dashboard (the error’showToFixfield carries the direct link), then retry the tool call.
get_ai_traffic fails with 'traffic_not_connected'
get_ai_traffic fails with 'traffic_not_connected'
- The project has no crawler-log, CDN, or Searchable-tracker source connected, so the tool call
returns a
409error withcode: "traffic_not_connected". - Connect a source under AI Traffic → Setup in your Searchable dashboard (the error’showToFixfield carries the direct link), then retry the tool call.
get_shopping_visibility fails with 'plan_upgrade_required'
get_shopping_visibility fails with 'plan_upgrade_required'
- The workspace’s plan doesn’t include Shopping Analytics (Free and Starter don’t), so the
tool call returns a
403-equivalent error withcode: "plan_upgrade_required"— on the summary view only once the project has shopping data to fetch. - This is different fromavailable: false— that’s a normal 200 response meaning the project just has no shopping data yet, not a plan restriction. If you’re seeingavailable: falseinstead of this error, no upgrade is needed. - Upgrade to a plan with Shopping Analytics in Settings → Billing, then retry.
A tool returns 'rate_limited' or 'query_timeout'
A tool returns 'rate_limited' or 'query_timeout'
Neither means you’ve used up a daily or monthly quota.
query_timeout means the aggregation ran
past the server-side limit — reduce the days window or add filters (platform, topicId,
country), then retry. rate_limited has two sources. (1) The per-connection tool-call limit:
its error carries retryable: true and a message naming “tool calls per minute”, and it is safe
to retry after retryAfterSeconds. (2) A refresh_suggestions call to manage_associated_source
(where Associated Sources is enabled) while a source scout is already running or was queued
recently. Its error has no retryable field. Don’t retry that one automatically: read
get_associated_sources with view=suggestions and check latestRefreshCompleted. A new scout
is paid, so start one only after the error’s retryAfterSeconds have passed, and with the user’s
confirmation.A write tool returns 'missing_scope'
A write tool returns 'missing_scope'
The connection lacks the scope or capability the tool needs.
trigger_audit, refresh_sitemap,
add_pages, remove_pages and update_site_issues need write; the project and prompt management tools,
import_prompts and manage_source_classification_rule need the capability named on their card,
which write doesn’t include. Over OAuth, reconnect and turn on Allow write access on the
consent screen — it also grants the capabilities the client asked for. It’s offered only for
projects you can edit, so a workspace
viewer’s connection is always read-only. An API key’s scopes can’t be changed after it’s created:
generate a new access token with Allow write access on, which grants write and every
capability, and revoke the old one.Tools not appearing
Tools not appearing
- Restart your MCP client.
- Verify the server URL and JSON config syntax.
- Check the client’s MCP logs for errors.
Security
Read-only by default, write tools scope-gated
Every read tool is annotatedreadOnlyHint: true: it can only list and read data. trigger_audit, refresh_sitemap, add_pages, remove_pages and update_site_issues require a grant or key with the write scope — a read-only connection can’t invoke them at all (the call fails with missing_scope). generate_report publishes a shareable report link and works on any connection, as sharing a report is open to every project member in the app; the workspace’s sharing policy can switch it off. The write tools under project and prompt management, import_prompts and manage_source_classification_rule each need their own named capability instead. Most write tools act straight away, as the app’s own controls do; pass dryRun: true to preview one first. The ones where a mistake costs money, exposure, a project slot or a pitch’s one extension still need an explicit confirm: true on the call, and without it return a no-op dry-run preview. That is every call to create_project, create_pitch, move_pitch_to_client, generate_report, refresh_sitemap, add_pages, remove_pages and update_site_issues, and to manage_associated_source where Associated Sources is enabled; and manage_pitch for extend, refresh and convert, and for a reactivate that would use the pitch’s extension.
Token & key handling
- The OAuth login flow issues your client an access token scoped to exactly the projects and read/write access you approved on the consent screen — no API key is created or stored for this path.
- Every request is re-checked against the server-side authorization grant, so a revoked grant stops working immediately — the token in the client’s hands can’t outlive the consent it came from.
- Tokens refresh silently while the connection is in use; active connections persist, and an idle connection expires about 60 days after its last use, after which you simply re-authorize.
- On the legacy API-key path, the
sea_key is the bearer token — treat it as a secret, scope it narrowly, and revoke it in Manage Account → Integrations → MCP → Access tokens if it’s exposed.
Origin validation
The server validates browserOrigin headers against an allowlist (claude.ai, claude.com, the Microsoft 365 Copilot widget origins that interactive cards render from, plus dev hosts) to prevent cross-site abuse. For an allowed origin it also answers the browser’s CORS preflight and sends the matching CORS headers. Requests without an Origin header are allowed through — that covers native clients (Claude Desktop, Cursor, curl) and hosted connectors like Claude.ai and ChatGPT, which call from their servers rather than a browser. This is defense-in-depth; bearer-token auth is the primary control.
Best practices
- Rotate keys regularly — generate new keys periodically and revoke old ones.
- Use per-use-case keys — separate keys for separate clients makes revocation targeted.
- Revoke unused keys — remove keys you’re no longer using from Searchable settings.
API reference
Server details
Rate limits
Searchable limits MCP tool calls to 600 per minute per API key or OAuth connection. Every app using the same API key shares that budget, and it is separate from the REST API’s 600 requests/minute. Past the limit a tool returnsrate_limited with retryable: true and retryAfterSeconds; wait that long, then retry. Two server-side controls can make a call fail retryably:
- Tool-call limit. Over 600 tool calls in a minute returns
rate_limited; the error says how many seconds to wait. - Query timeout. Long aggregations are bounded by a server-side timeout, returning
query_timeoutwith a hint to narrow thedayswindow or add filters.
Support
All integrations
Browse the integrations directory
Contact support
Email our team

