--- title: "Contentstack MCP Troubleshooting Guides" description: "Fix common Contentstack MCP Server and MCP Profile Hub errors, from client setup and sign-in to permissions, profile imports, automations, and tool calls." url: "https://www.contentstack.com/docs/contentstack-mcp-troubleshooting/faqs" product: "Contentstack" doc_type: "guide" audience: - developers - admins version: "current" last_updated: "2026-10-28" --- # Contentstack MCP Troubleshooting Guides ## MCP Server Setup and Authentication ### "Unauthorized" errors on CMA, Analytics, or Launch tool calls **Applies to:** Contentstack MCP Server Tool calls in an OAuth group, for example CMA, Analytics, or Launch, fail with an Unauthorized error. **Root causes** * You have not run the OAuth flow on this machine. * The OAuth tokens that the server saved on this machine have expired. **Resolution** Run the command below, then complete the sign-in in the browser window it opens: `npx @contentstack/mcp --auth` **Additional Resource:** For more information on which groups use OAuth, refer to the [Authentication](/docs/developers/contentstack-mcp-server#authentication) section of the Contentstack MCP Server documentation. ### CDA tool calls return empty results or 401 errors **Applies to:** Contentstack MCP Server **Root causes** * CONTENTSTACK\_DELIVERY\_TOKEN is missing or incorrect. * The delivery token belongs to a different environment than the one you query. **Resolution** 1. Check the value of CONTENTSTACK\_DELIVERY\_TOKEN in the server configuration. 2. Confirm that the delivery token belongs to the environment you query. If it does not, create a delivery token for that environment and set it as CONTENTSTACK\_DELIVERY\_TOKEN. **Additional Resource:** For more information on where each credential comes from, refer to the [Where to find your credentials](/docs/developers/contentstack-mcp-server#where-to-find-your-credentials) section of the Contentstack MCP Server documentation. ### Contentstack MCP Server tools do not appear in your MCP client **Applies to:** Contentstack MCP Server **Root cause** The GROUPS value contains a typo or a space, so the server does not recognize the groups it names. **Resolution** Set GROUPS to a comma-separated list of group values with no spaces, as in the example below: `GROUPS=cma,cda` **Additional Resource:** For more information on the accepted group values, refer to the [GROUPS variable](/docs/developers/contentstack-mcp-server#the-groups-variable) section of the Contentstack MCP Server documentation. ### Launch tool calls fail with authentication errors **Applies to:** Contentstack MCP Server **Root cause** The server configuration does not set CONTENTSTACK\_ORGANIZATION\_UID. The Launch group needs the organization UID in addition to OAuth. **Resolution** 1. Copy the organization UID from your project's URL in the Launch dashboard, or from your organization settings. 2. Add it to the server configuration as CONTENTSTACK\_ORGANIZATION\_UID, or pass it with \--organization-uid. ### Lytics tool calls return 403 **Applies to:** Contentstack MCP Server **Root cause** The Lytics access token has expired, or it holds an incorrect value. The Lytics group does not use OAuth, so the server sends only the token that LYTICS\_ACCESS\_TOKEN holds. **Resolution** 1. Generate a new access token under **API Tokens** in your Lytics account settings. 2. Set LYTICS\_ACCESS\_TOKEN to the new token. ### get_job_data returns "200 Job active" for an Analytics job **Applies to:** Contentstack MCP Server **Root cause** The Analytics job is still processing. Every Analytics tool runs asynchronously: it returns a jobId, and get\_job\_data returns the results only after the job completes. **Resolution** Wait a few seconds, then call get\_job\_data again with the same jobId. ### npx asks for confirmation when the MCP client starts the server **Applies to:** Contentstack MCP Server **Root cause** The args array in the client configuration does not include the \-y flag, so npx waits for you to confirm the package installation. **Resolution** Add "-y" as the first argument after npx, as in the configuration below: `"command": "npx", "args": ["-y", "@contentstack/mcp"]` ### Requests reach the wrong data center, or return 404 or 401 **Applies to:** Contentstack MCP Server **Root cause** The configuration sets no region, and no OAuth session exists to supply one, so the server sends requests to the default region, NA. A configuration that uses only a delivery token or only a management token always lacks an OAuth session. **Resolution** Set CONTENTSTACK\_REGION, or pass \--region, with the code of your stack's data center. **Additional Resource:** For more information on the region codes, refer to the [Supported regions](/docs/developers/contentstack-mcp-server#supported-regions) section of the Contentstack MCP Server documentation. ### "Unknown region" error when the server starts **Applies to:** Contentstack MCP Server **Root cause** The value of \--region or CONTENTSTACK\_REGION contains a misspelling. The server returns this error when it does not recognize the region value. **Resolution** Use a supported region code or alias, for example EU or aws-eu. Aliases ignore case and separators, so eu and AWS\_EU also resolve to the EU region. **Additional Resource:** For more information on every code and alias, refer to the [Supported regions](/docs/developers/contentstack-mcp-server#supported-regions) section of the Contentstack MCP Server documentation. ### CMA tool calls fail with authentication errors when no OAuth session exists **Applies to:** Contentstack MCP Server **Root cause** The server has no OAuth session, and the configuration provides no management token. **Resolution** Use one of the two options below: * Run npx @contentstack/mcp --auth and complete the sign-in, so the server has an OAuth session. * Set CONTENTSTACK\_MANAGEMENT\_TOKEN and CONTENTSTACK\_REGION. A management token authenticates only the CMA and CMA Extended groups, and the region tells the server which data center to call. **Additional Resource:** For more information on the management token option, refer to the [Authenticating without OAuth](/docs/developers/contentstack-mcp-server#authenticating-without-oauth-management-token) section of the Contentstack MCP Server documentation. ## Profile Hub Client Setup ### The Add to Claude button has no effect **Applies to:** MCP Profile Hub, Claude Desktop tab **Root cause** Your Claude plan restricts custom connectors to organization admins. **Resolution** Use the **Claude Desktop Manual** installation tab instead, or ask a Claude organization admin to add the connector. **Additional Resource:** For more information on each installation tab, refer to the [Connect a client to MCP Profile Hub](/docs/developers/mcp-profile-hub-connect-a-client-to-profile-hub) documentation. ### Two browser tabs open during sign-in **Applies to:** MCP Profile Hub, Claude Desktop Manual tab **Root cause** Claude Desktop occasionally opens two browser tabs at once when you sign in to a server that you added through the manual configuration. **Resolution** 1. Complete the sign-in in the first tab and close the other. 2. If the profile's tools still do not appear, restart Claude Desktop and sign in again. ### The claude mcp add command fails **Applies to:** MCP Profile Hub, Claude Code tab **Root cause** The connector URL has no quotes around it, so the shell reads ? and & as shell syntax instead of as part of the URL. **Resolution** Keep the connector URL in quotes when you run claude mcp add. ### The server does not appear after you edit claude_desktop_config.json **Applies to:** MCP Profile Hub, Claude Desktop Manual tab **Root cause** Claude Desktop reads claude\_desktop\_config.json only when it launches. **Resolution** Restart Claude Desktop. ### mcp-remote fails to start, and Node.js is missing **Applies to:** MCP Profile Hub, clients that run the mcp-remote bridge **Root cause** The machine has no Node.js installation, so npx cannot run mcp-remote. **Resolution** Install Node.js, then confirm that npx -y mcp-remote runs. ### mcp-remote fails to start, and Node.js is present **Applies to:** MCP Profile Hub, clients that run the mcp-remote bridge **Root cause** A registry allowlist, an execution policy, or a proxy blocks npx from reaching the npm registry. **Resolution** Use one of the two options below: * Install mcp-remote globally from an approved registry, and configure the client to run the installed binary instead of npx. * Ask your IT team to allowlist the mcp-remote package. ## Profile Hub Connection and Sign-In ### The client shows the server but no tools **Applies to:** MCP Profile Hub **Root causes** * You did not finish the Open Authorization (OAuth) sign-in. * Contentstack disabled the profile. A disabled profile returns an empty tool list. **Resolution** 1. Start the sign-in again from your client, for example with /mcp in Claude Code, and complete the browser flow. 2. If the sign-in completes and the client still lists no tools, Contentstack [disabled the profile](/docs/developers/mcp-profile-hub-manage-profiles#enable-and-disable-a-profile). The app provides no control for this setting, so contact [Contentstack support](mailto:support@contentstack.com). ### No tools appear, and the connection reports an error **Applies to:** MCP Profile Hub **Root cause** The connector URL contains a malformed project UID. A malformed project UID fails the whole tool listing, not only the tools of the affected product. **Resolution** Correct the project UID in the connector URL. The [MCP URL parameters](/docs/developers/mcp-profile-hub-url-parameters#validation) documentation gives the accepted format for each parameter. ### The browser never opens for sign-in, and the URL looks wrong **Applies to:** MCP Profile Hub **Root cause** The connector URL in your client contains a typo. **Resolution** Compare the URL in your client with the one on the profile's **Installation** step, including profile\_id and org\_uid, and correct any difference. ### The browser never opens for sign-in, and the URL is correct **Applies to:** MCP Profile Hub **Root cause** The client cannot reach the discovery endpoint. **Resolution** 1. Confirm that the machine reaches the endpoint over HTTPS, for example by opening the connector URL in a browser. 2. Check for a corporate proxy, VPN, firewall, or TLS-inspecting middlebox that blocks the request. ### The client asks you to authorize repeatedly **Applies to:** MCP Profile Hub, clients that run the mcp-remote bridge **Root cause** Contentstack raised the pinned mcp-remote version, and the new version stores credentials in a new, empty directory. **Resolution** Sign in again. A [version change](/docs/developers/mcp-profile-hub-connect-a-client-to-profile-hub#why-contentstack-pins-the-mcp-remote-version) triggers this prompt and does not indicate a fault. ### Sign-in loops with no version change **Applies to:** MCP Profile Hub **Root cause** The client holds a stale cached token. **Resolution** Clear the client's cached MCP credentials and reconnect, with the step below for your client: * **For** **mcp-remote****:** delete the version-specific subdirectory under ~/.mcp-auth, then retry. * **In Claude Code:** run /mcp and sign in again. **Warning:** ~/.mcp-auth holds cached OAuth credentials for every MCP server you connect through mcp-remote, not only Contentstack. If you delete the whole directory, you sign out of all of them, and each one prompts for authorization again on next use. ## Profile Hub Authentication and Permissions ### authorization_required error with reason no_token or local_token_unavailable **Applies to:** MCP Profile Hub The client receives JSON-RPC error code \-32010 with the message authorization\_required, and the reason field holds no\_token or local\_token\_unavailable. **Root cause** You have not completed the OAuth sign-in for this profile, or the stored token expired. **Resolution** Reconnect and [sign in again](/docs/developers/mcp-profile-hub-connect-a-client-to-profile-hub#authentication-and-permissions). The error also includes an authorization\_url that you can open directly. ### authorization_required error with reason insufficient_scope **Applies to:** MCP Profile Hub The client receives JSON-RPC error code \-32010 with the message authorization\_required, and the reason field holds insufficient\_scope. The message below names the method and path that failed: `Permission denied for . The authorized token may lack a required OAuth scope, or your Contentstack role may not permit this operation. If scopes were recently changed, re-authorize from the Authorization page (add the needed scope to the curated list) and try again.` **Root causes** Contentstack returned 403 for one of the two reasons below: * The token lacks a required OAuth scope. * Your Contentstack role does not permit the operation. A profile never grants more access than your roles allow. **Resolution** 1. Reconnect and approve the requested scopes, after you add the needed scope to the curated list on the **Authorization** page. 2. If you already granted the scope, sign in to Contentstack as the same user and try the same action in the UI. If the action also fails in the UI, your role does not permit it. Use an account with the required role, or ask the profile owner to remove the tool from the profile. **Additional Resource:** For more information on what each role permits, refer to the [About Product Roles](/docs/administration/about-product-roles) and [About Stack Roles](/docs/headless-cms/about-stack-roles) documentation. ### authorization_required error with reason contentstack_unauthorized **Applies to:** MCP Profile Hub The client receives JSON-RPC error code \-32010 with the message authorization\_required, and the reason field holds contentstack\_unauthorized. **Root cause** Contentstack rejected the token, and the token refresh also failed. **Resolution** Reconnect and [sign in again](/docs/developers/mcp-profile-hub-connect-a-client-to-profile-hub#authentication-and-permissions). ### Profile scope mismatch error **Applies to:** MCP Profile Hub **Root cause** The client requested a profile other than the one the connector URL specifies. **Resolution** Use the [connector URL](/docs/developers/mcp-profile-hub-url-parameters#a-connector-url-is-scoped-to-one-profile) of the profile you want. The profile\_id in the URL determines which profile the client can use. ## Profile Hub Configuration ### "No stack selected for this organization" error **Applies to:** MCP Profile Hub **Root cause** Neither the profile, the connector URL, nor the tool arguments specify a stack. **Resolution** Select a stack in the profile's **Configuration** step, or pass stack\_api\_key in the connector URL. ### "No Personalize project selected for this profile" error **Applies to:** MCP Profile Hub **Root cause** The profile includes Personalize tools but no Personalize project. **Resolution** Select a Personalize project in the profile's **Configuration** step, or add personalize\_project\_uid to the connector URL. ### Invalid "launch_project_uid" in the MCP endpoint URL **Applies to:** MCP Profile Hub **Root cause** The project UID in the connector URL is not 1 to 64 characters of letters, digits, hyphens, or underscores. **Resolution** Correct the [parameter](/docs/developers/mcp-profile-hub-url-parameters#validation) in the connector URL so that it matches that format. ### "Cannot find that stack" error **Applies to:** MCP Profile Hub **Root causes** * The configured stack API key is wrong. * The stack belongs to a different Contentstack region than the one your sign-in resolved. **Resolution** 1. Confirm that the configured stack API key is correct for your account. 2. Confirm that you signed in to the organization that owns the stack. Contentstack derives the regional endpoints from the organization you sign in with, so it cannot reach a stack in another region during that session. The [region codes](/docs/developers/contentstack-mcp-server#supported-regions) name each region, and the cma\_host [sign-in parameter](/docs/developers/mcp-profile-hub-url-parameters#sign-in-parameters) sets the region that the connector URL uses. ### Saving a profile fails because the plan does not include a catalog **Applies to:** MCP Profile Hub The app shows the message below, where names the excluded catalogs: `This organization's plan does not include .` **Root cause** The profile contains tools from a catalog that your organization's plan excludes. **Resolution** Remove the tools that belong to the excluded [catalog](/docs/developers/mcp-profile-hub-profiles-and-catalogs#plan-gated-catalogs), then save the profile again. ## Profile Hub Import ### Profile import fails because the file is too large **Applies to:** MCP Profile Hub The app shows the heading Couldn't import profile, then the message below: `That file is too large to be a profile export.` **Root cause** The file exceeds 1 MiB. **Resolution** Confirm that you picked a profile export, not another JSON file. ### Profile import fails because the file is not valid JSON **Applies to:** MCP Profile Hub The app shows the heading Couldn't import profile, then the message below: `That file isn't valid JSON.` **Root cause** The file does not parse as JSON. **Resolution** Export the profile again instead of editing the file by hand. ### Profile import fails because the JSON is not an exported profile **Applies to:** MCP Profile Hub The app shows the heading Couldn't import profile, then the message below: `That JSON isn't an exported profile. Pick a file exported from MCP Profile Hub.` **Root cause** The file holds valid JSON, but MCP Profile Hub did not export it. **Resolution** Export the profile from the source organization, then import that file. ### Profile import fails because a newer version of MCP Profile Hub exported the file **Applies to:** MCP Profile Hub The app shows the heading Couldn't import profile, then the message below: `That file was exported by a newer version of MCP Profile Hub (format v2). Update, then import it.` **Root cause** The file uses a newer export format than your organization's version of MCP Profile Hub reads. **Resolution** Contentstack hosts and updates MCP Profile Hub centrally, so you cannot apply the update that the message requests. Export the profile again from a source organization on your version, or import the file after Contentstack updates MCP Profile Hub for your organization. ### Profile import fails because the profile has more than 200 tools **Applies to:** MCP Profile Hub The app shows the heading Couldn't import profile, then the message below: `That profile has more than 200 tools, which is the maximum a profile can hold.` **Root cause** The export exceeds the limit of 200 tools per profile. **Resolution** Split the profile in the source organization, then export each part. ### Profile import fails because a field is missing or malformed **Applies to:** MCP Profile Hub The app shows the heading Couldn't import profile, then the message below: `That profile is missing or malformed at "profile.name".` **Root cause** A required field is absent, or it holds the wrong type of value. The message names the field. **Resolution** Export the profile again instead of editing the file by hand. ### Profile import fails because the name matches a system profile **Applies to:** MCP Profile Hub The app shows the heading Couldn't import profile, then the message below: `"CMS" is a system profile. Choose a different name.` **Root cause** Contentstack derives the profile\_id from the profile name, and that ID matches a system profile. Contentstack renames only system-profile exports, and this file is not one. **Resolution** Rename the profile in the file, or export it again from the source organization. ### Profile import fails because the profile ID already exists **Applies to:** MCP Profile Hub The app shows the heading Couldn't import profile, then the message below: `A profile with this profile_id already exists` **Root cause** You already have a profile with that name. **Resolution** Rename the profile before you import it. ### Profile import fails because you reached your profile limit **Applies to:** MCP Profile Hub The app shows the heading Couldn't import profile, then the message below: `Profile limit of 50 reached; delete an existing profile first` **Root cause** You already hold the maximum of 50 profiles. **Resolution** Delete a profile you no longer use, then import the file again. ### Profile import fails because the organization reached its profile limit **Applies to:** MCP Profile Hub The app shows the heading Couldn't import profile, then the message below: `Organization profile limit of 500 reached; ask an administrator to remove unused profiles` **Root cause** Your organization already holds the maximum of 500 profiles. **Resolution** Ask an organization admin to remove unused profiles, then import the file again. ### Profile import fails because the plan does not include a catalog **Applies to:** MCP Profile Hub The app shows the heading Couldn't import profile, then the message below: `This organization's plan does not include launch. Remove the tools from that catalog and save again.` **Root cause** The file contains tools from a catalog that your organization's plan excludes. **Resolution** Remove those tools from the file, or import it into an organization whose plan includes the catalog. The [Profiles and catalogs](/docs/developers/mcp-profile-hub-profiles-and-catalogs#plan-gated-catalogs) documentation lists the plan-gated catalogs. ## Profile Hub Automations and Agents ### An automation call fails with a secure HTTP trigger error **Applies to:** MCP Profile Hub The error message starts with the text below: `Automation "" uses a secure HTTP trigger, which is not supported yet. Disable Secure HTTP Trigger on the automation, or pick a different automation.` **Root cause** Secure HTTP Trigger is on for that automation. Contentstack cannot detect Secure HTTP Trigger on automations as it does on agents, so a secured automation stays visible in the tool browser, and you can add it to a profile. The call then fails when the agent runs the automation. **Resolution** Turn off Secure HTTP Trigger on the automation in Contentstack Automate, or pick a different automation. ### An automation call fails because the automation is not active **Applies to:** MCP Profile Hub The error message contains is not activated in Contentstack Automate, so it did not run. **Root cause** The automation is still a draft, or someone paused it. **Resolution** Open the automation in Automate and activate it. The [What qualifies](/docs/developers/mcp-profile-hub-automations-and-agents#what-qualifies) section lists every condition an automation must meet to work as a tool. ### An automation call times out **Applies to:** MCP Profile Hub The error message contains did not respond within ms. **Root cause** The automation ran longer than the profile's timeout. **Resolution** Raise timeout on the [connector URL](/docs/developers/mcp-profile-hub-url-parameters). Contentstack caps it at 120000 ms. ### An agent run times out before it finishes **Applies to:** MCP Profile Hub The error message reads as below, where is the state of the run: `The agent was still when the tool timed out.` **Root cause** The agent run exceeded the profile's timeout, which Contentstack caps at 120000 ms. **Resolution** Raise timeout on the [connector URL](/docs/developers/mcp-profile-hub-url-parameters), up to 120000 ms. If the run needs more than 120000 ms, look up the reported execution ID in Agent OS to see the result. ### An automation is missing from the tool browser **Applies to:** MCP Profile Hub **Root causes** * The automation's first step is not an HTTP trigger. * The automation is not active. * You fixed the automation less than five minutes ago. **Resolution** Fix the automation in Automate, then wait up to five minutes before you reopen the tool browser. Contentstack caches the discovered list on the server for five minutes, so if you reopen the tool browser sooner, it shows the same list. ### An agent is missing from the tool browser **Applies to:** MCP Profile Hub **Root causes** * The agent is unpublished or inactive. * The agent has no HTTP trigger. * The agent uses a secure trigger, which Profile Hub does not support yet. * You fixed the agent less than five minutes ago. **Resolution** 1. In Agent OS, publish and activate the agent, add an HTTP trigger, and turn off Secure HTTP Trigger. 2. Wait up to five minutes before you reopen the tool browser. ## Profile Hub Tool Availability and Selection ### The agent calls the wrong tool, or passes invalid arguments **Applies to:** MCP Profile Hub A tool call fails, or runs a different operation than the one you asked for, even though the profile and the tool work. **Root cause** The model selects a tool that does not match the request, or builds arguments that do not match the tool's input schema, for example by omitting a required field on publish. Some MCP clients retry the call with corrected arguments. The MCP client and the model control this retry behavior, not the profile or the tool. **Resolution** Retry with a different model, or state the operation and its required values in your prompt. ### "Tool not found" error **Applies to:** MCP Profile Hub **Root causes** * Someone removed the tool from the profile's **Tool selection** step. * The client still holds a tool list that it fetched before the profile changed. Contentstack does not notify a connected client that the list changed. **Resolution** 1. List the tools again in the client, by reconnecting or by running the client's server-refresh command. 2. If the tool is still absent, confirm that the profile's **Tool selection** step still lists it. ### A catalog is missing from the tool browser **Applies to:** MCP Profile Hub **Root cause** Your organization's plan does not include that product, so the tool browser does not display its tab or its tools. **Resolution** 1. Ask your organization's Contentstack admin to confirm the plan. 2. Contact [Contentstack support](mailto:support@contentstack.com) to add the product. Until then, build the profile from the catalogs your plan includes. ### "Saved tools could not be loaded" message on a profile **Applies to:** MCP Profile Hub The profile shows the message below, where is the number of affected tools: ` saved tools could not be loaded` **Root causes** * The tool manifests failed to load while the page opened. * A catalog key changed after the profile saved those tools. **Resolution** Reload the page to request the manifests again. Contentstack keeps the tools on the profile, and the tools stay callable.