Troubleshooting: MCP & API Access

🔧 Troubleshooting Cloudflare Token Paste Errors in Search Atlas

This article helps you resolve the error that appears when you paste a Cloudflare API token into Search Atlas. The error is almost always caused by one of a few specific token configuration issues — this guide walks you through each one so you can identify and fix the exact cause. 🔍 Common Causes - Incorrect token permissions: The token was created without the required permissions for Search Atlas to connect. - Token scope too narrow: The token is scoped to a specific zone (domain) but Search Atlas requires access to all zones, or vice versa. - Extra whitespace: Copying the token from Cloudflare sometimes includes a leading or trailing space, which causes the validation to fail silently. - Token was created as a Global API Key instead of an API Token: Search Atlas requires an API Token, not the Global API Key. - Token has been revoked or expired: A previously working token may have been deleted or expired in Cloudflare. 🛠️ Step-by-Step 1. Log in to your Cloudflare dashboard at dash.cloudflare.com and go to My Profile → API Tokens. 2. Verify you are using an API Token, not the Global API Key. The Global API Key will not work. If you used the Global API Key, you must create a new API Token instead. 3. Check the token's permissions. The token must include at minimum: Zone → DNS → Edit and Zone → Zone → Read. Read-only DNS access is not enough because OTTO writes DNS settings (it enables DNS proxy on DNS-only records). If these permissions are missing, click Edit on the token, add the missing permissions, and save. 4. Check the token's Zone Resources scope. Set it to All zones unless Search Atlas documentation specifies a single-zone scope. Mismatched scope is a frequent cause of this error. 5. Regenerate the token if you are unsure of its current state. In Cloudflare, click Roll (or delete and recreate it) to get a fresh token value. 6. Copy the new token carefully. Click the copy icon in Cloudflare rather than selecting the text manually. This reduces the risk of copying extra whitespace characters. 7. Paste the token into Search Atlas by opening your project settings and navigating to the Cloudflare integration field. Before saving, click inside the field and press Ctrl+A (or Cmd+A on Mac) to select all, then paste — this replaces any previous value fully rather than appending. 8. Save the token and wait for the connection validation to complete. ✅ How to Confirm It Worked After saving, Search Atlas will attempt to validate the token immediately. You will know the connection succeeded when: - The error message disappears and is replaced by a green success indicator or a confirmation message such as "Token connected" or "Cloudflare connected successfully." - Your Cloudflare zones or domain data become visible within the integration area — if zones were not populating before, they should now appear in a dropdown or list. - No red error banner is shown after saving. If the red error persists even after following all steps, the token value itself is the issue — return to Cloudflare and create a brand-new token from scratch rather than reusing the same one. If you need further assistance, open the chat widget in the bottom-right corner of the platform and type human teammate to be connected with a member of our team.

⚡ Search Atlas REST API Authentication and Error Fixes

Overview The Search Atlas REST API requires proper authentication before making API calls. Understanding how to obtain and use the correct credentials is essential to successfully integrating with the API. This article covers how to authenticate with the Search Atlas API and how to resolve common API errors related to credential configuration. Part 1 — Authenticating with the Search Atlas REST API The Search Atlas REST API uses a token-based authentication system. To make authenticated API requests, you must first obtain an access token using your Search Atlas account credentials. What credentials are required? - username — your Search Atlas account email address (the same one you use to log in to app.searchatlas.com) - password — your Search Atlas account password These are the same credentials you use to log in to the main platform. Once you have obtained your access token, include it in the headers of subsequent API requests as a Bearer token. Important notes: - Access tokens are time-limited. If you receive an authentication error mid-session, re-request a fresh token and retry your request. - Make sure you are using your Search Atlas login credentials, not a separate API key, when requesting an access token from the token endpoint. - Avoid hardcoding credentials directly in shared scripts. Use a secure credential storage method appropriate for your integration environment. Part 2 — Fixing Common API Authentication Errors If you are receiving authentication or configuration errors when calling the Search Atlas API, the most common causes are: 1. Wrong credential type — Using the wrong value (for example, passing a login password where an API key is expected, or vice versa). Confirm which credential type each endpoint requires before making calls. 2. Incorrect or malformed credential — The credential was copied with extra whitespace, a missing character, or from an outdated or revoked source. Copy your credentials carefully from your Search Atlas account settings. 3. Credential not yet generated — If you have not yet created an API key or token in your account, the relevant endpoint will reject your request. Check your account settings to confirm your credentials exist and are active. 4. Incorrect endpoint URL — Requests sent to a wrong or mistyped endpoint path will return errors. Double-check the endpoint URLs against the official Search Atlas API documentation. If you are unsure which credentials or endpoint configuration apply to your specific use case, gather the following before escalating: the endpoint URL you are calling, the exact error message or response code you are receiving, and the credential type you are passing. If you need further assistance, open the chat widget in the bottom-right corner of the platform and type human teammate to be connected with a member of our team.

🏷️ GHL API Keys Page Branding Fix

A branding inconsistency in the API Keys page has been resolved for GoHighLevel (GHL) users. The SearchAtlas name was incorrectly appearing in description text on that page, and it has now been corrected to reflect the proper white-label branding. ✨ What's New The API Keys page description text in GHL environments was displaying SearchAtlas branding instead of the expected white-label branding. This fix ensures that the platform identity remains consistent and fully white-labeled throughout the GHL experience, including the API Keys section. 📋 What to Expect GHL users will no longer see any SearchAtlas branding references within the API Keys page description text. All other areas of the platform that rely on white-label branding are unaffected by this change. No action is required on your part — the update is applied automatically. If you need further assistance, open the chat widget in the bottom-right corner of the platform and type human teammate to be connected with a member of our team.

