> 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 **Model Context Protocol (MCP)** connector lets an AI assistant work inside your PeakCommerce tenant — reading your journeys, pages and components, and authoring changes to them — through the same scoped, audited API surface your own integrations use. MCP is an open standard for connecting AI assistants to external systems. Instead of pasting configuration into a chat window and copying results back by hand, the assistant calls the platform directly, sees real data, and makes changes you can review and revert. ## Availability **The connector is in internal preview. It is not yet available for customer use.** Today it runs only as a local (stdio) server started from a PeakCommerce source checkout, which means the PeakCommerce team can use it but you cannot connect your own assistant to it. There is no hosted endpoint to point a client at yet. What is being built to change that: | Capability | Status | | ---------------------------------------------------- | ----------- | | Tool contract — the 25 authoring tools below | **Built** | | Scoped API keys enforcing what an assistant may do | **Built** | | Hosted remote endpoint (Streamable HTTP) | In progress | | OAuth sign-in, so you connect without handling a key | In progress | | Consent screen listing what you are granting | Planned | This page documents the tool surface and the permission model now, because those are settled and they are what determines whether the connector is safe to point at your tenant. Setup instructions will be added here when the hosted endpoint ships. If you want to be told when that happens, mention it to your PeakCommerce contact. ## What the assistant can do The connector exposes **25 tools** across three areas. Every one maps to a documented [Agent API](/developers/api-reference/api-reference.md) endpoint — the connector adds no capability the API does not already have, and takes none away. ### Journeys (13 tools) 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 commerce actions | | `create_journey` | Create a journey — **always as a draft** | | `update_journey` | Edit name, description, purpose or audience | | `publish_journey` | Put a journey live, running the platform's publish gates | | `list_journey_versions` | Version history | | `add_journey_step` / `update_journey_step` / `remove_journey_step` | Manage the steps a journey renders | | `reorder_journey_steps` | Set step order | | `add_step_commerce_action` / `update_step_commerce_action` / `remove_step_commerce_action` | Manage what a step *does* when the customer advances | ### Pages (8 tools) | Tool | What it does | | --------------------------------------------- | ---------------------------------------------------------------- | | `list_pages` / `get_page` | Browse pages; fetch one | | `create_page` | Create a page | | `update_page_draft` | Edit the working draft — **does not change what customers see** | | `publish_page` | Promote the draft to live and record a version | | `list_page_versions` / `restore_page_version` | Version history, and restore an earlier version *into the draft* | | `get_page_commerce_manifest` | The page's product set, persona config and resolved offer | ### Custom components (4 tools) `list_custom_components`, `get_custom_component`, `create_custom_component`, `update_custom_component` — the reusable blocks your pages render. ## Permissions This is the part worth reading closely, because it is what stops an assistant from doing more than you intended. The connector authenticates with a **scoped API key**, and the key — not the assistant's instructions — decides what is permitted. Tool descriptions guide the model; the server enforces the scopes. An assistant that has been talked into trying something outside its scopes gets a `403`, not a result. Scopes are per-resource and per-verb: | Resource | Verbs | | --------------------- | ------------------------------------ | | `journeys`, `pages` | `read`, `write`, `publish`, `delete` | | `productsets` | `read`, `write`, `publish`, `delete` | | `components`, `rules` | `read`, `write`, `delete` | | `catalog` | `read`, `write-native` | | `context` | `read` | ### `publish` is never implied by `write` The single most important property: **an assistant that can author drafts cannot put them live.** `publish` is a separate verb, deliberately. A key with `journeys:write` can build an entire journey and cannot ship it — publishing stays a human action unless you explicitly grant `journeys:publish`. The same separation applies to pages. `update_page_draft` edits the working copy; customers keep seeing the published content until someone with `pages:publish` promotes it. Even `restore_page_version` restores *into the draft* rather than going live — rolling back is two deliberate steps, not one. ### Suggested starting point Grant the least that makes the assistant useful for what you actually want: * **Reviewing and reporting** — the `:read` scopes only. The assistant can explain your configuration and answer questions about it, and can change nothing. * **Drafting changes for review** — add the `:write` scopes. The assistant proposes work as drafts; a person reviews and publishes. * **Full authoring** — add `:publish`. Appropriate for a sandbox tenant; think carefully before granting it in production. `delete` is rarely worth granting. Nothing in normal authoring needs it. ## Auditing Every change an assistant makes goes through the Agent API, so it lands in the same audit log as any other API activity, attributed to the key that made it. Give the assistant its own key rather than reusing one from another integration — then its activity is separable, and you can revoke it without disrupting anything else. ## See also * [Authentication](/developers/api-reference/authentication.md) — how API keys and scopes work * [API Reference](/developers/api-reference/api-reference.md) — the endpoints behind every tool * [Base URL & environments](/developers/api-reference/base-url.md) — sandbox vs production --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.peakcommerce.com/developers/mcp.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.