Troubleshooting and limitations

Use this guide for the Bluestone PIM product MCP server, which signs in a Bluestone user and can operate on organization data. Problems with published OpenAPI discovery belong to the separate Bluestone PIM docs MCP server.

401 Unauthorized before sign-in

An unauthenticated request to the product MCP endpoint is expected to require authorization. A compatible MCP client should follow the OAuth challenge, discover the authorization flow, and open Bluestone sign-in.

Opening the endpoint directly in a normal browser is not a complete MCP connection test. Add it as a remote Streamable HTTP server in the MCP client.

No sign-in window appears

1. Confirm that the client supports remote MCP servers over Streamable HTTP.
2. Confirm that the client supports OAuth for remote MCP servers, including PKCE.
3. Open the client's MCP connection details and choose its authenticate or reconnect action.
4. Check whether the browser opened behind another window, in another profile, or on another device.
5. If stale authorization is stored, use the client's clear-authentication or sign-out action and reconnect.

Do not work around the browser flow by placing a Management API key, client secret, or copied bearer token in the server configuration.

Authentication worked, then the session stopped working

The authorization may have expired or been revoked, or the client may have lost its stored OAuth state. Disconnect the server, clear its stored authentication, and complete sign-in again. If you intended to change user or organization, verify the identity shown in the new browser flow.

Never include access tokens, refresh tokens, authorization codes, or callback URLs in a support ticket or shared log.

The server connects, but an operation is denied

Check:

• The Bluestone user used for sign-in
• The organization resolved for that session
• Whether the user has permission for the underlying read or write operation
• Whether the target record belongs to the active organization and is still available
• Whether the proposed input matches the tool's input contract

Do not repeatedly try broader, bulk, or destructive operations after a denial. Switch to read-only discovery, confirm the target and permission requirement, and ask an administrator to adjust access only when the business task requires it.

The assistant finds the wrong record or context

Stop before any write. Ask the assistant to return candidate records with stable business identifiers and internal IDs, and retrieve context definitions instead of inferring a context from its name.

Stop and use read-only tools only. Show all candidate records with their product numbers, internal IDs, and relevant contexts. Do not select a target or make a change until I confirm one exact ID.

If a prior write may have targeted the wrong record, inspect the record and available history before planning remediation. Do not attempt an automatic reversal without understanding the original operation and its effects.

A job result is unclear

If an operation returns a job identifier, inspect that job rather than resubmitting the original mutation. Record the identifier, original target, and intended change. An unknown, failed, or ambiguous job state does not prove that no data changed; re-read the target before deciding whether another write is safe.

See Asynchronous jobs and History and audit events.

The client does not support this server

The verified connection uses remote Streamable HTTP and interactive OAuth. A client that supports only local stdio servers, only static bearer-token configuration, or no browser authorization cannot use this connection directly unless the client provides a compatible and trusted remote-server integration.

Follow the client's current documentation. Do not add an unreviewed proxy or credential bridge merely to bypass missing OAuth support.

Endpoint or environment is unavailable

This guide set covers the Production EU product MCP endpoint:

https://mcp-core-public.bluestonepim.com/mcp

Do not infer a Production US, Test, or another regional product-MCP URL from this hostname. If you need an environment other than Production EU, obtain its endpoint from Bluestone and confirm both the environment and organization before using it.

Current limitations

• A plan written by an assistant is not a transactional preview, dry run, or rollback guarantee.
• Permission errors and missing data can look similar in some operations; avoid treating either condition as proof that a record does not exist.
• History and job details depend on what the underlying operation records and what the signed-in user may access.
• Closing a chat may not clear the client's stored MCP authorization.

Information to collect for support

Record only non-secret diagnostic information:

• MCP client name and version
• The environment label, such as Production EU
• Time of the failure and the operation you intended
• Whether connection, sign-in, tool discovery, permission checking, or execution failed
• Sanitized error text with tokens, callback parameters, user data, and confidential record values removed
• Relevant non-secret record or job identifiers, if your support policy allows sharing them

For connection setup, return to Connect and authenticate. For operational boundaries, see Permissions and safe operation.