🔧 Fix Cloudflare Worker API Token Validation Failures

Overview API token validation errors in the SearchAtlas Cloudflare Worker typically trace back to one of two root causes: the Worker script was not deployed correctly, or the API token is missing the required permissions. This article explains what to check and what information to have ready so our team can resolve the issue quickly. Step 1: Confirm You Have the Correct Worker Script Before troubleshooting token validation, confirm you are using the official SearchAtlas Worker script — not a generic Cloudflare template or an outdated version from a previous installation. - Log in to your SearchAtlas account and locate the Cloudflare Worker integration section to retrieve the current Worker script. If you are unsure where to find this in your account, our support team can point you to the exact location. - Do not use a script obtained from a third-party source or one that predates your current SearchAtlas account, as a mismatched script is a common reason token validation fails. Step 2: Deploy the Script in Cloudflare Once you have the correct SearchAtlas Worker script, deploy it through your Cloudflare dashboard. Replace any existing Worker code with the latest SearchAtlas script in full, then save and redeploy. Running an outdated script version can cause token validation to fail even if your token permissions are otherwise correct. After deploying, note the Worker's URL — you will need it when configuring the integration in SearchAtlas. Step 3: Review Your Cloudflare API Token Permissions Cloudflare API tokens are permission-scoped. A token that lacks the required permissions will fail SearchAtlas validation. When creating or reviewing your token in the Cloudflare dashboard, ensure it includes the permissions necessary for Cloudflare Worker script deployment and API token validation as required by the SearchAtlas integration. If you are unsure which permissions are needed, or if the token continues to fail validation after reviewing your setup, our support team can assist you directly. What to Have Ready When Contacting Support If you are unable to resolve the validation failure on your own, please have the following information ready before reaching out: - Your SearchAtlas project name - The exact error message you are seeing during token validation - A timestamp of when the error first occurred - A brief description of any changes made to your Worker script or API token before the issue began If you need further assistance, open the chat widget in the bottom-right corner of the platform and type human teammate to be connected with a member of our team.

🔧 Cloudflare API Token Permissions for Clearview

🌐 Overview Connecting Clearview to your Cloudflare account requires a Cloudflare API token with specific permissions. A common issue customers encounter is searching for a Workers Routes permission that no longer exists in the current Cloudflare dashboard. This article explains exactly which permissions to select and how to create the token correctly using the updated Cloudflare UI. ⚠️ Common Mistake: Workers Routes Permission Older versions of the Clearview integration guide referenced a Workers Routes permission inside Cloudflare's token creation screen. Cloudflare has since redesigned their token creation interface, and this permission label no longer appears. If you have been searching for it, that is why the setup has been failing. You do not need a Workers Routes permission — follow the steps below to configure the correct permissions. ✅ Required API Token Permissions When creating your Cloudflare API token for the Clearview integration, you must include the following permissions: - Zone — DNS — Edit: Allows Clearview to read and update DNS records on your domain. - Zone — Zone — Read: Allows Clearview to identify and access your Cloudflare zone (domain). These two permissions are sufficient for the integration to function. Do not add unnecessary permissions, as this can cause authorisation errors. 🛠️ How to Create the API Token 1. Log in to your Cloudflare dashboard at dash.cloudflare.com. 2. Click your Avatar Menu (👤) in the top-right corner and select My Profile. 3. Navigate to the API Tokens tab on the left sidebar. 4. Click Create Token. 5. Scroll down and select Create Custom Token by clicking Get started. 6. Give your token a recognisable name, such as Clearview Integration. 7. Under Permissions, add the following two permission rows: - Row 1: Select Zone — DNS — Edit - Row 2: Click Add more, then select Zone — Zone — Read 8. Under Zone Resources, set the scope to Include — Specific zone and select the domain you are connecting to Clearview. 9. Click Continue to summary, review the permissions, then click Create Token. 10. Copy the token immediately — Cloudflare will only show it once. 🔗 How to Enter the Token in Search Atlas 1. Open the Search Atlas platform and navigate to the Clearview integration settings. 2. Paste your Cloudflare API token into the designated field. 3. Click Connect or Save to complete the integration. 4. Wait a few moments for the connection to verify. A green confirmation indicator means the integration is active. 🚨 Troubleshooting: Authorisation Failed (cf_10000) If you see an error message referencing Cloudflare API Authorization failed or error code cf_10000, this usually means one of the following: - The token was created with missing or incorrect permissions — recreate it using the steps above. - The token was scoped to the wrong zone — ensure the correct domain is selected under Zone Resources. - The token was not copied in full — return to Cloudflare, revoke the old token, and generate a new one. After fixing the token, return to the Clearview integration settings in Search Atlas, remove the old token, paste the new one, and reconnect. 💬 Need More Help? If you need further assistance, open the chat widget in the bottom-right corner of the platform and type human teammate to be connected with a member of our team.

🛠️ Fix API 404 Errors Fetching Published Content

