MCP Integration - Searchable Docs

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. Supported clients:

Claude.ai (web and mobile) — add as a connector
Claude Desktop
Cursor
Windsurf and any other MCP-compatible client

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 (Starter, Professional, or Scale). API keys cannot be created on the Free plan.

How authentication works

The Searchable MCP server uses OAuth 2.1 with Dynamic Client Registration. You do not paste an API key into your MCP client’s config. Instead:

You add the server URL to your client (https://mcp.searchable.com/mcp).
On first use, the client opens a Searchable authorize page in your browser.
The page lists the read-only permissions being granted and asks for your Searchable API key.
Your client receives an OAuth access token and uses it for subsequent requests. Your API key is stored encrypted in the OAuth grant and is never sent to the client.

Only connect the Searchable MCP from trusted clients. The access token grants read-only access to your projects, visibility data, articles, and site audits.

Setup

Step 1: Get your API key

Open Settings

Navigate to Settings → Workspace → Integrations in your Searchable dashboard.

Create API key

Click Create API Key and give it a descriptive name (e.g., “Claude MCP”).

Copy the key

Copy your API key (starts with sea_). Store it securely — you won’t be able to see it again.

Step 2: Add the server to your client

Claude.ai
Claude Desktop
Cursor
Windsurf

Open Claude.ai → Settings → Connectors.
Click Add custom connector.
Enter URL: https://mcp.searchable.com/mcp
Claude will redirect you to the Searchable authorize page.
Paste your API key and click Authorize.

Add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "searchable": {
      "url": "https://mcp.searchable.com/mcp"
    }
  }
}

Restart Claude Desktop. On first use, it will open the authorize page in your browser — paste your API key and authorize.

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "searchable": {
      "url": "https://mcp.searchable.com/mcp"
    }
  }
}

Add to your Windsurf MCP configuration:

{
  "mcpServers": {
    "searchable": {
      "url": "https://mcp.searchable.com/mcp"
    }
  }
}

Step 3: Verify the connection

Once connected, ask:

List my Searchable projects

You should see a list of your projects with their names and domains.

Available tools

The Searchable MCP exposes 35 read-only tools. All tools are annotated with readOnlyHint: true — the server cannot create, modify, or delete data.

Need to generate and publish a shareable report (visibility, sentiment, or combined)? That’s a write action, so it isn’t an MCP tool — use the Searchable REST API’s POST /projects/{projectId}/reports endpoint instead. See Advanced API Usage.

Projects & visibility

list_projects

List all projects for the authenticated user. Returns names, domains, descriptions, and IDs.

get_visibility_summary

Overall AI visibility score, mention rate, and citation counts for a project over a given time window. Set unbranded=true to restrict every metric to non-branded prompts only.Parameters: projectId (required), days (optional, default 30), unbranded (optional, default false)

get_visibility_details

Per-platform visibility breakdown (ChatGPT, Claude, Perplexity, Gemini, Copilot, DeepSeek, Grok). Set unbranded=true to restrict the breakdown to responses from non-branded prompts.Parameters: projectId (required), days (optional, default 30), unbranded (optional, default false)

get_visibility_history

Time-series visibility data. Useful for tracking uplift, before/after comparisons, and trend analysis. Set unbranded=true to compute the per-report score and stats from non-branded prompts only.Parameters: projectId (required), days (optional, default 90), unbranded (optional, default false)

get_visibility_by_topic

Visibility broken down by topic, with metrics like mention rate, citations, average position, and top competitors per topic.Parameters: projectId (required), days (optional, default 30), unbranded (optional)

get_visibility_by_location

Visibility broken down by location (per-country/city) with share of voice, sentiment, avg position, and the change vs the prior equal-length period. Filter by country / locationId / platform / topicId; returns all tracked locations when unfiltered.Parameters: projectId (required), days (optional, default 30, max 365), country (comma-separated ISO codes or names, e.g. US,DE), locationId (comma-separated raw location IDs; NULL for the worldwide bucket), platform, topicId, unbranded (all optional)

get_visibility_by_prompt

