MCP Integration

Connect Searchable to Claude.ai, Claude Desktop, Cursor, and other MCP-compatible assistants to query your AI visibility, site audits, and content.

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:

1. You add the server URL to your client (https://mcp.searchable.com/mcp).
2. On first use, the client opens a Searchable authorize page in your browser.
3. The page lists the read-only permissions being granted and asks for your Searchable API key.
4. 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

1. Open Settings

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

2. Create API key

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

3. 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

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

Claude Desktop

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.

Cursor

Add to .cursor/mcp.json:

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

Windsurf

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 13 read-only tools. All tools are annotated with readOnlyHint: true — the server cannot create, modify, or delete data.

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)

get_visibility_by_prompt

Per-prompt visibility with optional filters (topic, branded/non-branded, platform).

Parameters: projectId (required), days, topicId, branded, platform (all optional)

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)

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.

Support

All integrations

Browse the integrations directory

Contact support

Email our team