🔍 Overview If you are calling the Search Atlas API to retrieve published content and receiving a 404 error, you are not alone. This error can appear even when your published articles are clearly visible inside the Search Atlas platform. This article explains what to have ready when escalating this issue to our support team. ⚙️ What This Error Means A 404 response when retrieving published content via the Search Atlas API indicates that the server could not locate the requested resource at the time of the call. Because the root cause requires investigation on the backend, our support team will need to look into your specific account and request details to identify what went wrong. 🚀 What to Do This issue requires backend investigation by our support team. To help us resolve it as quickly as possible, please have the following information ready before reaching out: - The exact API endpoint URL you are calling, copied directly from your integration or logs. - The full error response you are receiving, including any response body or headers. - The name of the workspace or project where the published content is located. - The timestamp of when the 404 error occurred (date and time, including timezone). - Confirmation of the content status — whether the affected content is confirmed as fully published inside the platform at the time of the error. If you need further assistance, open the chat widget in the bottom-right corner of the platform and type human teammate to be connected with a member of our team.

Fix Twitter/X OAuth Integration Login Loop

🔍 Overview Some users experience a login loop when attempting to connect their Twitter/X account in Search Atlas. Instead of completing the connection, the platform repeatedly redirects to a sign-in page even when you are already logged in to Twitter/X. This issue requires investigation and resolution by our support team directly on your account. ⚠️ What This Looks Like - You click the option to connect your Twitter/X account. - You are redirected to a Twitter/X sign-in or authorization page. - After signing in (or if you are already signed in), the page loops back and requests sign-in again. - The account never successfully links and you cannot proceed. ✅ Steps to Resolve 1. Contact our support team and describe the loop you are experiencing. Because this issue requires back-end investigation on your specific account, reach out to our support team so they can examine the OAuth connection directly and get your Twitter/X account linked. To contact support, use the live chat widget in the bottom-right of the platform. 2. Provide your account details when you reach out. Share the email address associated with your Search Atlas account and confirm which Twitter/X account you are trying to connect. This allows the team to locate your account and investigate the OAuth issue promptly. 3. Our team will investigate and resolve the OAuth connection on your behalf. Once the team has reviewed the back-end state of your account's Twitter/X integration, they will apply the necessary fix and confirm when your account has been successfully linked. 💡 While You Wait - Make sure you are fully logged in to your Twitter/X account in your browser, as an active session may assist the team's investigation. - Do not attempt to disconnect or reconnect the account repeatedly, as this may complicate the back-end state our team needs to review. 🆘 Still Experiencing the Loop? If your Twitter/X connection loop is still occurring after contacting us, please reply to your existing support conversation so we can continue investigating. You can also reach our support team using the live chat widget in the bottom-right of the platform.

🔌 Fixing MCP Tool Count Differences in Claude Code

🧭 Overview When you connect the Search Atlas MCP (Model Context Protocol) server to Claude Code, you may notice that the number of available tools is lower than the full published count. For example, you might see 475 tools instead of 607, and a specific tool or skill such as /onboard-client may appear to be missing. This is almost always expected behavior caused by client-side limits and configuration, not a fault with your account. This article explains why the difference happens and how to restore access to the tools you need. 🔎 Why the Tool Count Looks Lower The Search Atlas MCP server exposes a large catalog of tools and skills. The number that actually appears in Claude Code can be smaller for several common reasons: - Client tool limits: Claude Code caps how many MCP tools it loads at once to protect performance. When the catalog exceeds that cap, some tools are not registered. - Multiple connected servers: If you have other MCP servers connected, they share the same tool budget, leaving fewer slots for Search Atlas tools. - Permission scope: Your plan, role, or workspace permissions may hide tools you are not entitled to use. - Version mismatch: An outdated Claude Code build or MCP server version may not expose newly added tools. - Filtering or allowlists: Project or user settings can explicitly enable or disable specific tools, which changes the visible count. 💡 Why a Specific Tool Is Missing A tool like /onboard-client disappearing usually points to one of these causes: - It falls outside the loaded tool limit and was dropped when the catalog was truncated. - It is gated behind a permission or feature your current workspace does not have enabled. - It was renamed or grouped under a different skill in a newer release, so an older client no longer recognizes it. 🛠️ How to Restore Missing Tools Work through these steps in order. Most customers regain full access after the first two. 1. Update everything: Make sure Claude Code and the Search Atlas MCP connection are on their latest versions. Restart Claude Code after updating so the tool list reloads. 2. Reduce connected servers: Temporarily disconnect other MCP servers you are not using. This frees space in the tool budget so more Search Atlas tools can load. 3. Raise the tool limit: In your Claude Code configuration, increase the maximum number of MCP tools allowed if your setup permits it, then reconnect. 4. Reconnect the MCP server: Remove and re-add the Search Atlas MCP connection to force a fresh sync of the full catalog. 5. Check your permissions: Confirm your Search Atlas plan and workspace role include the tools you expect. Some tools are only available on specific tiers. 6. Search directly: If a tool is not shown in the list but you know its name, try calling it directly (for example, /onboard-client). Some clients keep tools available even when they are not displayed in the visible count. ✅ Confirming the Fix After making changes, reload Claude Code and review the tool count again. It is normal for the number to still be slightly lower than the full published total because of client limits. What matters is that the specific tools you need — including /onboard-client — are now reachable. Test the tool you were missing to confirm it works end to end. 📌 Good to Know - A tool count that is lower than the maximum is not a bug on its own; it reflects client-side limits. - Keeping only the MCP servers you actively use gives Search Atlas tools the best chance to load fully. - Tool availability can change between releases, so staying updated is the most reliable way to keep the full catalog.

🛠️ Fix WebSocket 403 Errors on MCP Bulk Send

