MCP Server Configuration

1. Introduction

The Universal MCP Server is a thin JSON‑RPC wrapper that exposes Conscia’s orchestrated capabilities (built in the DX Engine) as MCP‑compliant tools. This allows any LLM‑based agent (ChatGPT, Perplexity, Gemini, etc.) or your own web chat client to invoke business capabilities such as product discovery or checkout via a single, standard gateway.

Why a wrapper? 95 % of the heavy lifting—data stitching, transformation, rule evaluation, caching—resides in the DX Engine. The MCP Server simply converts the DX Engine’s JSON payloads into the standard MCP response envelope so that agents can consume them.

2. Prerequisites

An active Conscia DX Engine tenant with at least one customer & environment.
API URL and token with permission to read the Flows you will expose.
Relevant Flows (orchestrations) already authored and tested in DX Engine.
(Optional) A deployment target for the MCP Server (Docker, serverless, etc.).

3. MCP Configuration Schema Overview

The configuration is a single JSON document that follows the schema below (excerpt):

{
  "mcpConfigurationCode": "my-mcp-cfg-001",   // unique key
  "version":            "1.0.0",             // semantic version
  "name":               "Universal MCP for ACME",
  "description":        "Discovery & Checkout capabilities for ACME brand", 
  "dxengine": {
      "customerCode":     "acme",            // required
      "environmentCode":  "prod",            // required
      "url":              "https://engine.conscia.ai", // required
      "token":            "${ENGINE_TOKEN}"   // required
  },
  "tools": {
    "mapping": []        // see §4.2
  }
}

Key Objects

Property	Purpose
`dxengine`	Default connection info used by all tools unless overridden.
`tools.mapping[]`	Defines each MCP Tool – its name, human‑readable description, JSON schema for parameters, and optional per‑tool DX Engine overrides such as `templateCode`, `contextTransform`, or `responseTransform`.

4. Step‑by‑Step Configuration

4.1 Define the base `dxengine`

Log in to Conscia Console → Customers → select your customer.
Navigate to Environments and copy the Environment Code (e.g. prod).
Generate a Personal Access Token (PAT) with Query permission.
Populate customerCode, environmentCode, url, and token in the root dxengine object.

4.2 Register Tools via `tools.mapping`

Each entry exposes a single DX Engine Flow as an MCP tool.

{
  "name": "crossBrandDiscovery",
  "description": "Returns a merged, relevance‑ranked list of SKUs across all brands.",
  "schema": {
    "type": "object",
    "properties": {
      "query": { "type": "string", "title": "Search query" },
      "limit": { "type": "integer", "title": "Max # of SKUs", "default": 10 }
    },
    "required": ["query"]
  },
  "dxengine": {
    "templateCode": "discovery.crossBrand",  // Flow Template
    "responseTransform": "transform-discovery-response" // optional
  }
}

Tip: Keep the schema titles & descriptions detailed—LLMs rely on them to call the tool correctly.

4.3 Advanced Overrides per Tool

templateCode – points to the Flow Template in DX Engine.
contextTransform – pre‑process incoming MCP context before calling DX Engine.
responseTransform – post‑process the DX Engine response before it is wrapped.

4.4 Versioning & Metadata

Increment version when you change schemas or point tools to new Flow templates. Use semantic versioning so clients can perform capability negotiation.

5. Example Configuration File (Discovery + Checkout)

{
  "mcpConfigurationCode": "acme-universal-mcp-01",
  "version": "1.0.0",
  "name": "ACME Universal MCP",
  "description": "Discovery & Checkout for ACME via Conscia DX Engine",
  "dxengine": {
    "customerCode": "acme",
    "environmentCode": "prod",
    "url": "https://engine.conscia.ai",
    "token": "${ENGINE_TOKEN}"
  },
  "tools": {
    "mapping": [
      {
        "name": "crossBrandDiscovery",
        "description": "Hybrid search across brand catalogs with ranking & deduping",
        "schema": {
          "type": "object",
          "properties": {
            "query": { "type": "string", "title": "Search query" },
            "limit": { "type": "integer", "title": "Max # of SKUs", "default": 10 }
          },
          "required": ["query"]
        },
        "dxengine": {
          "templateCode": "discovery.crossBrand"
        }
      },
      {
        "name": "checkout",
        "description": "End‑to‑end checkout flow including tax, inventory & payment auth",
        "schema": {
          "type": "object",
          "properties": {
            "cartId": { "type": "string", "title": "Cart identifier" },
            "paymentToken": { "type": "string", "title": "Payment authorization token" }
          },
          "required": ["cartId", "paymentToken"]
        },
        "dxengine": {
          "templateCode": "checkout.flow",
          "responseTransform": "checkout-response-v2"
        }
      }
    ]
  }
}

6. Exposing DX Engine Flows as MCP Tools – Practical Recipes

Cross‑Brand Discovery: Implement Flow discovery.crossBrand, which fans out to multiple search indexes, merges and re‑ranks results. See the Multi‑Brand Conversational Commerce recipe for architecture and success criteria.
Checkout: Implement Flow checkout.flow, orchestrating pricing, tax, inventory, payment, and order creation—mirrors the recipe’s mermaid diagram.

7. Security & RBAC Considerations

