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

# MCP Server

> Use OtterlyAI with Model Context Protocol (MCP)–compatible clients

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) lets AI
assistants like Claude Code, Claude Desktop, Cursor, and other compatible
clients call external tools in a structured way. The OtterlyAI MCP server exposes
your brand reports, prompts, citations, recommendations, and audit checks as
MCP tools so your assistant can answer questions about your AI search
visibility directly.

## Endpoint

```
https://data.otterly.ai/mcp
```

The server speaks the MCP **streamable HTTP** transport. Authentication is
handled entirely through **OAuth 2.0** — see below.

## Authentication

The OtterlyAI MCP server authenticates with **OAuth 2.0**. You do **not** pass
an API key. When you add the server to a compatible client, the client walks you
through a standard browser sign-in to OtterlyAI and obtains an access token on
your behalf. Permissions and workspace scoping match your OtterlyAI account.

<Note>
  The `oai_live_` API keys documented under
  [Authentication](/authentication) are for the **REST Public API only**. The
  MCP server does not accept them — it is OAuth-only.
</Note>

The flow is fully automatic for MCP clients: there is nothing to configure by
hand. Under the hood the server implements OAuth 2.0 with dynamic client
registration and PKCE, and advertises discovery metadata at:

```
https://data.otterly.ai/.well-known/oauth-protected-resource/mcp
https://data.otterly.ai/.well-known/oauth-authorization-server
```

When a request arrives without a valid token, the server responds `401` with a
`WWW-Authenticate` header pointing at the protected-resource metadata, which is
the client's cue to start the OAuth flow.

## Quick sanity check

You don't need a token to confirm the server is up and correctly OAuth-gated.
An unauthenticated request returns `401` with a `WWW-Authenticate` header:

```bash theme={null}
curl -i https://data.otterly.ai/mcp -X POST \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'
```

You should see `HTTP/1.1 401` and a header of the form
`WWW-Authenticate: Bearer error="invalid_token", resource_metadata="https://data.otterly.ai/.well-known/oauth-protected-resource/mcp"`.

Fetching that metadata document returns the resource and its authorization
server:

```bash theme={null}
curl https://data.otterly.ai/.well-known/oauth-protected-resource/mcp
```

## Claude.ai

In **Customize → Connectors**, choose **Add connector / "+" sign**, search for OtterlyAI, and click **Connect**:

```
https://data.otterly.ai/mcp
```

A browser window opens to sign in to OtterlyAI and authorize access. Once
approved, the OtterlyAI tools are available in your chats.

## Claude Code

```bash theme={null}
claude mcp add --transport http otterly https://data.otterly.ai/mcp
```

The first time a tool is used, Claude Code opens a browser to complete the
OAuth sign-in. Verify with `claude mcp list` — you should see
`otterly: ... - ✓ Connected`. Tools are then available as
`mcp__otterly__<tool_name>`.

## Claude Desktop