🔍 Overview When using the Search Atlas AI Agent via the Model Context Protocol (MCP), calls to ws_bulk_send_message may return an HTTP 403 Forbidden error on the WebSocket channel. This article explains why this happens, how to confirm the root cause, and what steps to take to restore normal functionality. ⚠️ What Causes the 403 Error? An HTTP 403 (Forbidden) response on a WebSocket upgrade or message-send request means the server received your connection attempt but rejected it due to a missing, expired, or malformed JSON Web Token (JWT). Because ws_bulk_send_message relies on the same authenticated WebSocket channel used by Website Studio's MCP tools, a broken token blocks every bulk message call — even when the underlying message delivery actually succeeds on the server side. A 403 error on ws_bulk_send_message is almost always caused by one of the following: - Expired or invalid JWT token: The authentication token used to open the WebSocket connection has expired or was not issued correctly, causing the server to reject subsequent message calls. - MCP bulk sends disabled at the project level: In some cases, the ability to send bulk messages via MCP can be turned off for a specific project, either by a configuration change or a platform update. - Incorrect WebSocket endpoint: An older integration may be pointing to a deprecated REST endpoint instead of the correct WebSocket channel, resulting in auth failures. An earlier version of Website Studio's V2 integration attempted REST endpoint calls instead of routing traffic through the correct WebSocket channel, producing 403 and 404 responses. - False failure reporting: In some resolved cases, ws_bulk_send_message reported a 403 failure even though the message was delivered successfully. This was a known bug that has since been fixed. - create_project dependency: Because create_project and ws_bulk_send_message share the same authenticated session setup, a broken project-creation flow could leave the WebSocket channel in an unauthenticated state for all subsequent calls. Common symptoms include: - All ws_bulk_send_message calls return 403 immediately without queuing messages. - Website Studio editing tools (create_project, page edits) also fail or return errors when accessed via MCP. - The AI Agent log shows JWT auth errors alongside the 403 response. - Some messages appear delivered in the UI despite the 403 error in the API response — this is a known false-failure behaviour that has been patched. ✅ How to Confirm the Root Cause Before taking corrective action, follow these steps to identify exactly what is causing the error in your project: 1. Check your JWT token validity. Inspect the token being passed in your MCP connection headers. Tokens typically expire after a set period. If the token is expired, re-authenticate to generate a new one and re-establish the WebSocket connection. 2. Verify your WebSocket endpoint. Confirm that your integration is connecting to the correct WebSocket URL for the Search Atlas agent channel. If you see REST-style URLs (e.g., /api/v2/...) in your request logs, your integration may be misconfigured and needs to be updated to use the WebSocket endpoint. 3. Test with a fresh project. Create a new project and attempt a ws_bulk_send_message call. If the call succeeds on a new project but fails on the original one, the issue is likely tied to that specific project's configuration. 4. Check whether MCP sends are enabled. In your project settings, confirm that MCP-based messaging is active. If the option appears greyed out or unavailable, the feature may have been disabled for your account or project. Note that a true MCP-disabled state returns a configuration-level error message (such as "MCP tool not available" or "feature disabled") indicating the feature is turned off — it does not return an HTTP 403. If you are receiving a 403 specifically, MCP messaging is enabled but the request is being rejected at the authentication layer. 5. Review recent platform updates. If the error appeared suddenly without any changes on your end, it may be related to a recent platform update. Check the Search Atlas changelog or status page for any relevant notices. 🔧 Steps to Restore ws_bulk_send_message Once you have identified the cause, use the appropriate fix below: - Expired JWT token: Re-authenticate your MCP client using your Search Atlas credentials to obtain a fresh JWT token. In Search Atlas, go to Avatar Menu (👤) → Settings → API Keys and regenerate your API key. Copy the new key and update it in your MCP client configuration. Restart your AI Agent or MCP client to force a fresh WebSocket handshake with the new JWT. Do not reuse a cached session token from before a fix was deployed. Update your WebSocket connection to use the new token before retrying ws_bulk_send_message. - Wrong endpoint: Update your integration to point to the correct WebSocket channel. Remove any references to legacy REST endpoints. Contact support via the chat widget if you need the current endpoint details for your account. - Project-level configuration issue: If a specific project appears to have MCP messaging disabled or misconfigured, try removing and re-adding the project connection within the AI Agent settings. This resets the channel configuration. Also confirm that the target project was created successfully by opening Website Studio and verifying it exists. If create_project previously failed silently, the project may be missing, which will cause all subsequent ws_bulk_send_message calls to 403 because there is no valid channel to attach to. Re-run create_project if needed. - False failure on successful delivery: If your messages are actually being delivered despite the 403 error appearing in your logs, this was a known reporting bug that has been resolved in recent platform updates. Ensure your platform is on the latest version and verify message delivery directly in Website Studio before assuming a failure occurred. If you retried sends during the false-failure window, your project may contain duplicate content — review the affected pages in Website Studio and remove any duplicates manually. - Test with a single message first. Before running a bulk send, call ws_bulk_send_message with a single small payload to confirm the channel is authenticated and returning 200. 🚫 How to Confirm if MCP Sends Are Disabled To check whether MCP bulk messaging has been disabled for your project: 1. Click Atlas Agent in the header (e.g., 'Launch Atlas Agent' on Home). 2. Navigate to the project in question and open its MCP Channel Settings. 3. Look for a toggle or status indicator labelled Bulk Messaging or MCP Sends. If it is off, enable it and save your changes. 4. Retry the ws_bulk_send_message call to confirm the error is resolved. If the toggle is not visible or cannot be enabled, the feature may require reactivation at the account level by a member of our team. If you see a message such as "MCP tool not available" or "feature disabled", contact support to confirm your plan includes MCP access. 💡 Prevention Tips - Always handle JWT token expiry gracefully in your MCP integration by implementing automatic re-authentication before the token expires. - Log both the HTTP status code and the actual delivery outcome separately so you can distinguish between true failures and false reporting errors. - After any Search Atlas platform update, do a quick test call on your most active projects to confirm WebSocket connectivity is intact. - After any bulk send retry cycle, review affected pages in Website Studio to check for duplicate content that may have been created during a false-failure window. 🙋 Still Need Help? If you have followed the steps above and are still experiencing 403 errors on ws_bulk_send_message, our team can review your account's WebSocket logs directly. To reach us, open the chat widget in the bottom-right corner of the platform and type human teammate.

