SPECIFICATION & RUNTIME • MCP PROTOCOL 2025-06-18

The Dual-API Architecture:
Public REST + Agentic MCP

Why single-API backends fail: Human shoppers require deterministic REST endpoints with sub-millisecond cart validation. AI agents require semantic Model Context Protocol servers with introspectable schemas, granular safety gates, and stateful workflow prompts. CSM Engine runs both seamlessly on a single relational foundation.

SYSTEM TOPOLOGY

End-to-End Execution Topology

Dual-ingress architecture: Shoppers interact via headless REST while AI agents orchestrate state through the Model Context Protocol layer with approval gates.

AGENT PERMISSION BOUNDARIES

Autonomous Safety: 3 Token Permission Modes

Giving autonomous agents raw database access is catastrophic for commerce. CSM implements a strict three-tier token permission model backed by cryptographically bound approval tokens.

MODE 1: read_only

Zero-Mutation Inspection

Allows the AI agent to query store resources, inspect recent orders, analyze stock levels, and review customer feedback without any permission to modify data.

✓ Can read csm://store/overview
✓ Can call inventory_stats
✗ Mutations return 403 Forbidden

Ideal for analytical & reporting agents.

DEFAULT SAFEST

MODE 2: approval_required

Dry-Run Preview + Token Binding

When an agent invokes a write tool (e.g. creating a product, issuing a coupon, approving a return), CSM executes a dry-run and responds with a preview payload and a single-use approval token.

{"needs_approval": true, "approval_token": "b2a4d...", "expires_at": "+600s", "preview": {...}}

The mutation only applies when the agent re-calls the exact tool with the exact parameters and the cryptographic approval token within 600 seconds.

Guards production stores against LLM hallucinations.

MODE 3: full

Unattended Execution

Permits trusted internal agents and scheduled cron pipelines (e.g., n8n nightly sync, stock ledger reconciliations) to execute mutations directly with immediate transaction commit.

✓ Direct write execution
✓ Rate limited to 60 calls/min
✓ Logged to csm_audit_log

Requires explicit merchant enablement in admin.

KEY DIFFERENTIATOR

The Installable Agent Skill Bundle

Most MCP servers dump dozens of raw functions onto an LLM and pray it doesn't break production. CSM Engine ships an official, dynamically generated Agent Skill Bundle.

Merchants generate a signed 15-minute export URL from their CSM dashboard. When ingested by Cursor, Claude Desktop, Codex, or n8n, it installs:

1. SKILL.md: Operational protocols & strict ground rules.
2. agents/openai.yaml: Tool call manifests & parameter schemas.
3. 17 Reference Documents: Data models, playbooks, API specs, and recovery paths.
4. csm-mcp-smoke.mjs: Automated pre-flight health validation script.

Skill Bundle Manifest Signed 15-min Token

# CSM MCP Operator Instructions
1. Ground yourself before tool calls:
   - Read csm://server/info (version, capabilities)
   - Read csm://store/overview (catalog summary)
2. Use dry_run: true for all mutating operations
3. Follow Rule 8 — additive-first change contract
4. Capture rollback snapshots before bulk edits
5. For frontend code changes, use Git suite:
   frontend_branch_create -> frontend_pr_open -> 
   frontend_pr_checks -> frontend_pr_merge

22 Registered MCP Prompts

class-csm-mcp-prompt-registry.php

Standardized operational workflows rendered on-demand for agent operators:

draft-product-description Catalog Copywriter

summarize-todays-orders Sales Rollup

restock-low-inventory-review Supply Chain

draft-coupon-campaign Promotions

moderate-pending-reviews Social Proof

ship-frontend-change Git Branch & PR

tune-frontend-performance Lighthouse Audit

plan-a-safe-change Rule 8 Contract

+ 14 additional workflow prompts for SEO, inquiries, offers, and unblocking Cloudflare.

36 Relational Tables

class-csm-tables.php

High-concurrency financial & state entities isolated from slow generic CMS tables:

csm_orders

csm_order_items

csm_carts (CSRF)

csm_returns

csm_return_items

csm_return_offers

csm_product_offers

csm_stock_history

csm_coupons

csm_audit_log

csm_wallet_trans

csm_chat_sessions

csm_chat_messages

csm_frontend_deploys

csm_flash_cycles

csm_wa_connections

Relational Integrity: Built with idempotent dbDelta schemas, foreign key indices, and atomic row locking to ensure checkout safety under high concurrency.

INTEGRATION GUIDE

Connecting Your AI Agent in 60 Seconds

Claude Desktop Configuration claude_desktop_config.json

{
  "mcpServers": {
    "csm-engine": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-fetch",
        "https://yourstore.com/wp-json/csm/v1/mcp"
      ],
      "env": {
        "CSM_BEARER_TOKEN": "csm_tok_live_..."
      }
    }
  }
}

Cursor IDE Setup .cursor/mcp.json

{
  "mcpServers": {
    "csm": {
      "url": "https://yourstore.com/wp-json/csm/v1/mcp",
      "headers": {
        "Authorization": "Bearer csm_tok_live_..."
      }
    }
  }
}

Ready to evaluate CSM Engine?

Request our technical architecture briefing, NDA-gated reference implementation, and confidential investor pitch deck.

The Dual-API Architecture: Public REST + Agentic MCP