Home 🔌 Integrations & API

🔌 Integrations & API

Camilo Aponte
By Camilo Aponte
• 7 articles

🛠️ Fix ChatGPT MCP Authentication Succeeded Action Failed

🔍 What This Error Means When you connect ChatGPT to Search Atlas through MCP (Model Context Protocol), ChatGPT first asks you to sign in and approve access. You may then see a message like Authentication succeeded, but the action failed. This means your sign-in was approved. The failure is the next step, when ChatGPT tries to load the Search Atlas connection and its actions. It does not mean a data request already ran. The usual fix is to disconnect Search Atlas and add it again. If it still fails, check that the signed-in account has an active Search Atlas subscription. 🧩 Common Causes - Stale or incomplete connection: The sign-in finished, but ChatGPT did not save the access token correctly. - Signed in to the wrong account: You approved access with a Search Atlas account that does not have the project or data you are asking about. - Missing subscription: the account you approved is not an active Search Atlas subscriber. Sign-in can still succeed, but every later action is rejected until that account has an active subscription. - Connector not selected in this chat: ChatGPT may have a working Search Atlas connection that is not selected as a tool for the current conversation. Check ChatGPT's tools or connectors menu and turn Search Atlas on for that chat. - Browser or session issues: Pop-up blockers, old cookies, or being signed in to several accounts can interrupt the approval step. - Workspace restrictions: If you use a ChatGPT Team or Enterprise workspace, an admin may limit which connectors or actions are allowed. - Temporary service errors: A short timeout on either side can cause a one-time failure. ✅ Quick Fixes to Try First 1. Retry the request. Start a new chat and ask for something simple, such as listing your projects. This rules out a one-time timeout. 2. Check the connector is selected. In ChatGPT, open the tools or connectors menu for the chat and make sure Search Atlas is selected for that conversation. That control belongs to ChatGPT, not Search Atlas. 3. Confirm your account. Open Search Atlas in another tab and check that you are signed in to the account that owns the projects you want to use. 4. Refresh the page. Reload ChatGPT and try the action again. 🔄 Reconnect the Search Atlas Connection If the quick fixes do not help, a clean reconnect solves most cases. 1. In ChatGPT, open Settings, then Apps or Connectors, where your connected apps are listed. 2. Find the Search Atlas connection and choose Disconnect or Remove. 3. Close the settings and refresh ChatGPT. 4. Sign out of Search Atlas, then sign back in with the correct account. 5. Return to ChatGPT, add the Search Atlas connection again, and approve every permission request. 6. After you approve access, start a new chat and test with a simple request, such as asking ChatGPT to list your projects. If ChatGPT still says the action failed, remove the connection and add https://mcp.searchatlas.com/mcp/lite/ again, one try at a time. Make sure you finish the approval screen and do not close the pop-up early. Closing it too soon is a common reason the connection looks successful but cannot run actions. 🌐 Check Your Browser - Allow pop-ups for ChatGPT and Search Atlas, since the sign-in often opens in a new window. - Try a private or incognito window with extensions turned off. - Clear cookies and cache for both sites, then try again. - Try a different browser to see if the issue is specific to one. 👥 Check Your Workspace and Plan - If you use a shared ChatGPT workspace, ask your admin whether custom connectors and MCP actions are allowed for your role. - Confirm your Search Atlas plan includes the feature you are trying to use through ChatGPT. - Make sure your Search Atlas user role has access to the project or data you are asking about. 💡 Tips for Better Results - Start with a simple request to confirm the connection works, then move to more detailed tasks. - Name the project or site you want ChatGPT to use so it does not guess. - If a large request fails, break it into smaller steps. - Only keep one Search Atlas connection active to avoid conflicts between old and new sessions. 📝 What to Share If the Problem Continues If the error keeps appearing after you reconnect, gather these details so our team can help you faster: - The exact error message shown in ChatGPT - The approximate time the error happened - The email of the Search Atlas account you signed in with - The request you typed when the error appeared - Whether you use a personal or shared ChatGPT workspace - The browser you are using 🙋 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 instantly connected with a member of our team.

Last updated on Oct 29, 2026

🛠️ Fix Shopify Token Exchange 404 Store Unavailable Error

