Decision 002: central MCP and a store REST module

Accepted · 1 October 2026. The founder selected the second option after discussing identity and cart access. This supersedes the earlier same-day decision to expose MCP directly from OpenCart. It is a target architecture, not a claim that the integration works today.

Decision

App / storefront chat → Agentfy harness → Store Deputy MCP / policy
                                               ↓ HTTPS REST/JSON
                                         OpenCart module
                                               ↓
                                Actual catalog and shopper cart

Agentfy owns agent execution, skills, conversations and tool calling. Store Deputy owns the account and connection experience and the controlled commerce gateway: one MCP interface, team/store access, actor context, entitlements, approvals and audit. The OpenCart module exposes a versioned REST API, validates calls and carries out supported platform operations. It does not expose a full MCP server.

The app includes teams (one by default), agents, account, billing and a chat with each agent. Connect in the module leads to hosted login/registration, secure pairing, automatic agent provisioning in Agentfy with the Store Deputy MCP URL, and a return to the connected module. The default team and basic pairing already exist locally; integration and new tools do not.

Three authority boundaries

Boundary	Trusted proof	Permitted scope
Store connection	Separate revocable server credentials for the installed module	The shop and capabilities the owner connected
Employee operation	Verified Store Deputy user/team membership, role and delegated runtime context	That employee's allowed operations; exact approval for protected writes
Shopper conversation	Storefront session verified by the module, then bound to a conversation	That visitor's cart and explicitly permitted customer data

Agentfy authenticates to the central MCP; Store Deputy authenticates separately to the module. Do not forward the MCP bearer token to OpenCart. Agentfy's service credential alone is not proof that a particular shopper owns a cart. Runtime attaches verifiable, scoped context outside the prompt: actor kind, team/store, conversation/run, scopes, expiry and opaque shopper binding where applicable. The model cannot select its own identity or permissions.

Recheck authorization on every tool call. Module-side ownership checks and local Pause remain effective even if central orchestration misbehaves. Never keep current_customer on a shared agent object; each visitor has a separate conversation and context.

Shopper and cart flow

1. The storefront widget calls the module on the shop's own origin. The module derives guest/customer identity from the real OpenCart session, not a browser-supplied customer_id.
2. Through an authenticated server exchange the module creates a scoped conversation binding in Store Deputy. The browser receives short-lived chat access. Raw OpenCart session cookies stay in the shop; an opaque reference remains checked against its authorized caller.
3. Agentfy receives the conversation and delegated context through the chat service. cart.get or cart.addItem(productId, quantity) is resolved against that binding, not a model-selected customer.
4. Store Deputy verifies scope and binding; the module verifies ownership again and operates on the existing storefront cart using platform logic.
5. OpenCart computes prices, availability, promotions, tax and totals. The confirmed cart revision/result refreshes the visible cart; Store Deputy and Agentfy do not become a second cart authority.

Login, logout, session expiry and guest-cart merging require binding refresh or revocation. Concurrent tabs require conflict detection. Mutations use a stable operation key per intent; a retry must not add the item twice. Reusing the key with a different payload fails. An uncertain timeout is reconciled before replay. Checkout, payments, order placement and order history are outside this first cart scope.

In OpenCart 3.0.3.5 cart selection uses api_id, customer_id and session_id; standard API login creates a separate API session. Using that login alone therefore does not recover the visitor's storefront cart. The adapter must prove this behavior on both supported test versions.

Contract and delivery

First agree the REST schemas, MCP transport/authentication, delegation contract with Agentfy, capability negotiation, errors, revocation and operation/revision semantics. These details remain engineering work; accepting this architecture does not choose an unverified protocol implementation. The proposed contract, still to be agreed, is REST 1.0.

Stage A: authenticated module API, connection lifecycle, central MCP, delegated employee identity, automatic agent provisioning and real catalog reads. Verify tenant isolation and revocation before adding writes under the existing price epic.

Stage B: verified shopper bootstrap, isolated frontend conversations, cart reads, then explicitly authorized cart mutations and storefront refresh. This stage requires the Frontend Agent and subscription decisions; it must not block the initial Admin Agent. Add no autonomous checkout.

PHP/module work is assigned to Artem Belikov. API, Agentfy integration, shared contracts and end-to-end work are assigned to yevhen.kariakin. Split cross-boundary work into separate tasks. Existing product epics retain their outcomes; this epic supplies the integration foundation.

Consequences and alternatives

A central gateway gives agents one maintained interface and keeps authorization, audit and commercial controls together. Platform/version differences stay in adapters, and unsupported capabilities fail explicitly. It adds a service hop and makes Store Deputy availability/security part of every operation. Both central and module checks are necessary.

Direct module MCP is a valid alternative and does not inherently lose control: the MCP client authenticates, not the language model itself. We reject it for this product because central governance and a stable multi-platform interface are more useful than independently exposing every shop's MCP. No second harness is built in Store Deputy. Earlier Bridge RPC drafts impose no compatibility requirements on REST 1.0; existing experimental code does not implement this contract.

Sources

• Founder discussion and working project decisions.
• MCP authorization: separate protected resources and token audience.
• MCP security: state handles are not authentication.
• OpenCart 3.0.3.5: cart implementation, API login.

Module ↔ API protocol: REST 1.0