Connect Whaily to your AI client

1. Generate an API key

1. Sign in and open Settings, API and MCP. Owners generate keys; admins and members cannot.
2. Give the key a name, pick its scopes and an expiry. The defaults suit most setups.
3. Generate it and copy the whaily_live_ value straight away. It is shown once. Lose it and you revoke and generate another.

Scopes

• read: List and fetch prompts, sources, competitors, domains, todos and recommendations, and ask analyze questions.
• manage: Every change an agent can make: create and update prompts, todos, comments and tags, turn a recommendation into a todo, and change workspace settings, competitors, products, partners and share links.
• expensive: Trigger work that costs model time, such as running a prompt on demand.
• write: Used by the REST API, not by MCP. A key meant for both carries both.

2. Paste it into your AI client

Claude Desktop

Open claude_desktop_config.json (on macOS it is under Library, Application Support, Claude) and add the whaily entry. The exact URL for your account is printed on your own settings panel; the example uses our production host.

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

Restart Claude Desktop. Whaily should appear in the tool picker at the bottom of the chat box.

Cursor

In Cursor, open Settings, Features, MCP, choose Add new MCP server, and use the same URL and bearer token. Cursor restarts itself after saving.

A custom agent

Both the Anthropic and OpenAI SDKs take MCP servers as tool sources. Pass the URL and the bearer token at session init and the SDK handles the handshake.

3. Ask the questions you actually want answered

• Show me which brands are gaining visibility in my space.
• Where is a named competitor overtaking us this week?
• Find the prompts where we are losing citations and add the top three as todos.
• Walk me through the brand audit failures and suggest the order to fix them.
• Generate a weekly status report.

What the server can do

The tool set grows, so this page does not print a list that would go stale between releases. Ask the server instead: every connection exposes describe_capabilities, which answers with the tools your key can actually reach, grouped by family, for the scopes you granted and the plan your workspace is on. Most clients also surface a handful of ready-made prompts, so a weekly status write-up or a competitor check is one pick rather than a paragraph.

Plans and limits

MCP is on the Starter, Pro, Agency and Enterprise plans. On Free a tool call answers with a structured upgrade message that your client shows as a readable error rather than a failure. Each workspace has a monthly call allowance, shown with the rest of your usage on the settings panel. Going over it answers 429 with a Retry-After that counts to the start of next month, so an agent that honours it stops until the allowance resets. See pricing for what each plan includes.

Audit log

Every tool call is recorded in your workspace and visible from the same settings panel: which tool ran, when, how long it took and how it ended. It is useful for a retro and for spotting an agent doing something you did not expect. Revoking a key takes effect immediately.

Security

• Keys are hashed with bcrypt at cost 12. The plaintext is never stored.
• Every call is scoped to one workspace. Reaching another one is impossible by construction: every query takes the organisation id as its first argument.
• Nothing changes without the manage scope. Give an agent that should only answer questions a key with read alone, and it cannot create, edit or delete anything.
• Keys can be given an expiry and can be revoked at any time.
• The expensive and manage scopes are opt in. Without them an agent cannot spend model time or change your settings.

Troubleshooting

The client does not see the Whaily tools

• Restart the client after editing its config file.
• Check the path is right and the JSON parses cleanly.
• Open the client developer tools and look for a connection error.

Missing or invalid API key

• The key was probably revoked, expired, or the workspace changed plan.
• Check the header reads exactly Bearer, a space, then the whole token.

A rate limit

The 429 carries a Retry-After in seconds: a few seconds for the per-minute limit, or the time to the start of next month for the monthly allowance. Most agents back off on their own. If you hit limits regularly, move up a plan or write to us about Enterprise.