Per-prompt visibility with optional filters (topic, branded/non-branded, platform). Paginated — the response includes pagination.hasMore and pagination.nextOffset; when hasMore is true, call again with that offset to page through every prompt.Parameters: projectId (required), days, topicId, branded, platform, limit (default 100, max 500), offset (all optional)

get_query_fanout

Query fanout for a project: the most frequent sub-queries AI models generate when answering tracked prompts, plus per-prompt fanout counts and a per-model breakdown. Use to see what AI engines actually search for around a brand. The per-prompt list is paginated.Parameters: projectId (required), days (default 30, max 180), platform (comma-separated, e.g. chatgpt,gemini), topicId, unbranded, limit (default 50, max 50), offset, topQueriesLimit (default 50, max 200) (all optional except projectId)

get_prompt_query_fanout

Detailed fanout for a single prompt: every deduped sub-query with per-query frequency, the models that issued it, and the query type (initial_search | model_query). Use after get_query_fanout to drill into one prompt.Parameters: projectId (required), promptId (required), days (default 30, max 180), platform (comma-separated), topicId, unbranded (all optional except projectId and promptId)

get_prompt_topics

List available topics for a project (useful to discover topic IDs for filtering).Parameters: projectId (required)

Site audits

get_website_issues

Current website issues grouped by severity (critical, high, medium, low).Parameters: projectId (required), status (“open” | “resolved” | “all”, default “open”)

get_page_audits

Technical, content, and AEO scores for each monitored page.Parameters: projectId (required)

get_monitored_pages

Page URLs, types, issue counts, and tracking status.Parameters: projectId (required)

get_issue_details

Detailed information about issues of a specific type, with fix recommendations.Parameters: projectId (required), issueType (“technical” | “content”)

Content & articles

list_articles

Article titles, status, topics, keywords, and metadata.Parameters: projectId (required), status (“draft” | “published” | “editing” | “all”), limit (max 100)

get_article

Full article content including HTML/markdown, outline, FAQs, schema markup, internal/external links, and SEO metadata.Parameters: articleId (required)

GA4 / Traffic

get_ga4_ai_referrals

Per-LLM-host AI Source Visitors from GA4 (ChatGPT, Copilot, Gemini, Perplexity, DeepSeek, and more) — weekly visitor series, latest complete-week week-over-week delta, and window total. Use this tool for AI-referral attribution. Requires a linked GA4 property.Parameters: projectId (required), weeks (optional, default 12, max 52)

get_ga4_traffic_trend

GA4 daily traffic trend showing users, sessions, and pageviews with window totals.Parameters: projectId (required), weeks (optional, default 12, max 52)

get_ga4_top_pages

GA4 top landing pages ranked by sessions, with users, bounce rate, and average session duration.Parameters: projectId (required), weeks (optional, default 12, max 52), limit (optional, default 20, max 100)

get_ga4_traffic_sources

GA4 traffic sources broken down by channel group and source. For the per-LLM-host split, use get_ga4_ai_referrals instead.Parameters: projectId (required), weeks (optional, default 12, max 52), limit (optional, default 20, max 100)

Sources

get_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 for a project.Parameters: projectId (required), days, sort, limit, offset, platform, topicId, sourceType, unbranded, country, locationId (all optional)

get_source_domain

Full detail for a single cited source domain — citation share, trend, top prompts, topics, platforms, and content-type breakdown. Use after get_sources to drill into a specific domain.Parameters: projectId (required), domain (required), days, platform, topicId, unbranded, country, locationId (all optional)

get_source_domain_urls

Cited URLs for a specific domain, with titles and content types. Cursor-paginated. Use to see which pages on a domain are cited by AI models.Parameters: projectId (required), domain (required), days, limit, cursor, sourceType, unbranded, country, locationId (all optional)

get_source_domain_responses

AI responses that cited a specific domain, with the originating prompt, platform, and cited URL. Optionally filter to a specific URL. Use to understand the context in which a domain gets cited.Parameters: projectId (required), domain (required), url, days, limit, offset, platform, topicId, unbranded, country, locationId (all optional)

get_source_urls

All cited URLs across a project, with domain, title, content type, and citation counts. Cursor-paginated. Use for a flat URL-level view of what gets cited.Parameters: projectId (required), contentType, days, limit, cursor, sourceType, unbranded, country, locationId (all optional)

