Contentstack MCP Troubleshooting Guides

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 section of the Contentstack MCP Server documentation.

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 section of the Contentstack MCP Server documentation.

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 section of the Contentstack MCP Server documentation.

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.

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.

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.

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"]

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 section of the Contentstack MCP Server documentation.

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 section of the Contentstack MCP Server documentation.

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 section of the Contentstack MCP Server documentation.

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 documentation.

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.

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.

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.

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.

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.

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. The app provides no control for this setting, so contact Contentstack support.

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 documentation gives the accepted format for each parameter.

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.

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.

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 triggers this prompt and does not indicate a fault.

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.

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. The error also includes an authorization_url that you can open directly.

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 <METHOD> <PATH>. 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 and About Stack Roles documentation.

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.

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 of the profile you want. The profile_id in the URL determines which profile the client can use.

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.

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.

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 in the connector URL so that it matches that format.

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 name each region, and the cma_host sign-in parameter sets the region that the connector URL uses.

Applies to: MCP Profile Hub

The app shows the message below, where <CATALOGS> names the excluded catalogs:

This organization's plan does not include <CATALOGS>.

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, then save the profile again.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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 documentation lists the plan-gated catalogs.

Applies to: MCP Profile Hub

The error message starts with the text below:

Automation "<AUTOMATION_ID>" 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.

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 section lists every condition an automation must meet to work as a tool.

Applies to: MCP Profile Hub

The error message contains did not respond within <MS>ms.

Root cause

The automation ran longer than the profile's timeout.

Resolution

Raise timeout on the connector URL. Contentstack caps it at 120000 ms.

Applies to: MCP Profile Hub

The error message reads as below, where <STATUS> is the state of the run:

The agent was still <STATUS> 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, 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.

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.

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.

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.

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.

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 to add the product. Until then, build the profile from the catalogs your plan includes.

Applies to: MCP Profile Hub

The profile shows the message below, where <N> is the number of affected tools:

<N> 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.