Norce Backend MCP Servers — Troubleshooting and FAQ

This page covers common problems when connecting to and using the Norce Backend MCP Servers, along with frequently asked questions. For setup instructions, see Using the Norce Backend MCP Servers.

Connection and authentication

I get a 401 Unauthorized error

The most common cause is a credential problem. Check each of the following in order:

1. Verify ClientId and ClientSecret — confirm the values in your env block match the OAuth2 client credentials exactly. Credentials are case-sensitive.
2. Check that MCP access is activated — creating an OAuth2 client is not sufficient on its own. You must also activate MCP access for that client ID in Norce Admin under Settings > Users > OAUTH. If MCP access is not toggled on, requests will be rejected even if the credentials are otherwise valid.
3. Check that the client has the required API access rights — the Backend MCP Servers call Norce APIs on your behalf. If your OAuth2 client does not have access to the Management API, Connect API, Query API, or Commerce Services APIs, those calls will fail with a 401. Grant access to all of these APIs to ensure full coverage.
4. Confirm the credentials target the correct environment — if you have separate credentials for stage and production, make sure the credentials in your configuration match the environment in the URL.

tools/list returns no tools

This usually means the client never completed a successful connection to the server.

• Check the server URL — confirm the customer slug in the URL is correct and that the environment matches (stage vs production).
• Check MCP access activation — as above, MCP access must be explicitly enabled for the OAuth2 client. A rejected connection can surface in some clients as an empty tools list rather than a visible error.
• Check the client's MCP logs — most clients log the underlying connection error even when the UI only shows a missing or empty server.

Note that AccountId does not affect the tools list — the tool catalog is the same for every connection. A missing or invalid AccountId shows up later, as an error when a write tool is called.

If the tools list returns tools for one server but not another, the issue is most likely specific to that server's URL or the credentials used for it.

mcp-remote fails on Windows with 'C:\Program' is not recognized

This error only affects setups that launch the bridge through npx. It occurs when Node.js is installed in C:\Program Files\nodejs (the default Windows location) — Claude Desktop resolves npx to its full path and passes it unquoted to cmd.exe, and the space in Program Files causes cmd.exe to misread the command.

The recommended fix is to switch to the installed bridge — npm i -g mcp-remote and "command": "mcp-remote" — which is the primary setup in the Claude Desktop guide and is not affected by this issue.

If you want to stay on npx, replace "command": "npx" in your config with the full path to npx.cmd in your npm global directory, which typically has no spaces:

"command": "C:\\Users\\YOUR-USERNAME\\AppData\\Roaming\\npm\\npx.cmd"

Replace YOUR-USERNAME with your Windows username. The rest of the configuration stays the same. Fully quit and reopen Claude Desktop after saving.

mcp-remote is not found or fails to start

• Run mcp-remote --version in your terminal to check whether the bridge is installed. If the command is not found, install it with npm i -g mcp-remote (requires Node.js), then open a new terminal and check again.
• If you are behind a corporate proxy, add the proxy settings to the env block of your MCP configuration:
  "env": {
    "HTTP_PROXY": "http://proxy.example.com:8080",
    "HTTPS_PROXY": "http://proxy.example.com:8080"
  }

• After changing your MCP configuration, restart your AI client completely. Most clients do not reload configuration without a full restart.

The AI client does not pick up my configuration changes

MCP server configurations are read at startup. If you change the configuration file — for example to update credentials, add a new server, or adjust env values — you must restart the AI client for the changes to take effect. A page refresh or session reload is not sufficient; the application itself must be closed and reopened.

I connected the MCP server but the AI says it has no tools

This can happen for several reasons:

• The server is not actually connected — check your client's MCP server panel or settings to confirm the server status. A server that fails to initialise may appear in the list but report an error.
• The AI session started before the server connected — start a new conversation after confirming the server is active.

Imports and async operations

The import job does not complete

Bulk imports run asynchronously. The AI will poll for job status and report the result when the job finishes. Depending on the size of the data, this can take from a few seconds to several minutes.

If the AI session times out before the import completes, the import is still running in Norce — the timeout only affects the AI's polling, not the job itself. To check the status, ask the AI to poll for the job ID, or check directly in the Norce Admin UI or via the API.

For very large imports, you can reduce the risk of session timeouts by importing in smaller batches rather than a single large file.

The import finished but the data looks wrong

• Check the job result for errors — the AI reports whether the import completed successfully or with errors. Ask for the full job result if you want to see per-record error details.
• Check the field mapping — confirm that the fields in your import file match what the tool expects. For the Product MCP, note that product master data (ERP fields) and product content (PIM fields) are imported with separate tools and different field structures.
• Check for partial failures — a job can complete with a success status even if some records were rejected. Ask the AI to check the error count in the job result.

The supplier import ran but products are showing as out of stock

The full supplier infrastructure chain must be in place before imports work correctly. A missing piece — no standard warehouse, no default location, no price list linked to the warehouse — will cause availability calculations to fail silently.