🔑 Fix Search Atlas MCP ChatGPT Authentication Errors

🧭 Overview The Search Atlas MCP (Model Context Protocol) server lets you connect Search Atlas tools directly to AI assistants like ChatGPT. However, setting it up for the first time — or after an API key change — can produce authentication errors or a 'no actions available' message. This article walks you through the correct setup process and the most common fixes. ⚙️ How the Search Atlas MCP Works with ChatGPT Search Atlas uses OAuth 2.1 to authenticate your ChatGPT connection. When you link the MCP server, ChatGPT receives a signed JWT (JSON Web Token) that grants it access to your Search Atlas tools — including GSC data, keyword research, and LLM Visibility features. Important things to know before you begin: - The Search Atlas MCP server is a standard remote MCP server that works with any MCP client, ChatGPT included. Whether a given ChatGPT app or plan lets you add a custom MCP connector is decided on ChatGPT's side. - Your Search Atlas account must be on a plan that includes MCP/AI Agent access. - JWT tokens are tied to your current API key. If you rotate your API key or disconnect a site, you must re-authenticate — existing tokens are not automatically invalidated but will stop working correctly. 🚀 How to Install the Search Atlas MCP in ChatGPT 1. In your ChatGPT-connected environment (e.g., ChatGPT desktop app or a GPT Action setup), open the plugin or action configuration panel. 2. Select Add an action or Connect an MCP server, then paste in the Search Atlas MCP Server URL. 3. When prompted for authentication, choose OAuth login (an active subscription is required), or alternatively authenticate with a Search Atlas API key from Settings → API Keys passed via the X-API-Key header. 4. If using OAuth, ChatGPT will redirect you to a Search Atlas login screen — sign in with your account credentials to complete the OAuth handshake. 5. Once authorised, return to ChatGPT. Your Search Atlas tools should now appear as available actions. 🛠️ Fixing 'No Actions Available' Errors If you see a 'no actions available' message after connecting, work through these steps in order: 1. Confirm your ChatGPT app and plan support custom MCP connectors. Custom MCP connector availability depends on the customer's ChatGPT app and plan (ChatGPT's side). 2. Re-check your authentication. Confirm you completed OAuth login with an active subscription, or that the Search Atlas API key from Settings → API Keys you provided in the X-API-Key header is valid. 3. Complete the OAuth flow fully. The connection only activates after you sign in on the Search Atlas authorisation page. If you closed that window early, disconnect and reconnect the integration to restart the flow. 4. Check your plan permissions. MCP access is not available on all plans. Verify that your subscription includes AI Agent or MCP features under Avatar (top-right) → Billing (Plans & Top-ups). 5. Rotate your token after an API key change. If you recently rotated your Search Atlas API key or disconnected a site, your previous JWT may be stale. Disconnect the MCP integration in ChatGPT, then reconnect it using fresh credentials from Search Atlas. 6. Wait up to two minutes. After a successful OAuth handshake, ChatGPT may take a short moment to load available actions. Refresh or restart the session before concluding there is a problem. 🔐 Understanding Token Behaviour Search Atlas issues signed JWT tokens during the OAuth flow. Keep these points in mind to avoid future authentication issues: - Tokens are valid for a set period. If your session expires, you will need to re-authorise the connection. - Rotating your Search Atlas API key does not automatically revoke existing JWTs. However, those tokens will lose access to protected data. Always reconnect after a key rotation. - Disconnecting a site from Search Atlas does not instantly invalidate tokens linked to that site. Reconnect the MCP integration after any major account change to ensure your tokens are fresh and correctly scoped. ❓ Frequently Asked Questions - Can I use the Search Atlas MCP in the ChatGPT web app? The Search Atlas MCP server works with any MCP client, ChatGPT included. Whether you can add a custom MCP connector depends on your ChatGPT app and plan (ChatGPT's side). - How many tools does the MCP give me access to? When correctly authenticated, the MCP unlocks tools across GSC data, keyword research, and LLM Visibility — over 70 actions in total. - Do I need to reconnect if I change my Search Atlas password? Changing your password alone does not affect your MCP token, but if you reset your API key you should reconnect the integration. 💬 Still Need Help? If you need further assistance, open the chat widget in the bottom-right corner of the platform and type human teammate to be connected with a member of our team.

🔧 Fix MCP Endpoint Connectivity and Initialization Failures

