Use the Bluestone PIM docs MCP server

Bluestone PIM hosts a Model Context Protocol (MCP) server alongside its API documentation. AI coding tools such as Cursor, Windsurf, Claude Code, Claude Desktop, and VS Code can connect to it to explore the Bluestone PIM API directly from the editor: list OpenAPI specs, discover endpoints, read endpoint details, and run live requests with your own credentials.

This is a documentation MCP server. Connecting to it does not grant access to your Bluestone PIM data. The server exposes the published OpenAPI specs and API reference, plus a request runner that executes calls using the OAuth2 bearer token you supply. It is not a separate Bluestone product MCP, and it does not read or write your account data on its own.

Endpoint

The docs MCP server is hosted at the /mcp path of each documentation site and uses the streamable HTTP transport. Connecting requires no authentication.

Environment	MCP endpoint URL	Documentation
Production EU	`https://docs.api.bluestonepim.com/mcp`	Production EU docs
Production US	`https://docs.api-us.bluestonepim.com/mcp`	Production US docs
Test	`https://docs.api.test.bluestonepim.com/mcp`	Test docs

Use the test endpoint while you are wiring up a client or experimenting with execute-request, then switch to production.

What the MCP server exposes

The server provides five tools. Four are read-only discovery tools over the published OpenAPI specs; one executes live API requests.

Tool	Type	What it does
`list-specs`	Read-only	Lists every published OpenAPI spec by title.
`list-endpoints`	Read-only	Lists all paths and HTTP methods for a spec, with summaries.
`search-endpoints`	Read-only	Deep search across paths, operations, and parameters to find endpoints, required parameters, and data models.
`get-endpoint`	Read-only	Returns full detail for one endpoint, including security schemes and servers.
`execute-request`	Live request	Executes an HTTP request you describe as a HAR request object (method, URL, headers, body) against the API. Requires your own bearer token.

The server exposes the same OpenAPI components published on the OpenAPI documentation page, including:

Completeness score, External notifications, Global settings, History, IDP, Labels, Media bank, Metadata, Bluestone Public API, PIM, Public API sync, Query builder, Search, Tasks, and UI settings. A helper spec named get-bearer-token exposes the OAuth2 token endpoint (POST /op/token) so an agent can discover how to authenticate.

The docs MCP server does not search guide prose pages and does not edit documentation. For SDK generation and language examples, see Generate SDKs and client code from OpenAPI. The raw OpenAPI JSON files are also linked from that guide.

Connect your MCP client

Each client reads MCP server definitions from its own config file. Add the entry for your environment.

Cursor

Add to ~/.cursor/mcp.json:

Production EU

{
  "mcpServers": {
    "bluestone-pim-docs": {
      "url": "https://docs.api.bluestonepim.com/mcp"
    }
  }
}

Production US

{
  "mcpServers": {
    "bluestone-pim-docs": {
      "url": "https://docs.api-us.bluestonepim.com/mcp"
    }
  }
}

Test