Add a remote connector pointing at the endpoint; Claude Desktop runs the OAuth
flow in your browser on first connect. If your version launches stdio servers
only, use the [`mcp-remote`](https://github.com/geelen/mcp-remote) bridge — it
performs the OAuth handshake for you, so **no static `Authorization` header is
needed**. Add the following to
`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

```json theme={null}
{
  "mcpServers": {
    "otterly": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://data.otterly.ai/mcp"]
    }
  }
}
```

Restart Claude Desktop; a browser opens to authorize, and the OtterlyAI tools
appear in the tool picker.

## Cursor

In **Cursor → Settings → MCP**, add a new server using the same `mcp-remote`
bridge (the OAuth flow opens in your browser on first use):

```json theme={null}
{
  "mcpServers": {
    "otterly": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://data.otterly.ai/mcp"]
    }
  }
}
```

## Available tools

Every tool maps 1:1 to an endpoint in the
[Public API OpenAPI spec](https://data.otterly.ai/v1/openapi.json). Required
arguments match the API; optional arguments are listed below the table.

### Workspaces & engines

| Tool                  | Required arguments | Description                                                                                     |
| --------------------- | ------------------ | ----------------------------------------------------------------------------------------------- |
| `list_workspaces`     | —                  | List all workspaces accessible by the API key.                                                  |
| `list_workspace_tags` | `workspaceId`      | List tags defined for a workspace.                                                              |
| `list_engines`        | —                  | List available AI engines and their supported countries. Optional filters: `country`, `engine`. |

### Brand reports

| Tool                                    | Required arguments                                        | Description                                                                                               |
| --------------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `list_brand_reports`                    | —                                                         | List brand reports accessible by the API key. Optional `workspaceId` scopes to a single workspace.        |
| `get_brand_report`                      | `reportId`                                                | Get a brand report's details, including competitors, countries, and tags.                                 |
| `get_brand_report_stats`                | `reportId`, `startDate`, `endDate`, `country`             | Aggregated stats — brand coverage history, brand ranks with sentiment, top domains, and engine breakdown. |
| `list_brand_report_prompts`             | `reportId`, `startDate`, `endDate`, `country`             | List prompts with brand and domain mention stats for a date range and country.                            |
| `get_brand_report_prompt`               | `reportId`, `promptId`, `startDate`, `endDate`, `country` | Detailed metrics for a single prompt — brand coverage history, ranks, sentiment, domain categories, tags. |
| `list_brand_report_prompt_ai_responses` | `reportId`, `promptId`, `startDate`, `endDate`, `country` | List AI response runs collected for a prompt — raw model content, brand mentions, and citations.          |
| `list_brand_report_citations`           | `reportId`, `startDate`, `endDate`, `country`             | List cited URLs for a brand report, filterable by AI engine, tag, and search query.                       |
| `get_brand_report_citation_stats`       | `reportId`, `startDate`, `endDate`, `country`             | Citation stats — top cited domains, share-of-citations, and most-cited URLs over a date window.           |
| `list_brand_report_citation_prompts`    | `reportId`, `url`, `startDate`, `endDate`, `country`      | List prompts that cited a specific URL within a brand report over a date window.                          |
| `list_brand_report_recommendations`     | `reportId`, `country`                                     | List AI-generated recommendations for improving brand visibility, optionally filtered by `engine`.        |

### GEO audits

| Tool                       | Required arguments       | Description                                                                                          |
| -------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------- |
| `list_crawlability_checks` | `workspaceId`            | List crawlability audit checks (robots.txt analysis, bot access) for a workspace.                    |
| `get_crawlability_check`   | `checkId`, `workspaceId` | Get a crawlability check's full results.                                                             |
| `list_content_checks`      | `workspaceId`            | List content / AI-readiness checks for a workspace.                                                  |
| `get_content_check`        | `checkId`, `workspaceId` | Get a content check's full results — AI readiness, PageSpeed, structural and dynamic-content scores. |

### Query fan-outs

| Tool                  | Required arguments        | Description                                                                                                                           |
| --------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `list_query_fan_outs` | `workspaceId`             | List query fan-out runs for a workspace — each run expands an original query into the related queries AI search engines may generate. |
| `get_query_fan_out`   | `fanOutId`, `workspaceId` | Get a query fan-out run and its expanded queries (query, type, user intent, reasoning) split per AI engine.                           |

### Write tools (`write` permission only)

| Tool                        | Required arguments     | Description                                                                                                                                                                             |
| --------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create_crawlability_check` | `workspaceId`, `url`   | Create a new crawlability audit for a URL.                                                                                                                                              |
| `create_content_check`      | `workspaceId`, `url`   | Create a new content / AI-readiness check. Optional: `crawlerIdentity` (crawler user-agent to test the page against), `sendOtterlyHeader` (send identity header).                       |
| `create_query_fan_out`      | `workspaceId`, `query` | Generate a new query fan-out — expands an original query into related queries across AI engines. Runs asynchronously; poll `get_query_fan_out` until status is `completed` or `failed`. |

These tools are only registered when your account has `write` permission; with
read-only access they are not advertised by the server.

### Common arguments

* **Dates**: `startDate` and `endDate` are inclusive. Accept `YYYY-MM-DD` or a
  full ISO timestamp; only the date portion is used.
* **Country**: `country` is a lowercase ISO 3166-1 alpha-2 code (e.g. `us`,
  `de`). Use `uk` for the United Kingdom.
* **Engines**: `engines` (multi-value) and `engine` (single-value) accept
  `chatgpt`, `google`, `perplexity`, `copilot`, `google_ai_mode`, `gemini`.
  Call `list_engines` to see which engines are available in which countries.
* **Pagination**: list tools accept `page` (default `1`) and `pageSize`
  (default `50`, max `100`).
* **Extra filters on `list_brand_report_prompts` and `list_brand_report_citations`**:
  `engines`, `tagId`, `search`, `sortBy`, `sortOrder`.

## Typical conversation flow

1. `list_workspaces` → pick a `workspaceId` (optional).
2. `list_brand_reports` → pick a `reportId`.
3. `list_brand_report_prompts` or `list_brand_report_citations` with
   `reportId`, a date range, and a country code (e.g. `us`, `gb`, `de`).
4. Drill into `get_brand_report_stats`, `get_brand_report_citation_stats`,
   `list_brand_report_recommendations`, or the GEO audit tools as needed.

## Things to know

* Most tools are **read-only**. Write tools (`create_crawlability_check`,
  `create_content_check`, `create_query_fan_out`) are only available to accounts
  with the `write` permission.
* Workspace scoping matches your OtterlyAI account. A `401` from a tool call
  means the OAuth token is missing or expired (reconnect to refresh it); a `403`
  means your account lacks permission for the requested workspace.
* The OpenAPI spec at
  [`https://data.otterly.ai/v1/openapi.json`](https://data.otterly.ai/v1/openapi.json)
  is the source of truth for the underlying data shapes returned by each tool.

<Tip>
  Hitting a bug or missing a tool you'd like to see? Email
  [support@otterly.ai](mailto:support@otterly.ai).
</Tip>