MCP Server - Otterly Public API

The Model Context Protocol (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 (protocol version 2024-11-05). Authenticate with the same Bearer token used for the Public API.

Authentication

Pass your OtterlyAI API key as a Bearer token in the Authorization header. Permissions and workspace scoping behave identically to the rest of the Public API — see Authentication.

Authorization: Bearer oai_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

OAuth (Coming Soon)

OAuth authentication is coming soon. This will allow you to authenticate users via standard OAuth 2.0 flows instead of static API keys. Stay tuned for updates.

Quick sanity check

Before wiring up a client, confirm the server responds:

curl https://data.otterly.ai/mcp \
  -H "Authorization: Bearer $OTTERLY_API_KEY" \
  -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 get back the server’s capabilities and serverInfo.name = "otterly-mcp".

Claude Code

claude mcp add --transport http otterly https://data.otterly.ai/mcp \
  --header "Authorization: Bearer $OTTERLY_API_KEY"

Verify with claude mcp list — you should see otterly: ... - ✓ Connected. Tools are then available as mcp__otterly__<tool_name>.

Claude Desktop

Claude Desktop currently launches stdio servers, so use the mcp-remote bridge. Add the following to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "otterly": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://data.otterly.ai/mcp",
        "--header",
        "Authorization: Bearer oai_live_..."
      ]
    }
  }
}

Restart Claude Desktop and the OtterlyAI tools will appear in the tool picker.

Cursor

In Cursor → Settings → MCP, add a new server using the same mcp-remote bridge:

{
  "mcpServers": {
    "otterly": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://data.otterly.ai/mcp",
        "--header",
        "Authorization: Bearer oai_live_..."
      ]
    }
  }
}

Available tools

Every tool maps 1:1 to an endpoint in the Public API OpenAPI spec. 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.

Write tools (API keys with `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` (impersonate a known crawler), `sendOtterlyHeader` (send identity header).

These tools are only registered when the API key was issued with write permission; with a read-only key 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

list_workspaces → pick a workspaceId (optional).
list_brand_reports → pick a reportId.
list_brand_report_prompts or list_brand_report_citations with reportId, a date range, and a country code (e.g. us, gb, de).
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) are only available to API keys explicitly granted the write permission.
Rate limits, error codes, and workspace scoping match the Public API. A 401 or 403 from a tool call means the API key is missing, invalid, or lacks permission for the requested workspace.
The OpenAPI spec at https://data.otterly.ai/v1/openapi.json is the source of truth for the underlying data shapes returned by each tool.

Hitting a bug or missing a tool you’d like to see? Email support@otterly.ai.

Documentation Index

​Endpoint

​Authentication

​OAuth (Coming Soon)

​Quick sanity check

​Claude Code

​Claude Desktop

​Cursor

​Available tools

​Workspaces & engines

​Brand reports

​GEO audits

​Write tools (API keys with write permission only)

​Common arguments

​Typical conversation flow

​Things to know

Endpoint

Authentication

OAuth (Coming Soon)

Quick sanity check

Claude Code

Claude Desktop

Cursor

Available tools

Workspaces & engines

Brand reports

GEO audits

Write tools (API keys with `write` permission only)

Common arguments

Typical conversation flow

Things to know