> For the complete documentation index, see [llms.txt](https://docs.peakcommerce.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.peakcommerce.com/developers/mcp.md).

# MCP Connector

The PeakCommerce MCP connector lets compatible AI assistants review your commerce configuration and draft changes directly in PeakCommerce. Assistants work from your real journeys, pages, product sets, business rules and catalog through the same scoped, audited [Agent API](https://docs.peakcommerce.com/developers/api-reference/api-reference.md) your integrations use.

MCP ([Model Context Protocol](https://modelcontextprotocol.io)) is an open standard that connects AI assistants to external systems. With it, an assistant can work in PeakCommerce without requiring you to copy configuration into a chat or manually transfer its proposed changes back. Access is controlled by the API key you provide, and publishing remains a separate permission.

## How it works

|                    |                                                                                                        |
| ------------------ | ------------------------------------------------------------------------------------------------------ |
| **Endpoint**       | `https://mcp.peakcommerce.app/mcp` (production) · `https://mcp.sandbox.peakcommerce.app/mcp` (sandbox) |
| **Authentication** | A PeakCommerce API key, sent as `Authorization: Bearer <key>`                                          |
| **Access**         | Only the tools allowed by the key's scopes. A read-only key exposes read-only tools.                   |

Every tool uses the documented Agent API. The API enforces the key's scopes on every request, so the connector cannot grant capabilities the key does not have.

## Connect Claude to PeakCommerce

### 1. Create a key for Claude

Give Claude **its own key**, with only the scopes it needs. Narrow, per-resource scopes are set when the key is created through the Admin API, using a key that holds `admin`:

```bash
curl -X POST https://api.peakcommerce.app/api/v1/api-keys \
  -H "Authorization: Bearer $PEAKCOMMERCE_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Claude: draft authoring",
        "scopes": ["journeys:write", "pages:write", "components:write",
                   "productsets:read", "rules:read", "catalog:read", "context:read"]
      }'
```

The response contains the key's secret **once**, under `data.secret`. Store it in Claude's configuration and nowhere else. See [Choosing scopes](#choosing-scopes) for the recommended sets, and [Admin - API Keys](https://docs.peakcommerce.com/developers/admin-api/admin-api-keys.md) for the full endpoint.

Do not give Claude an `admin` key. `admin` includes every scope, including the ones that put changes live.

### 2. Add PeakCommerce to Claude

#### Claude Code

Store the key in an environment variable, then add the connector. The single quotes keep `${PEAKCOMMERCE_API_KEY}` as a reference, so the key is read from your environment each time rather than written into Claude Code's settings:

```bash
export PEAKCOMMERCE_API_KEY="<your PeakCommerce key>"
claude mcp add --transport http peakcommerce https://mcp.peakcommerce.app/mcp \
  --header 'Authorization: Bearer ${PEAKCOMMERCE_API_KEY}'
```

Check it from the same terminal:

```bash
claude mcp list
```

A working connection reads `peakcommerce: https://mcp.peakcommerce.app/mcp (HTTP) - ✔ Connected`. If the key is wrong or has been revoked, it reads `✘ Failed to connect` with `HTTP 401` and `invalid_api_key`. Inside Claude Code, `/mcp` shows the same status and lists the connector's tools.

To use PeakCommerce in one project only, add `--scope project` to store the connector in that project's `.mcp.json`; Claude Code asks you to approve it the first time it starts there.

#### Claude Desktop

Claude Desktop starts its connectors from a configuration file. Use the open-source [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge to reach PeakCommerce; it needs [Node.js](https://nodejs.org) installed.

1. Open Claude Desktop's configuration file, `claude_desktop_config.json`:
   * macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   * Windows: `%APPDATA%\Claude\claude_desktop_config.json`
2. Add PeakCommerce under `mcpServers`, with your key in place of the placeholder:

   ```json
   {
     "mcpServers": {
       "peakcommerce": {
         "command": "npx",
         "args": ["-y", "mcp-remote", "https://mcp.peakcommerce.app/mcp",
                  "--header", "Authorization:${AUTH_HEADER}", "--transport", "http-only"],
         "env": { "AUTH_HEADER": "Bearer <your PeakCommerce key>" }
       }
     }
   }
   ```

   Write `Authorization:${AUTH_HEADER}` exactly as shown, with no space after the colon; `mcp-remote` fills in the value from `env`.
3. Quit Claude Desktop completely and open it again.
4. In a new chat, click the **+** button at the bottom of the chat box, then select **Connectors**. PeakCommerce and its tools appear there.

If PeakCommerce does not appear, open Claude Desktop's developer settings to see each connector's status and logs. An `invalid_api_key` error means the key is wrong or has been revoked.

#### Other MCP clients

Clients that connect to remote servers directly take the endpoint and a header. The file and field names depend on the client:

```json
{
  "mcpServers": {
    "peakcommerce": {
      "type": "http",
      "url": "https://mcp.peakcommerce.app/mcp",
      "headers": { "Authorization": "Bearer <your PeakCommerce key>" }
    }
  }
}
```

### Verify the connection

The handshake and tool list are plain JSON-RPC over HTTPS, so you can check a key from a terminal before opening Claude:

```bash
curl -X POST https://mcp.peakcommerce.app/mcp \
  -H "Authorization: Bearer $PEAKCOMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```

A working key returns the tools it is allowed to use. A missing or revoked key returns `401` with a JSON error. Leaving out the `Accept` header returns `406`: the client must accept both `application/json` and `text/event-stream`.

After connecting, ask Claude to call `get_tenant_context` first. It returns the personas, integrations and host routes that orient the remaining tools.

## What the assistant can do

PeakCommerce provides 53 MCP tools across seven areas. The tools Claude can use depend on the key's scopes: read scopes expose 19 tools, write scopes expose 50, and publish scopes expose all 53. The three publish-only tools are identified below.

### Journeys (13)

Journeys are the multi-step flows customers move through: checkout, cancellation, change-plan.

| Tool                                                                                         | What it does                                                                                                   |
| -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `list_journeys` · `get_journey`                                                              | Browse journeys; fetch one with its ordered steps and each step's commerce actions                             |
| `list_journey_versions`                                                                      | Version history                                                                                                |
| `create_journey`                                                                             | Create a journey. **Always created as a draft**                                                                |
| `update_journey`                                                                             | Edit name, description, purpose or audience. Does not publish                                                  |
| `add_journey_step` · `update_journey_step` · `remove_journey_step` · `reorder_journey_steps` | Manage the steps a journey renders. Changes are draft-side: a live journey keeps serving its published version |
| `add_step_commerce_action` · `update_step_commerce_action` · `remove_step_commerce_action`   | Manage what a step does when the customer continues (create a subscription, apply a discount, and so on)       |
| `publish_journey`                                                                            | Put a journey live, running the platform's publish checks and recording a version. Needs `journeys:publish`    |

### Pages (8)

| Tool                         | What it does                                                          |
| ---------------------------- | --------------------------------------------------------------------- |
| `list_pages` · `get_page`    | Browse pages; fetch one with both its draft and its live content      |
| `get_page_commerce_manifest` | The page's product set, persona settings and resolved offer           |
| `list_page_versions`         | Version history                                                       |
| `create_page`                | Create a page, with its content as a draft                            |
| `update_page_draft`          | Edit the working draft. **Customers keep seeing the live content**    |
| `restore_page_version`       | Restore an earlier version **into the draft**. It does not go live    |
| `publish_page`               | Promote the draft to live and record a version. Needs `pages:publish` |

### Product sets (14)

Product sets group the plans and add-ons a checkout or change-plan journey offers.

| Tool                                                                                                         | What it does                                                               |
| ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| `list_product_sets` · `get_product_set`                                                                      | Browse sets; fetch one with its items, dependencies and bundles            |
| `create_product_set` · `update_product_set`                                                                  | Create a set (always as a draft) or edit its details                       |
| `add_product_set_item` · `update_product_set_item` · `remove_product_set_item` · `reorder_product_set_items` | Manage what a set contains and in what order                               |
| `add_product_set_dependency` · `remove_product_set_dependency`                                               | Say which items require, exclude or co-term with each other                |
| `create_product_set_bundle` · `update_product_set_bundle` · `remove_product_set_bundle`                      | Group items behind one item customers see and buy                          |
| `set_product_set_status`                                                                                     | Make a set active, or take it back out of use. Needs `productsets:publish` |

An **active** set has no draft copy, so changing what it contains changes what customers can buy. For that reason, editing an active set needs `productsets:publish` as well; `productsets:write` alone can only shape sets that are not yet live.

### Business rules (7)

Business rules decide whether a plan change is allowed, when it takes effect and how it is prorated.

| Tool                                                                    | What it does                                         |
| ----------------------------------------------------------------------- | ---------------------------------------------------- |
| `list_business_rules` · `get_business_rule`                             | Browse rules; fetch one with the journeys it governs |
| `list_journey_business_rules`                                           | The rules that govern one journey                    |
| `create_business_rule` · `update_business_rule`                         | Create or edit a rule                                |
| `attach_business_rule_to_journey` · `detach_business_rule_from_journey` | Put a rule in force for a journey, or remove it      |

Rules have **no draft state**: a change to an active rule, and attaching or detaching one, takes effect immediately. Treat `rules:write` as a live-changing permission. See [Choosing scopes](#choosing-scopes).

### Catalog (4)

| Tool                                                | What it does                                                                                                                                         |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_catalog_products` · `get_catalog_product`     | Browse catalog products, each marked with whether it can be edited here                                                                              |
| `create_catalog_product` · `update_catalog_product` | Create or edit products authored in PeakCommerce. Products synced from your billing system are changed there, not here. Needs `catalog:write-native` |

### Components (4)

`list_custom_components` · `get_custom_component` · `create_custom_component` · `update_custom_component`: the reusable blocks your pages render.

### Tenant context (3)

`get_tenant_context` · `get_persona` · `get_integration`: your personas, what each persona's surface may do, and which integrations are configured. Integration **credentials and settings are never returned**.

## Permissions and safety

The key, not the assistant's instructions, decides what is allowed. Tool descriptions guide the model; the API enforces the scopes. If an assistant requests an action outside its key's scopes, the API rejects it with `403 Forbidden`.

### Putting something live is a separate permission

Drafting and publishing are separate permissions. For journeys, pages and product sets, a `:write` scope allows an assistant to prepare changes but not put them live. Publishing remains with a person unless you explicitly grant the matching `:publish` scope.

The same holds for rollback. `restore_page_version` restores into the draft, so undoing a page is two deliberate steps: restore, then publish.

Business rules are the exception, because they have no draft: `rules:write` changes live policy. Grant it only where you would let the assistant change pricing and plan-change behavior directly.

### Choosing scopes

Grant the least that makes the assistant useful for the job:

| Job                                                                                          | Scopes                                                                                                       |
| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Explain and review**: answer questions about your configuration, change nothing            | `journeys:read` `pages:read` `components:read` `productsets:read` `rules:read` `catalog:read` `context:read` |
| **Draft for review**: build journeys, pages and components as drafts that a person publishes | the read scopes, plus `journeys:write` `pages:write` `components:write` `productsets:write`                  |
| **Full authoring in a sandbox**                                                              | the above, plus the `:publish` scopes, `rules:write` and `catalog:write-native`                              |

On a production tenant, reserve `:publish` and `rules:write` for workflows that are intentionally allowed to make live changes. Normal authoring does not require `:delete` scopes.

The full scope vocabulary and how each scope expands is in [Authentication](https://docs.peakcommerce.com/developers/api-reference/authentication.md#narrow-per-resource-scopes).

## Auditing and control

Every change the assistant makes goes through the Agent API and is written to your [audit log](https://gitlab.com/peakcommerce/peak-help-docs/-/tree/main/product/reporting-and-analytics/audit-trail-and-logs/audit-logs-overview.md) as Agent API activity, with the action, the resource and a request id.

Give each assistant its own key so you can control its access independently:

* **Revoke** the key and the assistant loses access immediately, without disturbing any other integration.
* **Change its scopes** in place through the [Admin API](https://docs.peakcommerce.com/developers/admin-api/admin-api-keys.md) to widen or narrow what it may do, without re-pasting a key.

## Related

* [Authentication](https://docs.peakcommerce.com/developers/api-reference/authentication.md): API keys and scopes
* [Admin - API Keys](https://docs.peakcommerce.com/developers/admin-api/admin-api-keys.md): create, edit and revoke keys
* [Base URL & environments](https://docs.peakcommerce.com/developers/api-reference/base-url.md): sandbox and production
* [API Reference](https://docs.peakcommerce.com/developers/api-reference/api-reference.md): the endpoints behind every tool


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.peakcommerce.com/developers/mcp.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
