> ## Documentation Index
> Fetch the complete documentation index at: https://docs.searchable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Info>
  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.
</Info>

<Note>
  **Plan requirement:** MCP integration requires a paid Searchable plan (Starter, Professional, or Scale). API keys cannot be created on the Free plan.
</Note>

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

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

## Setup

### Step 1: Get your API key

<Steps>
  <Step title="Open Settings">
    Navigate to **Settings → Workspace → Integrations** in your Searchable dashboard.
  </Step>

  <Step title="Create API key">
    Click **Create API Key** and give it a descriptive name (e.g., "Claude MCP").
  </Step>

  <Step title="Copy the key">
    Copy your API key (starts with `sea_`). Store it securely — you won't be able to see it again.
  </Step>
</Steps>

### Step 2: Add the server to your client

<Tabs>
  <Tab title="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**.
  </Tab>

  <Tab title="Claude Desktop">
    Add to `~/.claude/mcp.json`:

    ```json theme={null}
    {
      "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.
  </Tab>

  <Tab title="Cursor">
    Add to `.cursor/mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "searchable": {
          "url": "https://mcp.searchable.com/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windsurf">
    Add to your Windsurf MCP configuration:

    ```json theme={null}
    {
      "mcpServers": {
        "searchable": {
          "url": "https://mcp.searchable.com/mcp"
        }
      }
    }
    ```
  </Tab>
</Tabs>

### 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

<CardGroup cols={2}>
  <Card title="list_projects" icon="folder">
    List all projects for the authenticated user. Returns names, domains, descriptions, and IDs.
  </Card>

  <Card title="get_visibility_summary" icon="chart-line">
    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)
  </Card>

  <Card title="get_visibility_details" icon="chart-pie">
    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)
  </Card>

  <Card title="get_visibility_history" icon="timeline">
    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)
  </Card>

  <Card title="get_visibility_by_topic" icon="tags">
    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)
  </Card>

  <Card title="get_visibility_by_prompt" icon="message">
    Per-prompt visibility with optional filters (topic, branded/non-branded, platform).

    **Parameters:** `projectId` (required), `days`, `topicId`, `branded`, `platform` (all optional)
  </Card>

  <Card title="get_prompt_topics" icon="list">
    List available topics for a project (useful to discover topic IDs for filtering).

    **Parameters:** `projectId` (required)
  </Card>
</CardGroup>

### Site audits

<CardGroup cols={2}>
  <Card title="get_website_issues" icon="triangle-exclamation">
    Current website issues grouped by severity (critical, high, medium, low).

    **Parameters:** `projectId` (required), `status` ("open" | "resolved" | "all", default "open")
  </Card>

  <Card title="get_page_audits" icon="file-magnifying-glass">
    Technical, content, and AEO scores for each monitored page.

    **Parameters:** `projectId` (required)
  </Card>

  <Card title="get_monitored_pages" icon="files">
    Page URLs, types, issue counts, and tracking status.

    **Parameters:** `projectId` (required)
  </Card>

  <Card title="get_issue_details" icon="magnifying-glass">
    Detailed information about issues of a specific type, with fix recommendations.

    **Parameters:** `projectId` (required), `issueType` ("technical" | "content")
  </Card>
</CardGroup>

### Content & articles

<CardGroup cols={2}>
  <Card title="list_articles" icon="newspaper">
    Article titles, status, topics, keywords, and metadata.

    **Parameters:** `projectId` (required), `status` ("draft" | "published" | "editing" | "all"), `limit` (max 100)
  </Card>

  <Card title="get_article" icon="file-lines">
    Full article content including HTML/markdown, outline, FAQs, schema markup, internal/external links, and SEO metadata.

    **Parameters:** `articleId` (required)
  </Card>
</CardGroup>

## 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="No projects returned">
    * Confirm you have projects in your Searchable account.
    * Check that the API key belongs to the correct workspace.
  </Accordion>

  <Accordion title="Tools not appearing">
    * Restart your MCP client.
    * Verify the server URL and JSON config syntax.
    * Check the client's MCP logs for errors.
  </Accordion>
</AccordionGroup>

## 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

<CardGroup cols={2}>
  <Card title="All integrations" icon="book" href="/integrations/overview">
    Browse the integrations directory
  </Card>

  <Card title="Contact support" icon="headset" href="mailto:support@searchable.com">
    Email our team
  </Card>
</CardGroup>