🔍 What This Error Means When you connect your Shopify store to Search Atlas using a custom app, you may see this message: Shopify token exchange failed: 404 Store unavailable. Search Atlas requested an access token from Shopify, but Shopify returned a 404 response with “Store unavailable.” Check the store’s myshopify.com address, whether the store is accessible, and whether the correct app is installed on that store. Read the full error details: an application_cannot_be_found message specifically calls for checking the Client ID and app installation. If these checks do not resolve the error, contact support. Source: ucmsi/integrations/shopify/v1/api.py:146–164,201–223. 🧭 Common Causes - The store address was entered incorrectly, with a typo or extra characters. - A custom domain (like www.yourstore.com) was used instead of the Shopify domain (yourstore.myshopify.com). - The store was renamed, so the old myshopify.com address no longer works. - The store is paused, frozen, closed, or has an unpaid plan or an expired trial. - The custom app was created in a different store than the one you are connecting. - The app was created but not yet installed on the store. - The Client ID or Client Secret was copied incorrectly or belongs to another app. ✅ Step-by-Step Fix Work through these steps in order. Many customers resolve the error by step 2 or 3. 1. Confirm your store is active. Log in to your Shopify admin and check that the store opens normally. If you see a notice about a paused, frozen, or expired plan, resolve it in Shopify first. 2. Find your exact Shopify domain. In your Shopify admin, look at the browser address bar. It should look like admin.shopify.com/store/your-store-name. Your store handle is the part after /store/. Your Shopify domain is that handle followed by .myshopify.com. 3. Use your store’s Shopify address, such as your-store-name.myshopify.com, rather than its custom storefront domain. You can also enter just your-store-name. The connector removes http:// or https:// and any trailing slash or page path automatically. Do not add www. Source: ucmsi/integrations/shopify/v1/api.py:98–116. 4. Check for typos and spaces. Retype the address instead of pasting if you suspect hidden spaces. Letters, numbers, and hyphens only. 5. Verify the app is installed. In Shopify, open your custom app and make sure it is installed on the store you are connecting. If it shows as not installed, install it and approve the requested permissions. 6. Check you are connecting the right store. If you manage several stores, confirm that the app matching your Client ID is installed on the same store whose Shopify address you entered in Search Atlas. Creating the app alone is not enough; complete its installation before reconnecting. Source: ucmsi/integrations/shopify/v1/api.py:146–150. 7. Re-copy your credentials. Copy the Client ID and Client Secret from the app settings in Shopify again. Paste them carefully without extra spaces. If you recently regenerated the secret, use the newest one. 8. Try the connection again. Return to Search Atlas and run the connection once more with the corrected details. 🏪 If You Recently Renamed Your Store Shopify lets you change your store name and your myshopify.com address. If the address changed, the old one may stop working for app connections. Open your Shopify admin, check the current address in the browser bar, and use that one in Search Atlas. If your custom app was set up before the change, check that it is still installed and that its credentials are current. 🔐 Check App Permissions Make sure the app has the Admin API permissions required for the features you use. For the Shopify CMS connector’s page and blog publishing features, grant read_content and write_content. If you change permissions, complete any installation or approval steps Shopify requests so the updated permissions are granted, then reconnect. Check additional permissions separately for other features. Sources: ucmsi/integrations/shopify/v1/api.py:36–40,161–164; ucmsi/app/cms/fixtures/cms\_catalog.json:1184–1186. 💡 Quick Tips to Avoid This Error - Always use the myshopify.com address when connecting. - Copy the address from your Shopify admin instead of typing it from memory. - Keep your Shopify plan active and your store accessible. - Update your connection details in Search Atlas if you rename the store or regenerate app credentials. - Create the custom app in the same store you plan to connect. ❓ Frequently Asked Questions Is my store down if I see this error? Not necessarily. The error only tells us Shopify could not find an available store at the address used. Your storefront may still be live, especially if the address entered was not the correct Shopify domain. Can I use my custom domain to connect? No. Use your myshopify.com address. Custom domains are for your shoppers and are not used for this connection. Will I lose any data if I reconnect? No. Reconnecting only refreshes the link between Search Atlas and Shopify. It does not delete products, pages, or content from your store. I corrected everything and still see the error. What now? Reach out to our team using the steps below so we can look at your connection directly. 💬 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 instantly connected with a member of our team. To help us resolve it faster, have the following ready: - Your myshopify.com store address. - The exact error message you see. - The approximate time you tried to connect. - Confirmation that the custom app is installed on the store. Never share your Client Secret in the chat. We will never ask for it.

