Connect an AI app or your own code

Updated

All docsSetup
On this page

You can ask your AI app about your BotSay results, and read them from your own code. An AI app that supports MCP, such as Claude, ChatGPT or Cursor, connects through the MCP server. Your own code, such as a dashboard or a script, uses an API key. Both are read-only: they can read the workspace and change nothing in it.

Both live in Setup, MCP server and API, which admins can open. The page has two tabs, MCP server and API.

What can an AI app or a key read? #

The same results you see in the app:

  • What the workspace tracks: your brand, rivals, engines, countries and the next reading.
  • This week's figures, you and your rivals ranked, and the trend week by week (up to 26 readings).
  • The questions BotSay asks, and what each engine answered to a question.
  • The sites and pages the engines cited, and the cited pages that name a rival but not you, with when each was first seen and last seen and in how many weeks.
  • Where an engine left you out: each question and engine in the newest week that never named you, and who it named instead.
  • Your readings so far, each engine's status and when setup changed.
  • The items in Work, and how the numbers are made.

So you can ask your AI app, for example, "How did Tessera's Mention rate move this month, and which pages should we write next?"

How do I turn on the MCP server? #

In Setup, MCP server and API, open the MCP server tab and set the switch to On. The page says "Saved." Off blocks every connection, so you can pause them all at once.

With the switch on, the page shows the Server URL with a Copy button, and steps under Add to for Claude, ChatGPT, Cursor and Other.

How do I connect Claude, ChatGPT or Cursor? #

Copy the Server URL first, then follow the steps for your app:

  • Claude. Open Settings, then Connectors. Choose Add custom connector and paste the server URL. On a Claude Team or Enterprise plan, an owner adds it first.
  • ChatGPT. In ChatGPT settings, add a custom connector. Paste the server URL, and choose OAuth if asked.
  • Cursor. Open Cursor settings and find MCP. Add a server and paste the server URL.
  • Other apps. Add a remote MCP server in your app, use the server URL and sign in with OAuth.

Your app then opens BotSay at Connect your AI app, which says "Sign in to BotSay to connect your AI app." Choose Sign in, check the page and press Allow. New to BotSay? Start a workspace sets one up as you connect.

What does the approval page ask? #

The page asks, for example, Connect Claude to BotSay? and shows the address the app sends you back to. It names the workspace the app will read and says it can change nothing. Approve only if you started the connection in your own AI app just now.

To approve, you need to have signed in within the last 10 minutes, with an emailed code or a passkey. If it has been longer, BotSay asks you to sign in again first. If the page shows the wrong workspace, choose Cancel, switch workspace in BotSay, then start again in your AI app.

How long does a connection last? #

A new connection lasts 24 hours. To keep it for 90 days, press Keep connected within that first day. You find it on Your account, under MCP connections, where each of your connections has a row with App, Workspace, Approved and Last signed in.

To end one of yours, choose Disconnect on its row. Your other AI apps stay connected.

How does an admin see every connection? #

The Connections list on the MCP server tab shows every connection in the workspace, with App, Connected by, Connected, Last used and Expires. To end one, open its row menu and choose Disconnect…. The person can connect again whenever they like. Ended connections are folded away; choose Show 2 ended, or whatever the count is, to see them.

How do I make an API key? #

Open the API tab and set the API keys switch to On. The tab shows the Base URL with a Copy button. Then:

  1. Choose Create key.
  2. Give the key a Name you will recognise, such as "Lovable dashboard".
  3. Under Expires in, choose 30 days or 90 days. 90 is the default.
  4. Choose Create key.

The next screen is headed Copy your key and says "Copy it now. You won't see it again." Copy it, keep it on your server rather than in browser code, then choose Done.

Your code sends the key with each request to the Base URL. Keys start with bsk_. For example, GET /api/v1/gaps lists where an engine left you out.

How do I renew or revoke a key? #

The keys table shows each key's Name, the start of the Key, Created by, Created, Expires and Last used. From a key's row menu:

  • Renew… keeps the same key and counts a new expiry from today, so your code keeps working.
  • Revoke… ends the key at once. Anything using it stops working, so replace it in your code first.

A workspace can have up to 10 active keys and make up to 5 new ones a day. Ended keys leave the table 30 days after they end.

How many requests can an app or a key make? #

Each connection and each key can make 30 calls a minute and 1,000 a day, and a key up to 10,000 a month. The whole workspace can make 60 calls a minute and 3,000 a day. That is plenty for asking questions in an AI app or refreshing a dashboard. Past a limit, the answer says to wait a moment and try again.

Tessera, Novaly, Pinefield, Kestrel Pay and Orbita are invented brands, used here as examples.