Skip to content

AICA Model Context Protocol (MCP) Server

The Liferay AI Commerce Accelerator (AICA) includes a built-in Model Context Protocol (MCP) server exposed inside the microservice.

AI agents (such as Gemini, Claude, Cursor, or Antigravity) can connect to this server over Server-Sent Events (SSE) to inspect, monitor, generate, and clean up commerce datasets programmatically.

Architecture Overview

Because the microservice runs as a long-lived Express HTTP daemon, the MCP server is exposed using the SSE Transport layer. This prevents stdout/stderr pollution and enables remote or containerized agents to interact with the AICA stack over standard HTTP/HTTPS ports.

+-------------------+                      +-----------------------------------+
|                   |   GET /mcp/sse       |                                   |
|   AI Agent        |--------------------->|   AICA Microservice               |
|   (MCP Client)    |<---------------------|   (SSE MCP Server)                |
|                   |   SSE Stream         |                                   |
+-------------------+                      |   Port: 3001                      |
        |                                  |   Base Route: /api/v1/mcp         |
        |   POST /mcp/message              |                                   |
        +--------------------------------->|                                   |
            JSON-RPC Request               +-----------------------------------+

Connection Endpoints

The base URL for MCP endpoints under the microservice is /api/v1/mcp.

  1. Establish SSE Stream (GET /api/v1/mcp/sse): Initiates the persistent SSE connection from the client. The server responds with a connect event containing the endpoint target for future client messages.
  2. Post JSON-RPC Messages (POST /api/v1/mcp/message): Accepts standard JSON-RPC 2.0 frames representing tool list queries and tool executions.

Authentication (Required)

Both endpoints are protected by requireAdmin (middleware/authorizationMiddleware.cjs) — since the MCP tools include destructive operations (aica_teardown_all, aica_delete_session), an authenticated request alone is not enough:

  1. The request must carry a valid Liferay JWT (Authorization: Bearer <token>), verified by the existing userContextMiddleware.
  2. The JWT's caller email must additionally appear in the AICA_ADMIN_EMAILS environment variable — a comma-separated allowlist configured on the microservice.

Without a valid JWT you'll get 401; if AICA_ADMIN_EMAILS isn't configured on the service at all, every request is denied with 503 (fails closed by design); if the caller's email isn't on the allowlist, 403. The client integration examples below will need a valid Bearer token and a configured AICA_ADMIN_EMAILS on the service to work as written; they are shown without auth headers purely for brevity.

Available MCP Tools

Once connected, AICA registers the following tools for the agent:

Tool Name Parameters Description
aica_get_status None Returns connectivity diagnostics, DXP health, database stats, and loaded configurations.
aica_list_sessions None Lists past data generation/import session details.
aica_get_session_logs sessionId (string, required) Extracts the execution logs and stack traces from the active logs for a specific session ID.
aica_trigger_generation productCount (int), accountCount (int), orderCount (int), generatePriceLists (bool), generateSkuVariants (bool) Triggers a background AI commerce generation run.
aica_delete_session sessionId (string, required) Performs targeted teardown of DXP objects and local database entries for a specific session ID.
aica_teardown_all None Wipes all generated AICA commerce data from the DXP instance and resets the database.

Commerce targets on aica_trigger_generation

An agent works from a configuration it was handed rather than from a list it just loaded, so a catalogId or channelId that no longer exists on the instance is a realistic input. The tool resolves both before starting a run:

  • If neither is supplied, the first catalog and channel are used and the tool says which ones in its reply.
  • If one is supplied and the instance does not have it, the tool fails with the id that could not be found, rather than generating a whole dataset into whichever entity happened to sort first. See #680.

The reply always names the catalog and channel the run is using, so a misdirected run is visible without querying Liferay.

Client Integration Examples

1. Claude Desktop Integration

To register AICA inside Claude Desktop, add the following to your claude_desktop_config.json configuration file:

{
  "mcpServers": {
    "aica": {
      "command": "node",
      "args": [
        "-e",
        "const { SSEClientTransport } = require('@modelcontextprotocol/sdk/client/sse.js'); const { Client } = require('@modelcontextprotocol/sdk/client/index.js'); const transport = new SSEClientTransport(new URL('http://localhost:3001/api/v1/mcp/sse')); const client = new Client({ name: 'claude-client', version: '1.0' }); client.connect(transport).then(() => console.log('Connected to AICA MCP Server!'));"
      ]
    }
  }
}

2. Standalone Node.js SSE Client

You can run a standalone client script using the @modelcontextprotocol/sdk package:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';

const transport = new SSEClientTransport(
  new URL('http://localhost:3001/api/v1/mcp/sse')
);

const client = new Client({
  name: 'aica-diagnostic-client',
  version: '1.0.0',
});

await client.connect(transport);

// List available tools
const tools = await client.listTools();
console.log('Available tools:', tools);

// Call a tool
const status = await client.callTool({
  name: 'aica_get_status',
  arguments: {},
});
console.log('AICA status:', status.content[0].text);

Last Reviewed: 2026-09-08