Last updated on Oct 29, 2026

🔑 Search Atlas API-Key Authentication Guide

🔑 Understand API-key authentication Search Atlas API requests require a valid API key. The key identifies your account and authorizes access to the API features available to you. If the API documentation index does not show an authentication entry, this does not mean authentication is unavailable. Open the endpoint documentation and follow its API-key requirements. 🛠️ Add your API key to a request 1. Open the Search Atlas platform and locate your API access or developer settings. 2. Copy an active API key. Create a new key if you do not have one. 3. Send the key in the authentication header required by the API documentation, such as the documented API-key header. 4. Keep the key private and store it in an environment variable or secure secrets manager. Do not place an API key in a public code repository, browser-side script, URL, screenshot, or support message. Never include it when sharing logs. 🔍 Check authentication errors - 401 Unauthorized: Confirm that the key is included, copied completely, active, and sent using the required header name. - 403 Forbidden: The key may be valid but lack permission for the requested resource. - Documentation mismatch: Check that you are using the current API version and the authentication instructions for that endpoint. - Unexpected failures: Remove extra spaces or quotation marks and confirm that your request is sent to the correct Search Atlas API host. 🔒 Protect and replace a key Use separate keys for development and production when possible. If a key is exposed, revoke it immediately, create a replacement, and update the systems that use it. 💬 Get help with authentication When contacting support, share the endpoint, HTTP status code, request timestamp, and a redacted request example. Do not share your API key. 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.

Last updated on Oct 29, 2026

🔌 Search Atlas MCP URL for Claude

🔍 What the MCP server URL is The MCP server URL is the web address Claude uses to connect to Search Atlas through the Model Context Protocol. It is not a website you open in a browser. Claude sends requests to that address so it can use Search Atlas data and tools from your account. If Claude has shown a connection warning for the past day or two, it usually means the connector is missing this URL, the URL was copied with extra characters, or the saved connector needs to be added again. 📋 Where to copy your URL Search Atlas shows the correct MCP server URL inside your account. Do not type a guessed address or reuse a link from an old chat, because a wrong URL will keep failing in Claude. 1. Sign in to Search Atlas. 2. Open your account or workspace settings and look for Integrations, MCP, or Claude. 3. Find the field labeled MCP server URL, or a similar label such as server URL or connector URL. 4. Select Copy so the full address is copied exactly, including https:// and with no spaces before or after it. If you do not see an MCP section, your plan or role may not include connector access. A workspace owner can confirm your permissions. ⚙️ How to add the URL in Claude 1. Open Claude and go to Settings, then Connectors (some accounts show this under Integrations). 2. Choose Add custom connector or edit the existing Search Atlas connector. 3. Paste the URL you copied from Search Atlas into the server URL field. 4. Save the connector and start a new chat so Claude reloads the connection. 5. If Claude asks you to approve the connector, accept it while you are signed in to the correct Search Atlas account. 🛠️ If Claude still shows an error - Remove the old Search Atlas connector, then add it again with a fresh copy of the URL. - Check for a missing https://, a line break, or a space at the start or end of the address. - Confirm you are using the URL from the same Search Atlas workspace you want Claude to access. - Sign out of Claude, sign back in, and test in a new conversation. - Try again after a few minutes if the warning started suddenly for many users. Temporary connector issues clear once the service is reachable again. The URL itself rarely changes. Re-copying it from Search Atlas is safer than editing it by hand. 💬 Still stuck 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.

Last updated on Oct 29, 2026

📊 Keyword Rank Tracker API for NinjaCat