{
  "mcpServers": {
    "bluestone-pim-docs": {
      "url": "https://docs.api.test.bluestonepim.com/mcp"
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

Production EU

{
  "mcpServers": {
    "bluestone-pim-docs": {
      "url": "https://docs.api.bluestonepim.com/mcp"
    }
  }
}

Production US

{
  "mcpServers": {
    "bluestone-pim-docs": {
      "url": "https://docs.api-us.bluestonepim.com/mcp"
    }
  }
}

Test

{
  "mcpServers": {
    "bluestone-pim-docs": {
      "url": "https://docs.api.test.bluestonepim.com/mcp"
    }
  }
}

Claude Code

Add the server from the project root with the CLI:

Production EU

claude mcp add --transport http bluestone-pim-docs https://docs.api.bluestonepim.com/mcp

Production US

claude mcp add --transport http bluestone-pim-docs https://docs.api-us.bluestonepim.com/mcp

Test

claude mcp add --transport http bluestone-pim-docs https://docs.api.test.bluestonepim.com/mcp

This writes a .mcp.json entry you can commit and share:

Production EU

{
  "mcpServers": {
    "bluestone-pim-docs": {
      "type": "http",
      "url": "https://docs.api.bluestonepim.com/mcp"
    }
  }
}

Production US

{
  "mcpServers": {
    "bluestone-pim-docs": {
      "type": "http",
      "url": "https://docs.api-us.bluestonepim.com/mcp"
    }
  }
}

Test

{
  "mcpServers": {
    "bluestone-pim-docs": {
      "type": "http",
      "url": "https://docs.api.test.bluestonepim.com/mcp"
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

Production EU

{
  "mcpServers": {
    "bluestone-pim-docs": {
      "url": "https://docs.api.bluestonepim.com/mcp"
    }
  }
}

Production US

{
  "mcpServers": {
    "bluestone-pim-docs": {
      "url": "https://docs.api-us.bluestonepim.com/mcp"
    }
  }
}

Test

{
  "mcpServers": {
    "bluestone-pim-docs": {
      "url": "https://docs.api.test.bluestonepim.com/mcp"
    }
  }
}

If your Claude Desktop version only supports local (stdio) servers, bridge to the remote endpoint with mcp-remote:

Production EU

{
  "mcpServers": {
    "bluestone-pim-docs": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://docs.api.bluestonepim.com/mcp"]
    }
  }
}

Production US

{
  "mcpServers": {
    "bluestone-pim-docs": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://docs.api-us.bluestonepim.com/mcp"]
    }
  }
}

Test

{
  "mcpServers": {
    "bluestone-pim-docs": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://docs.api.test.bluestonepim.com/mcp"]
    }
  }
}

VS Code

Add to .vscode/mcp.json:

Production EU

{
  "servers": {
    "bluestone-pim-docs": {
      "type": "http",
      "url": "https://docs.api.bluestonepim.com/mcp"
    }
  }
}

Production US

{
  "servers": {
    "bluestone-pim-docs": {
      "type": "http",
      "url": "https://docs.api-us.bluestonepim.com/mcp"
    }
  }
}

Test

{
  "servers": {
    "bluestone-pim-docs": {
      "type": "http",
      "url": "https://docs.api.test.bluestonepim.com/mcp"
    }
  }
}

Any MCP client that supports the streamable HTTP transport can connect using the same URL.

Authentication

Connecting to the MCP server and using the read-only discovery tools (list-specs, list-endpoints, search-endpoints, get-endpoint) requires no authentication.
Running requests with execute-request requires a valid OAuth2 bearer token that you provide. The server runs the request you describe; it does not hold or inject Bluestone credentials for you.

Generate a token from the IDP token endpoint for your environment, then have the agent include it as an Authorization: Bearer <token> header in the execute-request call.

See Environments for API and auth base URLs.

curl -sS -X POST "https://idp.bluestonepim.com/op/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=YOUR_CLIENT_ID" \
  --data-urlencode "client_secret=YOUR_CLIENT_SECRET"

Treat any token the agent uses as a secret. Use test credentials while developing, and never paste production credentials into a shared chat transcript.

Recommended prompts for agents

Once the server is connected, ask the assistant questions that map to the discovery and execution tools. For example:

"List the available Bluestone PIM OpenAPI specs."
"Find the endpoint for cursor pagination over products."
"Show the request body and required parameters for creating a product in the PIM spec."
"Which endpoint creates a webhook subscription, and what fields does it need?"
"Generate a product bulk update workflow, then poll the task status endpoint until it completes."
"Using my test bearer token, list the first page of products from the test environment."
"Show the security scheme and server URLs for the Media bank upload asset endpoint."

For the underlying request and retry patterns these workflows depend on, see Rate limits, retries, and backoff and Webhook events and delivery.

Limitations

The server exposes the API reference and OpenAPI specs, not guide prose pages. To search guides, use the documentation site search.
execute-request makes real API calls with the token you supply. A request against production data has the same effect as any other authenticated API call. Develop against the test endpoint first.
The docs MCP server is read-and-execute only with respect to documentation: it cannot edit Bluestone PIM docs.
Rate limits apply to any call execute-request makes, the same as direct API access. See Rate limits, retries, and backoff.

Support

Report problems connecting or unexpected MCP behavior through your usual Bluestone PIM support channel, and include the environment (production or test) and the MCP client you are using. For documentation content questions, use the docs site search or the Help Center.

For AI agents

The Bluestone PIM documentation MCP server is the machine-readable channel for discovering the API. It speaks the streamable HTTP MCP transport and requires no authentication to connect. Endpoints: Production EU https://docs.api.bluestonepim.com/mcp, Production US https://docs.api-us.bluestonepim.com/mcp, Test https://docs.api.test.bluestonepim.com/mcp.

Recommended agent workflow:

Connect to the MCP endpoint for your environment.
Call list-specs to see the available API components.
Use search-endpoints or list-endpoints to locate the operations you need.
Call get-endpoint to read parameters, request bodies, security schemes, and server URLs.
Obtain an OAuth2 bearer token from the /op/token endpoint (the get-bearer-token spec documents it).
Use execute-request with your bearer token to call the API, starting in the test environment.

The same specs are published as raw OpenAPI JSON and described in Generate SDKs and client code from OpenAPI, and an LLM index is available at /llms.txt.