DX Engine PATs should be scoped to Query only. Use DX Engine Roles (e.g. engineQuery) to limit what the MCP Server can access. Consider placing the MCP Server behind an API Gateway with rate limiting.

8. Deployment Checklist

9. API Reference (DX Engine & MCP Server)

Below is a concise reference for the endpoints used by the MCP Server when talking to Conscia’s DX Engine. Replace the variables in {{CAPS}} with real values at runtime.

#	Method & Path	Purpose
1	POST `/mcp`	Create (or upsert) an MCP configuration.
2	PATCH `/mcp/{mcpConfigurationCode}`	Update an existing MCP configuration.
3	GET `/mcp/{mcpConfigurationCode}`	Retrieve a single MCP configuration.
4	GET `/mcp`	List all MCP configurations for a customer/environment.
5	DELETE `/mcp/{mcpConfigurationCode}`	Delete an MCP configuration.
6	POST `/experience/customer/{customerCode}/_initialize`	Bulk‑initialise Connections, Components & Templates (one‑shot import).
7	POST `/experience/template/_query`	Execute a Flow Template synchronously.
8	POST `/experience/components/_query`	Execute one or more Components synchronously.

9.1 Common Headers

Content-Type: application/json
Authorization: Bearer {{DX_ENGINE_SYSTEM_TOKEN}}
X-Customer-Code: {{customerCode}}
X-Environment-Code: {{environmentCode}}

Authorization must carry a System‑level PAT (scope: System). PATs scoped to Query will not be able to create or update MCP configurations.

9.2 Create or Upsert an MCP Configuration

POST {{DX_ENGINE_URL}}/mcp

# body snippet
{
  "mcpConfiguration": {
    "mcpConfigurationCode": "bestbuy",
    "version": "1.0.0",
    "name": "My First MCP Configuration",
    ...
    "tools": { "mapping": [ /* see §5 */ ] },
    "resources": {},
    "prompts": {}
  }
}

Returns: 201 Created on first create, 200 OK on update. Response body echoes the stored configuration.

9.3 Update an MCP Configuration (Partial)

PATCH {{DX_ENGINE_URL}}/mcp/bestbuy

# body identical to POST but only fields that change are required.

Tip: Send the full object for idempotency; DX Engine will merge changes.

9.4 Retrieve an MCP Configuration

GET {{DX_ENGINE_URL}}/mcp/bestbuy

Response is the stored JSON object.

9.5 List All MCP Configurations

GET {{DX_ENGINE_URL}}/mcp

Returns an array of configuration summaries. Supports pagination via page and size query params.

9.6 Delete an MCP Configuration

DELETE {{DX_ENGINE_URL}}/mcp/bestbuy

Returns 204 No Content when successful.

9.7 Initialise Engine Assets in Bulk

Use this endpoint when you want to import Connections, Components, ComponentTemplates, etc., in a single atomic call.

POST {{DX_ENGINE_URL}}/experience/customer/{{customerCode}}/_initialize

{
  "engineConfig": {
    "connection": { /* connection definitions */ },
    "component": { /* component definitions */ },
    "componentTemplate": { /* template defs */ }
    ...
  }
}

Note: This is idempotent—re‑posting the same definitions will update changed fields in place.

9.8 Execute a Template Directly (Ad‑hoc)

POST {{DX_QUERY_ENGINE_URL}}/experience/template/_query
{
  "debug": true,
  "templateCode": "get-product-details-by-sku",
  "context": { "sku": "5200906" }
}

Returns: The fully‑materialised response for the specified template.

9.9 Execute a Component Directly (Advanced Debugging)

POST {{DX_QUERY_ENGINE_URL}}/experience/components/_query
{
  "debug": true,
  "componentCodes": ["format-query-get-product-details-by-sku"],
  "context": { "sku": "6611317" }
}

This is useful when validating a transformation script or external service call in isolation.

10. Appendix: Useful DX Engine Links & Resources

DX Engine Docs → Components, Flows, Templates
Recipes → Multi‑Brand Conversational Commerce, Checkout Orchestration
MCP Specification → https://mcp.xyz/spec (external)

Last updated: 2025‑07‑30

1. Introduction​

2. Prerequisites​

3. MCP Configuration Schema Overview​

Key Objects​

4. Step‑by‑Step Configuration​

4.1 Define the base dxengine​

4.2 Register Tools via tools.mapping​

4.3 Advanced Overrides per Tool​

4.4 Versioning & Metadata​

5. Example Configuration File (Discovery + Checkout)​

6. Exposing DX Engine Flows as MCP Tools – Practical Recipes​

7. Security & RBAC Considerations​

8. Deployment Checklist​

9. API Reference (DX Engine & MCP Server)​

9.1 Common Headers​

9.2 Create or Upsert an MCP Configuration​

9.3 Update an MCP Configuration (Partial)​

9.4 Retrieve an MCP Configuration​

9.5 List All MCP Configurations​

9.6 Delete an MCP Configuration​

9.7 Initialise Engine Assets in Bulk​

9.8 Execute a Template Directly (Ad‑hoc)​

9.9 Execute a Component Directly (Advanced Debugging)​

10. Appendix: Useful DX Engine Links & Resources​