📌 What this article covers NinjaCat and other reporting tools can pull Keyword Rank Tracker data on a schedule. That data is separate from local heatmap rankings. This article explains which data set to use, how to authenticate unattended pulls with an API key, and which filters return tracked keywords and historical daily positions. 🔍 Regular ranks versus local heatmaps Search Atlas stores these as two different products. Do not mix their endpoints if you want standard keyword positions in NinjaCat. - Keyword Rank Tracker returns the keywords you track for a site or project, plus position history by day (and related fields such as URL, search engine, device, and location when those are set on the keyword). - Local heatmap / geo-grid rankings return map-pack style points around a business location. Those series are not a substitute for regular rank history. If a report suddenly shows grid coordinates, many nearby pins, or local pack positions instead of one rank per tracked keyword per day, the integration is calling a heatmap endpoint. Switch it to the Keyword Rank Tracker endpoints in the in-platform API reference. 🔑 Authenticate unattended daily pulls Server-to-server jobs, including NinjaCat scheduled imports, should authenticate with an API key. Send it on every request as the header X-API-Key. Do not rely on a browser login session for daily pulls. 1. In Search Atlas, open your account or project API settings and create or copy an API key that can read rank data. 2. Store the key in NinjaCat (or your scheduler) as a secret. Do not paste it into shared sheets or public dashboards. 3. On each request, set the header X-API-Key to that key. Requests without a valid key are rejected. 4. Use HTTPS only. Rotate the key in Search Atlas if it is exposed, then update NinjaCat. The same header works for both Keyword Rank Tracker and heatmap calls. The header does not choose the data set. The endpoint path does. ⚙️ Endpoints and parameters to use Exact paths and field names are listed in the API reference inside the platform and can change. Use the reference labeled for Keyword Rank Tracker, not Local Heatmap or Geo Grid. Typical read flow for a daily NinjaCat import: 1. List tracked keywords for the site or project. Pass the site or project identifier your account uses. Optional filters often include search engine, device, location, tag, and keyword text. The response is the current tracking list (keyword id, keyword, target URL, and tracking settings). 2. Request historical positions for those keywords. Pass the same site or project id, one or more keyword ids from step 1, and a date range (start date and end date) for the days you want. For a daily job, request yesterday through today, or a short rolling window, so you do not re-download the full history every run. 3. Page through results when the reference shows limit, offset, page, or cursor parameters. Stop when a page is empty or the cursor is absent. A useful daily row usually includes keyword id, keyword text, date, position (or a null/not-ranking value), ranking URL, device, and location or country. Map those columns in NinjaCat. Ignore heatmap-only fields such as grid point, latitude and longitude pin, or distance from the business centroid. 📅 How to shape the daily pull - Run after Search Atlas has refreshed ranks for that day. Pulling too early can omit the latest positions. - Keep a stable keyword id in NinjaCat so history stays attached if the keyword text is edited. - Request only the date window you still need. Full history is for backfill, not every night. - Treat a missing position as not ranked for that day. Do not copy the previous day’s rank forward unless your report design says to. - If the keyword list and the history call disagree, refresh the keyword list first, then pull positions for the new ids. 🛠️ If the numbers look wrong - Confirm the path in the API reference is Keyword Rank Tracker, not a local heatmap route. - Confirm X-API-Key belongs to the account that owns the project. - Match site or project id, device, and location to the tracker view you compare in the UI. - Check the date range and time zone. A one-day shift is usually a date filter, not a different endpoint. - Compare one keyword for one date in the product UI before remapping the whole NinjaCat model. 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.

Last updated on Oct 29, 2026

🔍 Site Audit v2 Standalone API Contracts

