MCP server
Errors and troubleshooting
What goes wrong when using Platform through an AI assistant, and how the assistant and you recover.
There are two kinds of problem:
- Connection problems: the assistant can’t reach Platform at all. You fix these in your assistant’s settings.
- Tool errors: the connection works, but one call was refused. The error message goes back to the assistant, which reads it and usually corrects itself, for example by fetching a missing ID and trying again.
Connection problems
| What you see | Why | Fix |
|---|---|---|
| The assistant says it has no Platform tools | The connector isn’t added, it’s switched off for this chat, or the chat started before you added it | Add it (Quickstart), enable it in the chat’s connector menu, then start a new chat |
| It asks you to sign in to Platform | Your connection URL has no ?token=… part, so the assistant uses OAuth: this is expected once. Sign in with your dashboard email and password (10 failed attempts in 15 minutes lock sign-in for 15 minutes) | Sign in, or paste the full connection URL with ?token=… from Integrations → MCP Server so no sign-in is needed |
It asks you to sign in although you pasted a URL with ?token=…, or reports 401 unauthorized (Bearer token required…) | The key in the URL is wrong: cut short when pasting, or rotated since you copied it | Copy the whole connection URL again from Integrations → MCP Server and replace the old one in your assistant |
| “Session not found or expired. Reconnect via /mcp/sse” | An older SSE connection dropped | Reconnect the connector; newer clients use Streamable HTTP and don’t hit this |
| It connects but tools time out | Your network blocks outside MCP servers | Ask your IT team to allow rest-dash.revealid.xyz |
Tool errors
Tool errors come back as a message the assistant can read, marked as an error:
{ "error": "Tool not available for website-scoped key. Ask your account owner for a master key." }| Message | Why | What the assistant should do |
|---|---|---|
| “Tool not available for website-scoped key…” | A team member’s URL was used for an account-level tool, such as list_websites or get_account | Tell you the account owner needs to do it, or connect with the owner’s URL |
| It returns another website’s data, or ignores the website you named | A team member’s URL reaches one website only: any websiteId the assistant sends is replaced by that website’s id, without an error | Connect with the account owner’s URL, or copy a URL while the right website is open. See What each connection can reach |
| “websiteId is required…” / “…needs a prospectId (24 hex characters)” | It skipped a lookup step | Call list_websites (or the matching list_ tool) for the ID, then retry |
| “Your plan does not allow the prospector” (403) | The plan doesn’t include that feature | Stop and tell you; the fix is a plan change, not a retry |
| “You exceed the limits” (429) | On a search: the plan’s search limit is used up, or the call came less than a second after the previous search (a refused call is not counted) | Wait a second and retry once; if the plan limit is used up, stop and tell you |
“Free tools: 10 calls a day per account, resets 00:00 UTC.” (429), or emailStatus “daily free limit reached — resets 00:00 UTC” | The free tools share 10 calls and 10 verified business emails per account per day | Wait for 00:00 UTC, or use the paid tools such as search_people |
| “You have reached your limit.” / “You have no credit.” (400), “Insufficient credits” (402), “You cannot add more websites, please upgrade” (401) | A plan limit or the credit balance is used up | Stop and tell you; get_account shows what is left. The fix is more credits or a plan change |
| Payment required, with an upgrade link (402) | The tool needs an add-on, e.g. verify_contact needs Email Waterfall | Show you the link; don’t retry |
503 provider_unavailable, or “Free tools are unavailable right now, please retry.” | The data source behind that tool was busy (search_companies, search_domain_availability, the free tools) | Retry once after a minute; nothing was charged |
| Empty results | Nothing matched | Suggest widening the filters, e.g. a bigger company size or more job titles |
For assistant builders
- Tool failures come back as tool results with
isError: trueand a JSONerrormessage, not as protocol errors, so the model can read the reason and adjust. - Treat plan, add-on and permission errors as final: retrying won’t change the answer. Treat
503as temporary: one retry after a pause. - The server validates every input. The tool descriptions say which lookup tool provides each ID (
list_websites→websiteId,search_people→profileId). - A missing or bad key is an HTTP
401with aWWW-Authenticateheader pointing at/.well-known/oauth-protected-resource, so OAuth-capable clients start sign-in by themselves.