Overview The Search Atlas MCP (Model Context Protocol) endpoint allows external AI agents and tools to connect with your Search Atlas account. If you are seeing timeout errors, DNS resolution failures, or MCP initialization issues, this article explains what to have ready when escalating to our support team so we can investigate and resolve the issue on the backend as quickly as possible. Common Symptoms - DNS resolution failure: Your client cannot resolve the MCP endpoint domain - Connection timeout: The MCP endpoint does not respond within the expected window - Initialization error: The MCP handshake starts but fails before tools are loaded - API or server errors: Requests via MCP return error responses - Tool list empty or missing: Connected successfully but no tools appear What to Have Ready When You Contact Support MCP endpoint connectivity and initialization failures are typically caused by backend configuration issues that require investigation by our team. To help us resolve your case efficiently, please gather the following before reaching out via the chat widget: - Your Search Atlas account email or username - The exact error message you are seeing — copy it in full, including any error codes - The timestamp of when the failure first occurred or was most recently observed (include your timezone) - A description of your MCP client setup — for example, which AI agent or tool you are using to connect - Steps you have already tried — such as re-entering your API key, restarting your client, or checking your network connection - Whether the issue is consistent or intermittent — and if intermittent, how often it occurs Having this information ready will allow our team to investigate your specific account and endpoint configuration on the backend without unnecessary back-and-forth. If you need further assistance, open the chat widget in the bottom-right corner of the platform and type human teammate to be connected with a member of our team.

🛠️ Fix MCP WebSocket 403 Permission Errors