Ask the AI to run norce_supplier_check_supplier_setup for the affected supplier. This validates the full chain and identifies the missing step.

Prices and data propagation

The price looks wrong right after an import

There is a short propagation delay between when a price import completes and when the storefront preview reflects the new values. If you query a price immediately after an import, you may see the old price.

Wait a moment and query again. If the price is still wrong after a reasonable delay, the issue is likely in the import data itself rather than propagation.

The storefront price differs from the raw stored price

This is expected — the raw price and the storefront price are two different things. The raw price (norce_pricing_get_sku_prices) is what is stored in the database. The storefront price (norce_pricing_preview_prices) is what the system calculates for a specific application, applying business logic, VAT, rounding rules, and price list rules on top.

If the two differ, the difference is in one of those layers. Ask the AI to check which price list rule is being applied, whether the correct VAT code is configured, and whether any rounding rule could explain the difference.

Prices differ across storefronts but should be the same

When comparing prices on different storefronts (different application IDs), pass the same currencyId to both preview_prices calls so the Pricing MCP converts both prices to the same currency using Norce's stored exchange rate. Without this, you are comparing prices in different currencies and the difference is expected.

Be aware that rounding rules applied in different currencies may cause a small residual difference even when the underlying price is intentionally the same.

Products and data quality

A product is not showing up on the storefront

The most common causes, in roughly this order:

1. Not published — the product does not have the Published flag set, or is set to inactive.
2. No primary category — every product must have a primary category assigned to appear correctly in the catalogue.
3. Missing required parametrics — the storefront or a publication rule may require certain parametrics to be populated.
4. Application-specific rules — if the product appears on one storefront but not another, check whether the application has specific publication or assortment rules that the product does not satisfy.

Ask the AI to run a readiness check on the product: norce_product_check_product_issues. This surfaces the most common problems in one call.

The product exists but parametric values are not showing in the filter panel

Parametrics must be set to filterable to appear in the filter panel. If a parametric has a value but is not marked as filterable, it will not appear — even if the value is correct.

Ask the AI to confirm that the parametric is configured as filterable in the category assignment. This is a common oversight when adding new parametrics to an existing category.

Translations are missing

Use norce_product_list_missing_translations to get a structured report of products with missing translations for each locale. This is the fastest way to assess the scope of the problem before prioritising which translations to fill in first.

Note that parametrics and categories also have their own translations — missing a product translation is a different issue from missing a parametric or category label translation.

Multi-environment and multi-server issues

Behaviour differs between stage and production

Propagation delays, import processing times, and polling intervals can differ between environments. If stage consistently processes imports faster than production (or vice versa), update your LLM instructions to reflect this — for example, instructing the AI to wait longer before checking import status on production.

Configuration drift between environments is another common source of unexpected differences. Ask the AI to fetch a client overview from the Config MCP for each environment and compare the results — it will flag where the two have diverged in applications, VAT codes, price list assignments, or sales area configuration.

I am connected to both stage and production and the AI used the wrong one

Use a clear naming convention in your MCP configuration that distinguishes the two environments:

norce-product-acme-stage
norce-product-acme-prod

Add an explicit instruction to your system prompt that defines which environment to use for which purpose, and that the AI must never write to production without explicit user confirmation. See Multi-environment setup for a sample instruction.

Application IDs from the Config MCP do not work with the Product or Pricing MCP

Application IDs are shared across all five Backend MCP Servers. If an application ID retrieved from the Config MCP returns no results or an error on another server, check:

• That the servers are connected to the same environment (stage vs production). An application ID from one environment does not work in another.
• That the same AccountId is used in the headers for both servers. A mismatch in AccountId will cause one server to see a different set of applications than another.

Frequently asked questions

Can I connect all five Backend MCP Servers at the same time?

Yes. Each server is connected as a separate entry in your MCP configuration. You can connect all five simultaneously and the AI will coordinate them automatically based on the task.

Can I connect the same server for multiple environments?

Yes — add one entry per server per environment, using distinct keys. See Multi-environment setup for the recommended naming pattern.

Why does the AI ask me for an application ID?

Application IDs are required by most tools to return the correct data for a specific storefront. In this version, there is no tool that automatically discovers all application IDs — you need to provide the initial application ID in your LLM instructions. Once it is in your instructions, the AI uses it automatically without asking.

Use norce_config_list_applications to look up application IDs for your environment, then add the relevant ones to your system prompt.

What happens if I run a write operation by accident?

Write operations are protected by a server-side guard — lower-risk changes go through with a visible warning, and higher-risk changes on stage and production (and a few destructive ones on every environment) are refused until the operation is explicitly confirmed. See the Security and access guide for the full detail on how write protection works and what it does not protect against.

The AI returned a result I do not understand — what should I do?

Connect the Norce Assistant MCP Server alongside the Backend MCP Servers. The Assistant MCP knows the full Norce API reference and data model. If you encounter an unfamiliar field or an unexpected result, ask the Assistant MCP to explain it before concluding something is wrong.