OtterlyAI MCP Server

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

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.ai holds the resulting token itself, so it never shares credentials with another client on your machine.

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 Code holds the resulting token itself, so it never shares credentials with another client on your machine.

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.

If you also run Cursor, a second Claude Desktop profile, or any other mcp-remote client on this machine, the snippet above is not enough — see Running more than one client.

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"]
    }
  }
}

If you also run Claude Desktop or any other mcp-remote client on this machine, the snippet above is not enough — see Running more than one client.

Running more than one client on one machine

The mcp-remote bridge stores every credential in ~/.mcp-auth, keyed by server URL, regardless of which client started it. Two clients pointed at the same URL therefore share a single login: whichever one authorizes last evicts the other, which then opens its own browser tab to authorize and evicts the first. The symptom is an authorization tab that keeps reappearing and a client that reports no connection to OtterlyAI.

Separate application folders do not separate these credentials — two Claude Desktop profiles hit this too. Give each client its own store and its own callback port.

Claude Desktop:

{
  "mcpServers": {
    "otterly": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://data.otterly.ai/mcp", "9696"],
      "env": { "MCP_REMOTE_CONFIG_DIR": "/Users/you/.mcp-auth-claude" }
    }
  }
}

Cursor:

{
  "mcpServers": {
    "otterly": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://data.otterly.ai/mcp", "9697"],
      "env": { "MCP_REMOTE_CONFIG_DIR": "/Users/you/.mcp-auth-cursor" }
    }
  }
}

Use an absolute path for MCP_REMOTE_CONFIG_DIR; ~ is not expanded. Then quit every client, delete the shared ~/.mcp-auth, and authorize one client at a time.

This is also how you connect two different OtterlyAI accounts on one machine — with one shared store both clients end up on whichever account authorized last.

Available tools

Every tool has a counterpart in the Public API and returns the same data shapes. Each tool also advertises an outputSchema (JSON Schema) in tools/list and returns its result as structuredContent conforming to that schema, with the same JSON mirrored in the text block — so clients can type and validate responses at the protocol level. Required arguments are listed per tool; optional arguments below the tables.

Account

Tool	Required arguments	Description
get_account_info	—	Your team’s subscription plan and end date, plus current-period usage and limits for prompts, GEO audits, Public API requests, and MCP tool calls. Free: it never counts against the MCP limit and works even once the limit is reached.

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, with their color and prompt count.
list_workspace_prompts	workspaceId	List the prompts monitored in a workspace. id is the identifier accepted by the prompt write tools.
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.
get_brand_report_citation_history	reportId, url, startDate, endDate, country	Get Citation history for a cited URL — total citations, the change vs the previous period (percentageChange), and a daily breakdown by engine.
list_brand_report_recommendations	reportId, country	List AI-generated recommendations for improving brand visibility, optionally filtered by engine.
list_brand_report_annotations	reportId	List the annotations (dated notes and recommendation markers) on a brand report’s charts, most recently created first. Optional startDate + endDate (both or neither) narrow it to annotations dated in that range, inclusive, ordered by annotation date, latest first. Annotations may not show in the dashboard until annotations are enabled there.
research_competitors	brand, brandDomain	Suggest competitors for a brand from one web-backed AI lookup. Optional: maxResults (default 10, max 20). Returns them in the exact shape create_brand_report and update_brand_report accept for competitors, with likely name variations and extra domains, subdomains included. The input brand is never returned. Nothing is saved: review the list, then pass it on. Counts as one normal call.

Agent analytics

AI crawler and agent traffic hitting the brand report’s own domains — the inverse of citations, which are what the engines said about your brand. Same data as the Agent Analytics tab in the app.

Tool	Required arguments	Description
get_brand_report_agent_stats	reportId	Overview of agent traffic — total agent visits, distinct pages visited, the busiest engine, per-engine totals, and a per-(day, engine, bot) visit series (trend).
list_brand_report_agent_pages	reportId	Per-URL breakdown, busiest page first, with a per-engine split. Supports search on the page URL.
list_brand_report_agents	reportId	Per-agent breakdown — agent name, its engine, its category (On-Demand AI Fetcher, Search Index, AI Training / Data Scraper, or Other), and visit count. Supports search.

Unlike the other brand-report tools, startDate and endDate are optional here and default to the last 14 days (UTC) — the window the app shows by default. There is no country argument: crawler traffic is attributed to a URL and a user-agent, and neither carries a country.