📌 What a standalone audit is Site Audit v2 can run against a domain as a standalone audit. You identify that run by its audit_id, such as 101009. Reading status, page count, effective settings, or issues for that ID does not create or require a permanent project. Use only the routes published for your workspace on sa.searchatlas.com. Route names can differ by API version, so do not guess a path from an example ID. If your API reference is not visible in the platform, confirm the current contract in live chat before you automate calls. 📡 What you can read for one audit For a specific audit_id, a read request should return three kinds of information: - Status shows whether the audit is queued, running, complete, or failed. - Page count shows how many URLs were discovered or crawled for that run. - Issue payload lists URL-level findings for the completed or partially completed run. Use a GET read for an existing audit_id. A GET does not start a new crawl and does not change crawl settings. Call the status read while the audit is in progress, then call the issues read when status shows the run is ready. If issues are paginated, request each page until the payload indicates there are no further results. ⚙️ Settings and crawl budget Effective settings belong to the audit or domain configuration returned with that audit. Read them from the settings response rather than assuming a default. A value such as crawl_budget: 25 is enforced only when that audit’s effective settings say so. It is not a universal rule for every new domain. Compare the requested budget with the effective budget in the response before you rely on a page count. On a new domain, the platform applies the settings saved for that standalone audit. If no custom budget was saved, use the effective value returned by the API. Do not treat an example budget from another audit as the limit for yours. 🔄 Fresh results without changing settings To refresh an existing domain, request a new run with the same saved settings. Do not send a settings update in that request. A read-only GET never refreshes crawl data. The rerun action should keep the current budget, scope, and other options, then issue a new audit_id or run identifier for the fresh results. 1. GET the current status and effective settings for the existing audit_id. 2. Confirm the budget and scope you want to keep. 3. Request a fresh run without including changed settings. 4. Store the new audit_id and poll its status. 5. GET the page count and URL-level issues only after the new run is ready. Keep the previous audit_id if you still need the older issue payload. A fresh run does not erase a completed audit unless you explicitly delete it. ✅ Practical checks - Call GET only when you are reading status, page count, effective settings, or issues. - Pass the exact audit_id. An unknown ID should return a not-found response, not a new project. - Treat empty issues on a still-running audit as incomplete data, not as a clean site. - Use the effective settings in the response as the source of truth for crawl budget. - Request a rerun, not a settings write, when you want fresh results with the same configuration. 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.

Last updated on Oct 29, 2026

🚀 Connect a Vercel Site with Search Atlas

✅ Yes, Search Atlas works with Vercel Search Atlas can optimize a site hosted on Vercel. There is no separate Vercel app to install. You add your live website in Search Atlas, place the Search Atlas script in your site code, and deploy that change through Vercel. After the script loads on your production site, Search Atlas can audit the site and support ongoing SEO work. Use the domain your visitors see, usually your custom domain such as www.example.com. Do not connect only a temporary preview URL. Preview links change and are not the version search engines should rank. 📋 Before you start - You can edit the site code and deploy it on Vercel. - You know which domain is the live production site. - The site is publicly reachable, not blocked by a login or maintenance page. - You have a Search Atlas project ready for that domain. 🛠️ Add the site and install the script 1. In Search Atlas, add the website with the full production address, including https://. 2. Open the installation instructions for that project and copy the Search Atlas script. 3. Paste the script into the global layout so it loads on every public page, not on a single page only. 4. For a Next.js App Router site, add it in the root app/layout file. For the Pages Router, add it in _app or _document so it appears in the page head. For another framework, use the shared HTML head or layout. 5. Save the file, commit the change, and deploy it to your Vercel production environment. 6. Open the live site, refresh, and confirm the script is present in the page source. Then return to Search Atlas and check that the installation is detected. If your framework docs show a dedicated script component, use that method so the tag is included correctly in the head. Do not place the script only inside a blog post, a footer widget, or a draft page. 🌐 Custom domains and Vercel addresses Connect the same hostname you want to rank. If both example.com and www.example.com work, pick the one that is your main address and redirect the other to it. A vercel.app address is fine only when that address is the real public site. Production, not a preview deployment, must contain the script. 🔍 Confirm optimization is active - Visit several key pages on the production domain and confirm each one includes the script. - In Search Atlas, confirm the site shows as connected or the script shows as detected. - Run or review your site audit after the new deployment is live. - If the platform provides a sitemap or indexing check, confirm your public sitemap URL loads, often /sitemap.xml. DNS and deployment updates can take a few minutes. Check the production deployment in Vercel before testing again. 🧰 Fix common connection issues - Script missing on the live site: The change may be on a preview branch only. Deploy it to production. - Wrong domain connected: Remove the preview or non-canonical hostname and add the main domain. - Script blocked: A content security policy, cookie banner, or tag manager may stop the script. Allow the Search Atlas script in your site settings, then redeploy. - Cached old page: Hard refresh the page and confirm Vercel finished the latest production build. - Pages behind a login: Search Atlas can only read pages that visitors and crawlers can open. 💬 Need help connecting the site 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.

Last updated on Oct 29, 2026