When the Sitebulb MCP misbehaves, the cause is almost always one of three things: a connection issue, a permission issue, or a timing issue. It's never the MCP changing your data, because it can't - every tool is read-only. That narrows the field nicely, and most of the symptoms below have a thirty-second fix.
Setting up for the first time? This page is for connections that exist (or used to). If you haven't connected yet, start with Sitebulb MCP: Start Here and the step-by-step connection guides.
The four quick checks
Before anything else, run these. Between them they fix the majority of problems we see:
(Desktop) Is Sitebulb Desktop actually open? A Desktop connection only works while the app is running, signed in, on the latest version, on an active licence, and online. A computer that went to sleep or an app that was quit explains most Desktop symptoms on its own.
Has the crawl finished? The MCP reads finished audits only. Hints, insights, URLs and reports from a crawl that's still running will return an error, not partial data.
Did you name the project as it appears in Sitebulb? "The client site" means nothing to the MCP; "Acme Store" does, if that's what the project is called.
Did you tell it to use the Sitebulb MCP? Starting a prompt with "Using the Sitebulb MCP..." stops the assistant answering from general knowledge or the web instead of your data.
Connection problems
The connector won't add at all
Check the URL character for character. The only two connection addresses are https://mcp.sitebulb.com/cloud and https://mcp.sitebulb.com/desktop - no tenant subdomain, nothing after /cloud or /desktop. If the sign-in was abandoned partway (a closed tab counts), there's no broken state to clean up: just restart the connect flow from the relevant connection guide and follow it to the end.
Stuck on the sign-in or approval screen
Two usual causes. Either the approval never actually completed (a blocked pop-up, a closed tab, or clicking away all leave your AI client waiting for an approval that never arrives), or you signed in with the wrong Sitebulb account - easy to do if you have a work and a personal login. Restart the flow from your AI client, and make sure you sign in with the account that owns the projects you want to see. There's nothing to undo first.
No Sitebulb tools showing in this chat
Connecting is a one-time step, but some clients also want tools switched on per conversation. In both Claude and ChatGPT, open the tools or connectors control in the chat composer (near where you type), find Sitebulb in the list of connected sources, and make sure it's enabled for the current chat. The first time a tool is used in a conversation, the assistant may also ask inline for permission - approve it.
If Sitebulb isn't in that list at all: try a hard refresh and, if needed, run the sign-in again, as both clients occasionally have trouble syncing a recently added connector. On a ChatGPT Business plan, also check the plugin was actually Published to the workspace - it's the step admins most often miss. If it's still missing, the connector likely isn't connected any more; reconnect from the guides.
It worked yesterday, not today
Three causes cover nearly every case of a connection that simply stops:
(Desktop) The app closed, slept, or signed out. Reopen Sitebulb Desktop, sign in, and give it a minute to come back online.
The authorisation expired or was revoked. If every call now fails with an unauthorised-style error, the connection itself needs re-establishing: remove the connector and reconnect from the guide. Retrying the same failing question won't fix it.
You're pointed somewhere else than you think. If you've switched Cloud workspaces, or a different Desktop machine is the one currently online, your assistant may be looking in the wrong place rather than failing outright. Confirm which workspace or machine the connection is using.
My Desktop machine doesn't appear as a target
During sign-in you're asked to choose the Desktop machine to read from, and only eligible machines appear. Eligible means: Sitebulb Desktop installed, signed in, running, on an active licence, on a version that supports MCP, and online recently enough to be seen. Fix whichever of those isn't true, give it a minute, and try again.
Data problems
"Project or audit not found"
This is the MCP failing loudly rather than guessing, which is what you want. It almost always means the assistant guessed or reused a stale reference instead of looking the project up fresh, or you're connected to a different workspace or machine than the one holding the project. Ask the assistant to list your projects by name again (and that project's audits, if needed), then repeat your question using a name it just confirmed exists.
An error about the audit not being finished
Per-crawl data (hints, insights, URLs, reports) only exists once the crawl completes. Wait for it to finish and ask again, or point your question at an audit that's already done. Don't ask the assistant to retry in a loop or to estimate from partial data - an unfinished audit can't be summarised accurately.
Empty results when you expected some
Three possibilities, in order of likelihood: the audit hasn't finished (which should surface as an error - if your assistant presented it as clean empty data, ask it to check the audit's status); the assistant resolved the wrong project or an older audit (ask it to confirm which it used); or the category is genuinely empty for this audit, which is a real answer, not a fault. Not every crawl has findings in every category.
I only got 50 URLs back
That's by design. For any single hint, the MCP returns a sample of up to 50 example URLs, not the full list - it keeps answers fast and readable, and a sample is enough to see the shape of an issue and spot-check real pages. The same applies to Lost & Found URL comparisons. When you need every affected URL, use the export in the Sitebulb app; the MCP isn't a bulk-export mechanism.
A comparison says there's no previous audit
Lost & Found compares an audit against the one before it in the same project, so it needs at least two finished crawls to work with. On a project's first audit there's simply nothing to compare yet - run the next scheduled crawl and the comparison will light up.
It answered from the web, not my data
Remind it: "Use the Sitebulb MCP for this." Making "Using the Sitebulb MCP..." the first words of your prompt is the habit that prevents this altogether.
It says it's being rate-limited or told to slow down
Normal protective behaviour when a lot of requests land in a short window, not a sign anything's broken. Wait a short while and ask again - and don't ask the assistant to retry in a tight loop, which only extends the wait.
When these docs don't match your screen
AI clients rename menus, move buttons, and redesign settings screens faster than any documentation can track. If a step here names a control you can't find, look for whatever in your client matches the described purpose - the screen listing connected apps, connectors, or plugins is the usual suspect, and it tends to live near account settings or in the chat composer whatever it's called this month. That drift is expected; it doesn't mean the Sitebulb MCP has changed or broken. If you genuinely can't find an equivalent control, contact support and tell us which client and which step, so we can point you right and fix the doc.
Frequently asked questions
Can my AI assistant change or delete anything in Sitebulb through this?
No. Every tool is read-only. It can't start, pause, stop, or delete a crawl, and it can't change a setting, no matter what it's asked. See What the Sitebulb MCP can and can't do.
Can it run a crawl for me?
No. Set up and schedule crawls in Sitebulb as you always have; the MCP reads the results once they're done.
Can it export every URL affected by an issue?
No - you get a sample of up to 50 URLs per hint. For the complete list, use the export in the Sitebulb app.
Which AI assistants are supported?
Claude and ChatGPT, with step-by-step guides for both, on Cloud and Desktop. The MCP is an open standard though, so most other MCP-capable clients (Perplexity, Cursor, Claude Code, Codex) should also connect - see Connect any MCP client to Sitebulb.
Do I need an API key?
No. Signing in and approving is the only connection method - there's no key to generate, manage, or lose.
Is my data safe? Where does it actually go?
The connection is read-only, uses your own sign-in, and only moves data into the chat when you ask a question. The full picture - including the part governed by your AI provider rather than Sitebulb - is in the Sitebulb MCP: security and privacy overview.
Will my crawl data be used to train AI models?
That's decided by your own agreement and settings with your AI provider (Anthropic for Claude, OpenAI for ChatGPT), not by Sitebulb. Check the data controls in your Claude or ChatGPT account - once an answer is in your chat, it's handled like anything else you'd paste there.
Can teammates see my data through my connection?
No. Connections are per-user: each person signs in as themselves and their assistant sees what their own Sitebulb account can see. That's also why removing one person's access never affects anyone else's.
How do I disconnect Sitebulb from my AI assistant?
Remove the Sitebulb connector from inside the AI client - that's the whole job. Steps for both clients, plus an offboarding checklist, are in Disconnecting and revoking Sitebulb MCP access.
Which Sitebulb plans include the MCP?
Sitebulb MCP is supported on all Cloud plans and on Sitebulb Desktop Pro - the only plan it is not supported on is Sitebulb Desktop Lite.
You can also use the Sitebulb MCP on the Sitebulb Desktop trial.
Still stuck?
If nothing above matches, or the fix didn't take, get in touch - through the messenger on this help centre, or however you usually reach Sitebulb support. Include all four of these in your first message and you'll save a whole round trip:
Which surface: Sitebulb Cloud or Sitebulb Desktop (or both).
Which AI client: Claude or ChatGPT, and whether it's the web or desktop app version.
Roughly when it started: "this morning" or "since I reconnected on Tuesday" both help narrow down what changed.
The exact error text, copied not paraphrased. An error message often points us straight at the cause.