get_brand_report_agent_stats speaks one engine vocabulary throughout — chatgpt, claude, copilot, perplexity, google (Gemini included), other. That holds for both the summary (topEngine, per-engine totals) and the trend series, whose rows are { dayId, engine, bot, visitCount }. bot is the raw crawler name (GPTBot, Google-Extended), so one engine can appear across several bots on a day — e.g. google for both GoogleOther and Google-Extended.

Every response carries an availability field. Check it before reading the numbers:

availability	Meaning
not_connected	No logs connector is set up for this report. Metrics are null, not zero — nothing is being measured. Connect a log source in the app first.
connected_no_data	A connector is active but matched no visits in this window. The zeros are real.
connected_with_data	Populated payload.

Treating not_connected as zero is the mistake worth avoiding: it reads as “no AI crawler visited this site” when the truth is that nobody is measuring.

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.
create_prompts	workspaceId, country, prompts	Create one or more prompts in a workspace and start monitoring them, exactly like creation in the UI. Optional: tagIds, brandReportIds. Up to 5 prompts are created synchronously and returned with their IDs; larger batches are processed asynchronously and return a processing summary instead — use list_workspace_prompts afterward to see what was created. The whole batch is validated against the workspace’s remaining prompt allocation up front. A prompt’s text and country are immutable after creation.
delete_prompt	workspaceId, promptId	Delete a prompt. It’s removed from any brand report it’s part of, and affected brand reports are recalculated without it (asynchronously).
update_prompt_tags	workspaceId, promptId, tagIds	Replace the tags assigned to a prompt with the given set (pass [] to remove all tags). Only tags can be changed — attempting to change a prompt’s text or country isn’t supported; create a new prompt and delete the old one instead.
create_brand_report	workspaceId, promptIds, brandDomain	Create a brand report from prompts that already exist in the workspace (at least one). Set brand, or brandRegex with reportTitle. Optional: brand, reportTitle, brandVariations, brandRegex, brandDomainWildcard, brandDomainVariations, competitors. brandRegex replaces brand + brandVariations for detection (JavaScript-compatible, case-sensitive, max 1000 characters); send one or the other, not both. With brandRegex you can leave out brand, but then reportTitle is required and is used as the brand’s label. brandDomainWildcard includes all subdomains of the main domain only. Each competitor takes the same brand fields, and its brand is always required as its label. Up to 100 competitors, and up to 100 name and domain variations each. Countries come from the prompts. Returns the full report, in the same shape as get_brand_report.
update_brand_report	reportId	Update a brand report. Takes any of the create_brand_report fields except workspaceId, and only the fields you send change. Array fields (promptIds, competitors, brandVariations, brandDomainVariations) replace the stored list whole. Send brandRegex: null to remove a regex, together with brand. You can send back a report from get_brand_report unchanged; read-only fields are ignored. Lists are capped at 100 competitors and 100 variations each. Changing a detection field (brand, variations, regex, domains, competitors) recalculates the report’s existing history asynchronously, not only future runs. Returns the full updated report.
add_prompts_to_brand_report	reportId, promptIds	Add one or more existing prompts to a brand report, up to 1000 per call. Prompts already on the report are ignored rather than duplicated, and the response lists which ids were added and which were already assigned. The report is recalculated asynchronously to include the new prompts. There’s no workspaceId argument — the workspace is taken from the report.
remove_prompts_from_brand_report	reportId, promptIds	Remove one or more prompts from a brand report, up to 1000 per call. The prompts themselves aren’t deleted; they stay in the workspace and only their membership of the report goes away, and the report is recalculated without them (asynchronously). Removing a prompt discards the citation data already collected for it in that report: if you add it back later, only the most recent 7 days of its citation history are reprocessed and anything older isn’t restored, so removing and re-adding isn’t reversible.
create_tag	workspaceId, name, color	Create a new tag in a workspace. Tags can be assigned to prompts with update_prompt_tags.
delete_tag	workspaceId, tagId	Delete a tag. It’s unassigned from all prompts asynchronously; brand reports filtered by it update accordingly.
create_brand_report_annotation	reportId, date, text	Add a note to a brand report, dated date (YYYY-MM-DD), with text of 1 to 1000 characters after trimming. Optional type accepts only note: only notes can be created; recommendation markers come from completing a recommendation in the app. Annotations may not show in the dashboard until annotations are enabled there.
update_brand_report_annotation	reportId, annotationId	Change a note’s text (1 to 1000 characters after trimming) and/or date (at least one). You can send back an item from list_brand_report_annotations unchanged; read-only fields are ignored. Recommendation annotations can’t be edited.
delete_brand_report_annotation	reportId, annotationId	Delete a note or a recommendation annotation, which removes it from the chart. Deleting it again returns “Annotation not found”.

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, claude, google, perplexity, copilot, google_ai_mode, gemini. Call list_engines to see which engines are available in which countries.
• Engines on the agent-analytics tools: single-value — chatgpt, claude, copilot, perplexity, google, other. google covers the whole Google family (Gemini included), unlike the app which lists Gemini separately. Pass engine=other to match every AI crawler outside the named engines (Amazon, Meta, xAI, ByteDance, Common Crawl, and so on). other also appears in the response breakdown, so it means the same thing in and out. The agent name in list_brand_report_agents is always exact, so other never hides which crawler it was.
• Pagination: every list tool pages, with limit defaulting to 25 (max 100). The paging object has the same shape as the Public API endpoint behind the tool, but only the shape: several Public API endpoints return the whole list in one response where MCP pages it. Cursor lists (list_workspaces, list_workspace_tags, list_workspace_prompts, list_brand_reports, list_brand_report_recommendations, list_brand_report_annotations, list_crawlability_checks, list_content_checks, list_query_fan_outs) accept cursor and limit and return paging: { nextCursor, hasMore }; pass nextCursor back as cursor for the next page. list_brand_report_prompt_ai_responses is cursor-paged too, with cursor only. Offset lists (list_brand_report_citations, list_brand_report_prompts, list_brand_report_citation_prompts, list_brand_report_agent_pages, list_brand_report_agents) accept limit and offset (a multiple of limit) and return paging: { limit, offset, hasMore }, the agent-analytics lists adding totalCount; add limit to offset for the next page. Either way, stop when hasMore is false. The former page and pageSize arguments are no longer accepted: a list tool rejects them, like any unknown argument, with a validation error rather than ignoring them.
• Extra filters on list_brand_report_prompts and list_brand_report_citations: engines, tagId, search, sortBy, sortOrder.
• search on the agent-analytics list tools is a case-insensitive substring match, applied server-side across the whole result set. It is matched literally — % and _ are not wildcards.

