If you are unable to connect the Search Atlas MCP or your connection is not working correctly, this guide covers the most common causes and how to resolve them.
The MCP connection relies on a working login session, valid plan access, and an active authentication token. When any of these fail, the connection may not complete or tools may not work after connecting.
⚙️ Step-by-Step: Fix MCP Connection Issues
Follow these checks in order to resolve the most common causes of failure.
🔍 Issue 1 — You Are Not Logged Into Search Atlas
What happens
When the browser window opens during connection, the login flow fails or does not complete properly.
How to fix
Step 1
Open:
👉 https://dashboard.searchatlas.com
Step 2
Sign in to your Search Atlas account
Step 3
Return to your MCP client
Step 4
Retry the connection process from within your MCP client. The exact steps to retry or reconnect vary by client (for example, Claude Code, Cursor, and other MCP-compatible tools each have their own reconnection UI) — refer to your client's documentation or our connection guide for client-specific instructions.
🔍 Issue 2 — Your Plan Does Not Include MCP Access
What happens
- The connection may complete
- But MCP tools fail when executed
This is because MCP access is controlled at the plan level.
How to fix
Step 1
Check your Search Atlas plan in the billing area of your dashboard: 👉 https://dashboard.searchatlas.com/billing
Step 2
Confirm that MCP access is included on your current plan. MCP access is available on eligible paid Search Atlas plans — if you are unsure whether your tier qualifies, review the plan details on the billing page or visit the Search Atlas pricing page.
Step 3
If MCP is not included, contact your account team or upgrade your plan
🔍 Issue 3 — Session Is Expired or Stale
What happens
- Authentication fails
- Connection stops working after setup
- Tool calls return errors
This occurs when the authentication token is no longer valid.
How to fix
Step 1
Open your MCP client
Step 2
Disconnect the Search Atlas MCP
Step 3
Reconnect the MCP using the current Search Atlas endpoint: https://mcp.searchatlas.com/mcp/. The Search Atlas MCP server now uses the Streamable HTTP transport (it previously used SSE), so if you have an older SSE-based URL saved in your client configuration, replace it with the Streamable HTTP endpoint above before reconnecting. The exact reconnection steps differ by MCP client (Claude Code, Cursor, and others each handle this in their own UI) — see your client's documentation if you are unsure where to update the endpoint.
Step 4
Complete the login flow again
This triggers a fresh authentication session.
🔍 Issue 4 — “Invalid Token” Errors
What happens
The client reports an invalid token even after login.
Why this happens
The server rejects tokens that are close to expiration instead of allowing them to fail mid-request.
How to fix
Step 1
Disconnect the MCP
Step 2
Reconnect the MCP
Step 3
Complete a fresh login
🔍 Issue 5 — Connection Works but Tools Fail
What happens
- MCP connects successfully
- But actions fail or return errors
Possible causes
- Plan does not include required product area
- Quota is exhausted
- Permissions are restricted
How to fix
Step 1
Check your plan entitlements
Step 2
Check your quota usage
Step 3
Retry the action after confirming access
🔍 Issue 6 — MCP Tool Fails When Deploying Domain-Level Schema
What happens
When attempting to deploy schema at the domain level through the MCP, the tool call fails with an HTTP 400 response containing the message otto_urls not found.
Why this happens
This is a known platform-side issue with domain-level schema deployment via MCP. It is not caused by a misconfiguration on your side, and the fix requires a platform update.
How to fix
Contact Search Atlas support to confirm your account is tracked against this issue, and watch for a platform update that addresses it. In the meantime, deploy schema through the Search Atlas dashboard instead of through the MCP where possible.
🔍 Issue 7 — Platform Outage or Backend Error
What happens
The MCP or Atlas Brain consistently fails even after you have verified your login, plan access, and reconnected with a fresh session. This can indicate a platform-wide outage or a backend error rather than a local configuration problem.
How to identify a server-side issue
- The same error occurs across multiple devices
- The same error occurs in an incognito or private browser window
- Other Search Atlas surfaces (dashboard, API) also return errors or load slowly
- The error message references a 5xx status code or a generic backend failure
How to fix
Check for any reported platform issues, then contact Search Atlas support with the error message, the affected tool, and the approximate time of the failure. If you have already worked through Issues 1–3 above without success, this is the recommended next step.
⚠️ Additional Notes
- The MCP uses the same authentication and rate limits as the Search Atlas API
- A failed tool call may return a structured error with details
- Reconnecting the MCP resolves most session-related issues
Most MCP connection issues are caused by login state, plan access, or expired sessions. By checking these in order and reconnecting when needed, you can restore full access and continue using Search Atlas through your AI assistant.