🔍 What Is This Error? When using the Search Atlas MCP (Model Context Protocol) server with an AI client like Claude to manage or edit your website, you may encounter an HTTP 403 error with a message such as "You do not have permission to perform this action." This error can appear when running playbooks, accessing SEO tools, or executing any MCP-connected operation. This is an authentication and permissions issue — it means the MCP server cannot verify that your session has the correct access rights to carry out the requested action. ⚠️ Common Triggers - Your MCP API credentials are missing, expired, or were not saved correctly. - The MCP connection was set up under a different workspace or user account than the one currently active. - Your Search Atlas session timed out, invalidating the active WebSocket connection. - A recent platform update reset or changed permission scopes for MCP integrations. - The connector was configured but has not completed its authorisation handshake. 🔧 Step-by-Step Troubleshooting 1. Verify you are in the correct workspace. In the left sidebar, click Coworker. At the top of the page, confirm the workspace name shown matches the project you are working on. If not, use the workspace switcher to select the right one. 2. Refresh your setup status. Go to Coworker → Overview tab and click Refresh setup status. Wait for the status indicators to update. A green status on all items confirms your agent connection is healthy. 3. Check your MCP connector. Navigate to Coworker → Connectors tab and click Manage connectors. Locate your MCP connector. If it shows an error state or a warning icon, click into it and re-authenticate by following the on-screen prompts to re-enter your API key or OAuth credentials. 4. Re-enter your Search Atlas API key in your MCP client. Open your MCP client configuration (for example, Claude's settings or your claude_desktop_config.json file). Confirm the API key entered matches the one found in your Search Atlas account. Copy a fresh key from your account settings if needed, paste it into the config, and save. 5. Restart the MCP server connection. After updating credentials, fully quit and relaunch your AI client (e.g., Claude Desktop) so it establishes a fresh WebSocket session with the updated credentials. Stale sessions will continue to produce 403 errors even after a key update. 6. Re-run the failing playbook or tool. Return to your AI client and retry the action that produced the 403 error. If the credentials and connector are correctly configured, the request should now succeed. 💡 Tips to Prevent This Error - Always complete the full connector setup flow in Coworker → Connectors tab before using MCP tools in your AI client. - If you belong to multiple workspaces, double-check the active workspace before running any agent playbook — permissions are workspace-specific. - Rotate API keys carefully: update them in your MCP client configuration immediately after generating a new key in Search Atlas to avoid session mismatches. - Keep your AI client (Claude Desktop or similar) updated to the latest version to ensure WebSocket compatibility with the MCP server. 🚀 Still Seeing the 403 Error? If you have followed all the steps above and the error persists, it is possible that a permission scope for your account or agent has not been correctly provisioned on the backend. This requires a manual review by our team. If you need further assistance, open the chat widget in the bottom-right corner of the platform and type human teammate to be connected with a member of our team.

🔧 Fix Signal Genesys External API 403 Scope Errors

Overview If every request you send to the Signal Genesys External API returns an HTTP 403 – Invalid scope provided error, your API token may be missing one or more required permission scopes. This article explains what causes the error and what to have ready when contacting our team to resolve it. What Causes the 403 'Invalid Scope' Error? A 403 scope error means your bearer token was authenticated successfully, but it does not have permission to perform the action you requested. Common reasons include: - The token was generated without the necessary permission scopes for the External API feature you are trying to use. - Your token was created with a limited scope configuration that excludes certain External API features. - Your plan tier may not include External API access, so the platform blocks those scopes entirely. - The token has expired or been rotated and the updated token was not saved in your integration. What to Do Because resolving a 403 scope error on the Signal Genesys External API requires backend verification of your token permissions and plan entitlements, our support team will need to investigate on your behalf. To help us resolve this as quickly as possible, please have the following ready before reaching out: - Your Search Atlas account email address - The exact 403 error message you are receiving - The specific API endpoint or action you are attempting to call - The date and time (with timezone) when the error first occurred - Your current plan or subscription tier, if known Do not share your full bearer token when contacting support — our team can look up your token configuration securely on the backend. If you need further assistance, open the chat widget in the bottom-right corner of the platform and type human teammate to be connected with a member of our team.

🔑 Troubleshoot Customer API Key 401 Errors

🔍 What a 401 error means A 401 Unauthorized response with "Bad API key" means Search Atlas could not authenticate the credential sent with the request. This usually results from an incorrect key, an unsupported header format, a hidden character, or using a key from the wrong environment. ✅ Check the API key and request format 1. Locate your API key in your Search Atlas account settings. 2. Confirm you copied the complete production key. Do not include quotation marks, spaces, line breaks, or other surrounding characters. 3. Review the endpoint documentation and use the required authentication header exactly as shown. Do not substitute a JWT, session token, or an older authentication format. 4. Confirm the request is sent over HTTPS and that your HTTP client is not removing or rewriting the authentication header. 5. Test with a simple request from a tool such as cURL or Postman before testing through your application. 🧪 Test with a clean request Create a new request using one documented endpoint and the current production base URL. Add only the required headers, including the API key header specified in the documentation. Avoid copying headers from a browser session, cached environment variables, or another integration. If the request works in cURL or Postman but fails in your application, compare the final outgoing request. Check for an empty environment variable, truncated value, extra whitespace, incorrect capitalization, or middleware that replaces the API key. 🔄 Rotate the key safely If the key still returns 401, generate a new API key from your Search Atlas account settings and update the integration. Store it securely as a secret, then retry the request. Do not publish API keys in source code, browser-side scripts, screenshots, logs, or support messages. After confirming the new key works, remove or revoke the old key if it is no longer needed. When rotating keys in production, update all services that use the credential before disabling the previous key. ⚠️ Check endpoint and account access API key authentication is supported on customer-facing endpoints documented for API-key access. Some specialized actions or connectors may require a different authentication method or may not support API keys. Verify that the endpoint, HTTP method, account, and production environment match the documentation. 🛠️ When to contact Search Atlas If newly generated production keys continue to return 401 on documented endpoints after completing these checks, have the following ready when you reach out: the endpoint path, HTTP method, response status, response message, and a redacted request example showing only the header names (never the key values). This information allows the team to investigate your account's API access quickly. If you need further assistance, open the chat widget in the bottom-right corner of the platform and type human teammate to be connected with a member of our team.

🔑 Fix External API 403 Scope Errors in Search Atlas

🔍 Overview If every External API call — including the token/validate endpoint — returns an HTTP 403 error with the message "Invalid scope provided. Check API Key permissions on your Press Releases account!", your API key is missing the press-release scope required by the Search Atlas External API (used by Signal Genesys). This article explains what causes the error and walks you through the steps to fix it. ⚠️ Understanding the Error The 403 response is a permissions error, not an authentication failure. Your API key is recognized, but it has not been granted the scopes needed to access press release endpoints. Common reasons this happens include: - The API key was created before the press-release scope was added to your plan. - The key was generated with default or limited permissions. - Your account plan does not currently include External API / press-release access. 🛠️ Step-by-Step: Check and Update Your API Key Permissions 1. Log in to your Search Atlas account and navigate to your Account Settings (click your Avatar Menu (👤) in the top-right corner). 2. Go to the API Keys or Integrations section within Account Settings. 3. Locate the API key you are using for your External API or Signal Genesys integration. 4. Click Edit or Manage Permissions on that key. 5. Look for the press-release scope (sometimes listed as External API or Press Releases) and ensure it is enabled. 6. Save your changes. 7. Re-run your API call to confirm the 403 error is resolved. If you do not see a press-release or External API scope option on the key, proceed to the next section. 📋 If the Scope Option Is Not Available The press-release scope may not be visible if it is not included in your current subscription plan. In that case, the scope cannot be enabled from within the API key settings alone — it must be unlocked at the account or plan level first. Here is what to check: - Plan eligibility: Confirm that your Search Atlas plan includes External API and Press Release access. Refer to your plan details in Account Settings under Billing or Subscription. - Regenerate the key: If the plan is correct but the scope is still missing, try deleting the existing API key and generating a new one. Newly created keys inherit the latest permissions tied to your account. - Existing keys: Keys created before a plan upgrade may not automatically receive new scopes. A fresh key should resolve this. 🔗 Reconnecting Signal Genesys After Fixing Permissions Once the correct scopes are in place, update the API key in your Signal Genesys configuration so the integration uses the updated credentials: 1. Copy your updated or newly generated API key from Search Atlas Account Settings. 2. Open your Signal Genesys settings and navigate to the Search Atlas API or External API connection section. 3. Replace the old API key with the new one. 4. Save and test the connection using the token/validate endpoint to confirm a successful 200 OK response. ✅ Verifying the Fix After updating your key and permissions, verify that the integration is working correctly: - The token/validate endpoint should return HTTP 200 instead of 403. - Press release submissions and other External API actions should complete without scope-related errors. - If you still receive a 403 after following all steps, the issue may require a backend scope assignment on your account that cannot be self-served. 💬 Still Seeing the 403 Error? If you have completed all the steps above and the error persists, the press-release scope may need to be manually enabled on your account by our team. If you need further assistance, open the chat widget in the bottom-right corner of the platform and type human teammate to be connected with a member of our team.

🔌 Fix External API 403 Scope Errors Fast

🔍 What This Article Covers If every call to the Search Atlas External API — including the token/validate endpoint — returns an HTTP 403 error with the message "Invalid scope provided. Check API Key permissions on your Press Releases account!", your API key is missing the press-release scope. This article explains what causes this error and the exact steps to resolve it. ⚠️ Understanding the 403 Error The 403 error means the API key you are using does not have permission to access the Press Releases (External API) scope. This is not a network issue or a bug in your integration code — it is a permissions configuration issue on your Search Atlas account. Until the correct scope is enabled, every API call, regardless of endpoint, will be rejected with this message. Common situations where this happens: - You recently generated a new API key but did not assign all required scopes. - Your account plan was changed and certain scopes were reset. - A team member created the API key without enabling the press-release permission. - You are using an older hardcoded token that no longer has the correct permissions. 🛠️ How to Fix the Scope Error Follow these steps to check and update your API key permissions inside Search Atlas. 1. Log in to your Search Atlas account. 2. Click your Avatar Menu (👤) or account name in the top-right corner of the platform. 3. Navigate to Account Settings and select the API Keys or Integrations section. 4. Locate the API key you are using for Signal Genesys or your External API integration. 5. Click Edit or Manage Permissions on that key. 6. Ensure the press-release scope (also labeled External API in some views) is toggled on. 7. Save your changes. 8. Re-run your token/validate call to confirm the 403 error is resolved. Important: If you do not see an option to enable the press-release scope, your current account plan may not include External API access. Contact our team using the chat widget to verify your plan includes this feature. 🔑 Best Practices for API Key Setup To avoid scope errors in the future, follow these recommendations whenever you create or rotate API keys: - Always review the full list of scopes before saving a new API key. - Enable only the scopes your integration actually needs — but do not accidentally leave required scopes unchecked. - Avoid hardcoding API tokens directly in your application code. Use environment variables or a secrets manager so tokens can be rotated without a code deployment. - After rotating a key, immediately run a validation call (token/validate) to confirm the new key has the correct permissions before pushing to production. - Document which scopes each integration requires so your team can replicate the setup consistently. 📋 Signal Genesys Integration Checklist If you are connecting Signal Genesys to Search Atlas via the External API, confirm all of the following before testing: - Your API key has the press-release scope enabled. - You are using the correct base URL and OAuth client credentials flow (not a legacy hardcoded token). - Environment variables in Signal Genesys are up to date with the current key and endpoint values. - You have tested the token/validate endpoint independently before making other API calls. 💬 Still Seeing the 403 Error? If you have followed all the steps above and the error persists, it is possible that the press-release scope needs to be enabled on your account at the platform level by our team. If you need further assistance, open the chat widget in the bottom-right corner of the platform and type human teammate to be connected with a member of our team.

🔌 Fix MCP Authentication Errors

🔍 What the error means The message “Authentication succeeded, action failed” indicates that ChatGPT authentication completed, but the requested Search Atlas MCP action did not. 🛠️ What to check 1. Retry the same action. Run the MCP action again and note whether the result changes. 2. Record the failing action. Identify the specific Search Atlas MCP action that fails. 3. Capture the exact error. Save the complete message shown by ChatGPT. ✅ Before contacting support Record the exact ChatGPT error, the MCP action you attempted, and the selected Search Atlas project. Avoid sharing passwords or access tokens. If you need further assistance, open the chat widget in the bottom-right corner of the platform and type human teammate to be instantly connected with a member of our team.

🔌 Fix ChatGPT MCP Tool Discovery

🔍 What this error means If ChatGPT shows “Authentication succeeded, action discovery failed” for https://mcp.searchatlas.com/mcp/, your sign-in was accepted, but ChatGPT could not retrieve the available Search Atlas tools. This usually indicates a connection, session, permission, or temporary service issue rather than an incorrect password. ⚙️ Check your Search Atlas access 1. Sign in to the Search Atlas account you want ChatGPT to use. 2. Confirm that the account can access the Search Atlas areas you need, such as Site Metrics or Local. 3. For Site Metrics, open Left sidebar → Site Metrics and verify that your projects and sites load. 4. For Local, open Left sidebar → Local and verify that your projects load. 5. If you belong to a team, confirm that your role includes access to the required projects and features. 🔄 Reconnect the MCP server 1. In ChatGPT, open the settings or connected apps area where MCP servers are managed. 2. Remove the existing Search Atlas MCP connection, if one is listed. 3. Add the server again using exactly https://mcp.searchatlas.com/mcp/. 4. Complete the Search Atlas sign-in and permission prompts in the same browser session. 5. Retry the connection and wait for ChatGPT to finish discovering the available actions. 🧹 Resolve browser and session issues - Sign out of Search Atlas, then sign in again before reconnecting. - Allow pop-ups, redirects, and cookies for Search Atlas and ChatGPT. - Try a private browser window or another supported browser. - Disable extensions that block scripts, redirects, or third-party authentication. - Ensure the MCP URL has no extra spaces, characters, or trailing path changes. 🧪 Test the connection After reconnecting, ask ChatGPT to list the available Search Atlas MCP tools. If discovery succeeds, ask it to perform a simple read-only request using an accessible site or project. If tools still do not appear, do not repeatedly authorize the same failed connection; continue with the checks below. 📋 Information to provide for investigation If the error continues, record the exact error message, the MCP URL used, the approximate time of the attempt, your Search Atlas workspace, and whether the issue affects all projects or only one. Screenshots of the ChatGPT connection result and any request or correlation ID can also help investigate the authenticated tool-discovery request. Never share your password or private access tokens. 💬 Get help If you need further assistance, open the chat widget in the bottom-right corner of the platform and type human teammate to be instantly connected with a member of our team.