Typical conversation flow

1. get_account_info → your plan and how many MCP tool calls remain this period. Free, so it is safe to call first.
2. list_workspaces → pick a workspaceId (optional).
3. list_brand_reports → pick a reportId.
4. list_brand_report_prompts or list_brand_report_citations with reportId, a date range, and a country code (e.g. us, uk, de).
5. Drill into get_brand_report_stats, get_brand_report_citation_stats, list_brand_report_recommendations, or the GEO audit tools as needed.
6. To ask about AI crawlers on your own site rather than what the engines said, start at get_brand_report_agent_stats with just the reportId, then drill into list_brand_report_agent_pages or list_brand_report_agents.

Troubleshooting

The authorization tab keeps reopening, or the client reports no connection to OtterlyAI. Two clients are sharing one mcp-remote credential store — see Running more than one client. Reconnecting repairs one client and breaks the other, so the loop survives any number of reconnects.

“state already in use”. A connection link is single-use and retrying the same one lands here. Wait about ten minutes, then start the connection again from the client rather than reloading the page.

The wrong OtterlyAI account got connected. Approval is granted by whichever account the browser is already signed into; the client has no say in it. To connect a specific account, sign that account in first — a separate browser profile per account is the reliable way — and then authorize.

401 from a tool call. The OAuth token is missing or expired; reconnect to refresh it. If reconnecting works and then fails again within a day, it is the shared-credential case above rather than an expiry.

403 from a tool call. Your account lacks permission for the requested workspace.

Things to know

• Most tools are read-only. The tools in the Write tools section above are only available to accounts with the write permission.
• Workspace scoping matches your OtterlyAI account. See Troubleshooting for 401 and 403 responses.
• Every tool call except get_account_info counts against your plan’s MCP tool-call limit. Once it is exhausted, calls fail with Request limit exceeded for this billing period until the next period.
• Each tool’s outputSchema is the contract for its result. The shapes are the Public API response shapes, paging included, so the OpenAPI spec doubles as a field reference.

Hitting a bug or missing a tool you’d like to see? Email [e-mail].