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

The oai_live_ API keys documented under Authentication are for the REST Public API only. The MCP server does not accept them — it is OAuth-only.

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:

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:

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

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

{
  "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):

{
  "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. 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 (`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).

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

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

​Endpoint

​Authentication

​Quick sanity check

​Claude.ai

​Claude Code

​Claude Desktop

​Cursor

​Available tools

​Workspaces & engines

​Brand reports

​GEO audits

​Write tools (write permission only)

​Common arguments

​Typical conversation flow

​Things to know

Endpoint

Authentication

Quick sanity check

Claude.ai

Claude Code

Claude Desktop

Cursor

Available tools

Workspaces & engines

Brand reports

GEO audits

Write tools (`write` permission only)

Common arguments

Typical conversation flow

Things to know