get_source_page

Citation analytics for a single cited URL — total citations, prompts, mentions, and models that cite it. Returns 404 if the URL has not been cited in the project’s data window.Parameters: projectId (required), url (required, full URL), days (optional), unbranded (optional), country (optional), locationId (optional)

get_source_page_content

Cached scraped markdown and entity mentions (brand/competitor) for a cited page. Returns available: false if the page has not been scraped yet — never triggers a live scrape.Parameters: projectId (required), url (required, full URL)

get_source_content_types

Content-type distribution of cited sources (Blog, Product page, How-to, etc.) with citation rates and per-competitor breakdowns. Use to understand which content formats AI models cite most.Parameters: projectId (required), days, platform, topicId, unbranded, country, locationId (all optional)

get_source_types

Source-type summary (editorial, social, forum, review, institutional, etc.) showing citation counts and share per type. Use to understand which category of site AI models favor.Parameters: projectId (required), days, platform, topicId, unbranded, country, locationId (all optional)

get_source_article_types

Article/content-type breakdown by URL count and citation volume. Complements get_source_content_types with a URL-count perspective rather than citation rate.Parameters: projectId (required), days, platform, topicId, unbranded, country, locationId (all optional)

get_source_trend

Citation trend over time for source domains. group='brand' → brand’s own cited sources; 'competitors' → competitor cited sources; 'top-domains' (default) → top cited domains overall. Use for time-series source analysis.Parameters: projectId (required), group (“brand” | “competitors” | “top-domains”, optional), days (optional), unbranded (optional), country (optional), locationId (optional)

Sentiment

get_sentiment

Brand sentiment summary + per-platform distribution — positive/neutral/negative share and an overall sentiment score across AI platforms (ChatGPT, Claude, Perplexity, Gemini). Set unbranded=true to restrict to non-branded prompts.Parameters: projectId (required), days (optional, default 30), platform, topicId, unbranded, country, locationId (all optional)

get_sentiment_history

Brand sentiment trend over time — per-day sentiment score and positive/neutral/negative counts, with an improving/declining/stable trend. Set unbranded=true to restrict to non-branded prompts.Parameters: projectId (required), days (optional, default 90), platform, topicId, unbranded, country, locationId (all optional)

get_sentiment_competitors

Head-to-head sentiment comparison of the brand vs competitors — sentiment score and positive/neutral/negative share per entity, plus visibility and identified gaps. Set unbranded=true to restrict to non-branded prompts.Parameters: projectId (required), days (optional, default 30), platform, limit, unbranded, country, locationId (all optional)

Opportunities

get_opportunities

Actionable opportunities Searchable surfaced for the project — prioritized fix / write / audit suggestions derived from visibility, sentiment, sources, traffic, prompts, site health, and articles. Returns them in the product’s priority order (status, then impact, then newest) plus global stats. Defaults to active opportunities; set includeResolved=true or a status to widen, and source / impact to narrow.Parameters: projectId (required), status, includeResolved, source, impact, limit (default 100, max 500), offset (all optional)

Pagination

Tools that return lists are paginated so you can read complete datasets without silent truncation.

Per-prompt visibility

get_visibility_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:

{
  "pagination": {
    "limit": 100,
    "offset": 0,
    "returnedCount": 100,
    "totalCount": 740,
    "hasMore": true,
    "nextOffset": 100
  }
}

Loop until you’ve read every prompt:

Call get_visibility_by_prompt (defaults: limit 100, offset 0).
While pagination.hasMore is true, call again with offset = pagination.nextOffset.
Stop when pagination.hasMore is false.

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 paginate too: get_opportunities, get_sources, get_source_domain_responses, and get_query_fanout (per-prompt list) use limit + offset, while get_source_domain_urls and the source-URL listings are cursor-based (pass the cursor from the previous response until none is returned). See each tool’s parameters above.

Example prompts

Visibility analysis

What's my brand's AI visibility score for the last 30 days?

How does my brand perform on ChatGPT vs Claude vs Perplexity?

Which topics have the weakest visibility? Show me the top 5.

Site audit

What critical AEO issues does my site have and how do I fix them?

