Setup guide

Connect Whaily to your AI client

Generate an API key, paste a config snippet, ask questions. Three steps. Works with Claude Desktop, Cursor, custom agents built with the Anthropic SDK or OpenAI Agents SDK, and anything else that speaks the Model Context Protocol over HTTP.

1. Generate an API key

Sign in to Whaily and open Settings → API & MCP. Owners only — workspace owners can generate keys; admins and members can't.
Pick a name (e.g. Maya's Claude Desktop), choose the scopes you want, and an expiry. Defaults are fine for most setups.
Click Generate key. Copy the whaily_live_… value now. It is shown exactly once. If you lose it, revoke and generate a new one.

Scopes

read — list and fetch prompts, sources, competitors, todos, recommendations.
write — create or update prompts, todos, comments, tags. Convert recommendations into todos.
expensive — trigger LLM-cost work (run prompts on demand, generate fresh recommendations). Not yet enabled in this release.

2. Paste it into your AI client

Claude Desktop

Open ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or the equivalent path on Windows / Linux. Add the whaily entry:

{
  "mcpServers": {
    "whaily": {
      "url": "https://whaily.com/api/mcp",
      "headers": {
        "Authorization": "Bearer whaily_live_..."
      }
    }
  }
}

Restart Claude Desktop. You should see Whaily appear in the tool picker (the slider icon at the bottom of the chat box).

Cursor

In Cursor, open Settings → Features → MCP, click Add new MCP server, and use the same URL and bearer token as above. Cursor restarts automatically after saving.

Custom agent (Anthropic / OpenAI SDK)

Both SDKs support MCP servers as tool sources. Pass the URL and bearer token at session-init time and the SDK handles the JSON-RPC handshake for you.

3. Ask the questions you actually want answered

Once connected, try these:

“Show me which brands are gaining visibility in my space.”
“Where is HubSpot overtaking us this week?”
“Find the prompts where we're losing citations and add the top three as todos for Maya.”
“Walk me through brand audit failures and suggest the order I should fix them.”
“Generate a weekly status report.”

What you can ask Whaily to do

Predefined prompt templates

Most clients surface these as one-click starting points. Type slash and pick one — the agent runs the right tools and writes back to your workspace.

Name	What it does
`weekly-status`	Summarise this week's movement, top three risks, three suggested actions.
`competitor-watch`	Find prompts where a named competitor overtook you. Suggest specific actions.
`losing-citations`	Find prompts where citations dropped, group by source, propose recovery actions.
`audit-walkthrough`	Walk through brand audit failures, prioritise by impact, queue todos.
`category-radar`	Snapshot of your standing across every tracked engine and competitor.

Read tools (22)

Tool	Returns
`get_visibility_overview`	Headline visibility metric across the last 30 days.
`get_visibility_trend`	Daily visibility timeseries by provider/model.
`get_visibility_by_model`	Per-engine breakdown for the last 30 days.
`list_prompts`	Tracked prompts with filters (status, country, language).
`get_prompt`	A single prompt with last runs, citations, recommended brands.
`list_prompt_runs`	Per-model recent runs of a single prompt.
`list_sources`	Top NCI sources in your category.
`get_source`	Source detail: NCI score, citation history per prompt, model breakdown.
`search_sources`	Find sources by domain pattern.
`list_competitors`	Tracked competitors with current overall visibility.
`get_competitor`	A competitor's detail: per-model and per-prompt visibility.
`get_competitor_trend`	Daily visibility timeseries for a competitor.
`compare_to_competitor`	Head-to-head: prompts where they lead, prompts where you lead.
`find_losing_prompts`	Prompts where your visibility dropped vs the prior window.
`get_brand_audit`	Every presence check (G2, Wikipedia, schema, robots.txt, more).
`get_brand_audit_check`	Drill into a single check by key.
`list_recommendations`	AI-generated recommendations.
`get_recommendation`	A single recommendation.
`list_action_items`	Todos in your workspace.
`get_action_item`	A single todo with comments.
`list_tags`	Prompt tag catalog.
`get_workspace_settings`	Brand domains, industries, tracked models, member count, prompt count.

Write tools (13)

Tool	What it does
`create_prompt`	Track a new prompt. Optional tags, country, language.
`update_prompt`	Edit prompt text, status, country, language.
`pause_prompt / resume_prompt`	Toggle active/inactive without losing history.
`archive_prompt`	Soft delete (requires confirm:true).
`add_prompt_tag / remove_prompt_tag`	Tag operations. Auto-creates new tags.
`create_action_item`	Create a todo with assignee, due date, and source.
`update_action_item`	Change status, assignee, due date. status:"done" stamps completed_at.
`add_action_item_comment`	Append a comment to a todo.
`delete_action_item`	Hard-delete a todo (requires confirm:true).
`dismiss_recommendation`	Mark a recommendation as user_dismissed.
`convert_recommendation_to_action_item`	Create a todo from a recommendation in one call.

Quotas and rate limits

MCP requires a paid plan (Starter, Pro, or Enterprise). The Free plan returns a structured upgrade message that your AI client surfaces as a helpful error. Per-tier limits:

Plan	Read	Write	Expensive	Concurrent jobs	LLM cost ceiling
Starter	10 000 / mo	1 000 / mo	100 / mo	2	$50 / mo
Pro	100 000 / mo	10 000 / mo	1 000 / mo	10	$500 / mo
Enterprise	unlimited	unlimited	unlimited	50	unlimited

Burst limits live on top: Pro gets 60 read tokens (refilling 2/sec), 30 write (1/sec), 10 expensive (1 every 10 sec). Hit a limit and the agent gets a structured 429 with a Retry-After hint.

Audit log

Every tool call is recorded in your workspace, visible from the same settings panel. The owner sees the tool name, when it ran, how long it took, and the outcome. Useful for retros and for spotting an agent doing something unexpected. Revoking a key takes effect immediately.

Security

Keys are bcrypt-hashed at cost 12. The plaintext is never stored or recoverable.
Every tool call is scoped to your organisation. Cross-org access is impossible by construction — every helper takes the org ID as its first argument.
Destructive operations (archive_prompt, delete_action_item) require an explicit confirm: true argument so the agent has to ask you before acting.
Keys can be set to expire (30, 90, 365 days) and revoked at any time.
The expensive scope is opt-in — without it, the agent cannot trigger LLM-cost work.

Troubleshooting

Claude doesn't see the Whaily tools

Make sure you restarted Claude Desktop after editing the config file.
Check your config file path is right and the JSON parses cleanly. Run cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq . on macOS.
Open Claude's developer tools (View → Developer → Toggle Developer Tools) and look for connection errors in the console.

I get “Missing or invalid API key”

The key was likely revoked or the workspace switched plans. Check Settings → API & MCP.
Make sure the Authorization header is exactly Bearer + the full token.

I hit a rate limit

The 429 response includes a Retry-After header with the number of seconds until the next token refills. Most agents back off and retry automatically. If you're hitting limits regularly, upgrade or contact us about Enterprise.

Questions? Email hello@whaily.com or open your settings panel.