Show me the pages with the lowest AEO scores.

Content

List all my draft articles.

Get the full content of my latest published article for review.

Use cases

Automated issue fixing

Pair the MCP with a coding assistant to retrieve AEO/SEO issues and apply fixes in your codebase:

Get all critical issues for my project and propose fixes in this repo

The assistant fetches issues from Searchable (missing meta descriptions, alt text, heading structure, etc.), locates the relevant files, and proposes or applies fixes.

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

Confirm the server URL is exactly https://mcp.searchable.com/mcp (the server validates the Origin header — only Claude.ai, Claude.com, and native clients are allowed).
Check your API key starts with sea_ and is enabled for MCP in Searchable settings.
Restart your MCP client after config changes.

Authorize page shows 'API key is invalid or expired'

Regenerate the key in Searchable Settings → Integrations and try again.
Make sure the key hasn’t been revoked.
If the backend is briefly unreachable, the server falls back to accepting the key; it will then fail at first tool call instead — retry after a minute.

No projects returned

Confirm you have projects in your Searchable account.
Check that the API key belongs to the correct workspace.

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 design

Every tool is annotated readOnlyHint: true. The server can list and read data; it cannot create, modify, or delete anything in your Searchable account.

API key handling

Your API key is entered once on the Searchable authorize page, never in your client’s config.
It is stored encrypted in the OAuth grant on the server.
It is never sent back to the client. The client only receives an OAuth access token.

Origin validation

The server validates browser Origin headers against an allowlist (claude.ai, claude.com, plus dev hosts). Native clients that don’t send Origin (Claude Desktop, Cursor, curl) are allowed through.

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

Property	Value
Endpoint	`https://mcp.searchable.com/mcp`
Transport	Streamable HTTP
Protocol	MCP 1.0
Authentication	OAuth 2.1 with Dynamic Client Registration

Rate limits

Tool calls proxy to the Searchable backend, which applies platform-level throttling and abuse protection. Clients should handle 429 Too Many Requests responses by honouring the Retry-After header and backing off before retrying. Normal interactive usage from Claude, Cursor, or similar clients is not expected to hit a limit.

​What is MCP?

​How authentication works

​Setup

​Step 1: Get your API key

​Step 2: Add the server to your client

​Step 3: Verify the connection

​Available tools

​Projects & visibility

list_projects

get_visibility_summary

get_visibility_details

get_visibility_history

get_visibility_by_topic

get_visibility_by_location

get_visibility_by_prompt

get_query_fanout

get_prompt_query_fanout

get_prompt_topics

​Site audits

get_website_issues

get_page_audits

get_monitored_pages

get_issue_details

​Content & articles

list_articles

get_article

​GA4 / Traffic

get_ga4_ai_referrals

get_ga4_traffic_trend

get_ga4_top_pages

get_ga4_traffic_sources

​Sources

get_sources

get_source_domain

get_source_domain_urls

get_source_domain_responses

get_source_urls

get_source_page

get_source_page_content

get_source_content_types

get_source_types

get_source_article_types

get_source_trend

​Sentiment

get_sentiment

get_sentiment_history

get_sentiment_competitors

​Opportunities

get_opportunities

​Pagination

​Per-prompt visibility

​Other list tools

​Example prompts

​Visibility analysis

​Site audit

​Content

​Use cases

​Automated issue fixing

​For developers

​For AEO/SEO teams

​For content teams

​Troubleshooting

​Security

​Read-only by design

​API key handling

​Origin validation

​Best practices

​API reference

​Server details

​Rate limits

​Support

All integrations

Contact support

What is MCP?

How authentication works

Setup

Step 1: Get your API key

Step 2: Add the server to your client

Step 3: Verify the connection

Available tools

Projects & visibility

Site audits

Content & articles

GA4 / Traffic

Sources

Sentiment

Opportunities

Pagination

Per-prompt visibility

Other list tools

Example prompts

Visibility analysis

Site audit

Content

Use cases

Automated issue fixing

For developers

For AEO/SEO teams

For content teams

Troubleshooting

Security

Read-only by design

API key handling

Origin validation

Best practices

API reference

Server details

Rate limits

Support