Configuring the MCP Server

This page describes the configuration model, parameter properties, and capability constraints for the Model Context Protocol (MCP) Server in HCL Digital Experience (DX) IQ deployments.

The MCP Server establishes the communication layer that enables IQ services to exchange structured requests and responses with supported AI capabilities. It centralizes tool execution and maintain consistent data exchange patterns across the backend environment.

The configuration architecture delivers these capabilities through the following features:

A single MCP entry point for enabled DX capabilities, including authentication, DAM Digital Asset Management (DAM), Web Content Manager (WCM), and Core tools.
Consistent request handling behavior across all registered tools.
Token-Oriented Object Notation (TOON) response encoding for JSON tool payloads, with a standard JSON text fallback.
Support for brief and detailed response modes (summary and full) on many DAM and WCM tools.

Prerequisites

Before validating the configuration, ensure your environment meets the following requirements:

DX CF236 or later is installed.
IQ is enabled in your DX environment.
The IQ chart release is deployed successfully.
Networking rules permit communication between DX, IQ integrator, and MCP Server services.

Verifying service-level expectations

Use these baseline checks in your environment:

Confirm the dx-mcp-server pod is running and healthy.
Confirm the service name and namespace resolution are correct.
Confirm IQ integrator and MCP Server are from compatible release levels.

Note

If IQ was upgraded, verify that the associated MCP Server deployment was upgraded as part of the same release plan.

Configuring server parameters

The MCP Server relies on specific Helm chart configuration values to control tool availability, payload capacity, and session data context.

Use the following feature flags to enable or disable tool domains to expose only the capabilities required by your deployment.

Parameter	Description	Default value
`ENABLE_DAM`	Enables Digital Asset Management (DAM) tools.	`false`
`ENABLE_WCM`	Enables Web Content Manager (WCM) and DX Core content-related tools.	`false`
`STANDALONE_MODE`	Controls authentication tool enablement and determines whether the server integrates with HCL DX user authentication or runs in isolation.	`false`

Warning

At least one of ENABLE_DAM or ENABLE_WCM must be set to true. If both parameters are disabled, the MCP Server does not expose any DAM or WCM tool domains and the readiness probe reports the service as unhealthy.

Use the following parameter to adjust the payload handling limit:

Parameter	Description	Default value
`BODY_PARSER_JSON_LIMIT`	Limits the size of incoming JSON-RPC payloads to ensure service stability. This parameter maps to the body-parser `jsonLimit` setting at runtime. Increase this value in the Helm chart configuration if your deployment requires larger payloads.	`1mb`

Use the following JSON-RPC parameters to propagate request-scoped context to downstream HCL DX API calls.

Parameter	Context type	Description
`params.cookies`	Cookie context	Forwards session cookies to downstream HCL DX requests.
`params.vpContext`	Virtual portal context	Applies virtual portal parameters to downstream request routing to maintain consistent behavior.

Managing endpoints and security

The MCP endpoints are internal to the IQ backend deployment and are accessed only by the IQ integrator service within the cluster. They are not exposed externally and are not routed through HAProxy.

Endpoints and health probes

Route tool execution requests through the following endpoints to handle traffic for enabled DX tool domains:

Endpoint path	Type	Network and runtime behavior
`/mcp`	Tool API (Unprefixed)	Provides MCP Server functionality as the unprefixed entry point for enabled DX tool domains.
`/dx/api/iq/v1/mcp`	Tool API (Versioned)	Provides MCP Server functionality as the versioned entry point for enabled DX tool domains to prevent breaking changes.

Note

MCP tool responses use TOON encoding for JSON payloads when encoder support is available. If encoding is unavailable, the server falls back to standard JSON text responses. TOON output strips out repetitive structural syntax to make payloads more compact, which reduces token usage in LLM-driven workflows.

Monitor service health and backend dependency availability using these operational probes:

Probe path	Type	Description
`/probe/live`	Liveness probe	A standard health check that confirms the server process is actively running inside the container.
`/probe/ready`	Readiness probe	A dependency check that validates the backend tools are responsive. This check runs only for enabled tool domains. It reports healthy if at least one domain works and fails if everything is turned off or broken.

Enabling HTTPS for the MCP Server

HTTPS is disabled by default in the IQ Helm chart (hcl-dx-iq). To secure connections between the MCP Server and the IQ Integrator, enable HTTPS and configure a Kubernetes TLS Secret:

Create a TLS Secret in your Kubernetes namespace containing the standard tls.crt and tls.key keys.

The following example uses dx-tls-cert as the Secret name. You can use another name as long as it matches the tlsCertSecret value in your Helm chart:
```
kubectl create secret tls dx-tls-cert \
    --cert=<PATH_TO_CERTIFICATE> \
    --key=<PATH_TO_PRIVATE_KEY> \
    --namespace <YOUR_NAMESPACE>
```
Set httpsEnabled to true and set tlsCertSecret to the name of the TLS Secret.

The chart requires a non-empty tlsCertSecret when HTTPS is enabled and mounts the Secret at /etc/mcp-tls-config. The MCP Server reads the certificate from /etc/mcp-tls-config/tls.crt and the private key from /etc/mcp-tls-config/tls.key.
```
configuration:
  mcpServer:
    httpsEnabled: true
    tlsCertSecret: "dx-tls-cert"

environment:
  pod:
    integrator:
      - name: "MCP_SERVER_LIST"
        value: "https://<IQ_RELEASE_NAME>-mcp-server:3000"
```
When HTTPS is enabled, the MCP Server health probes use HTTPS automatically.

Note

The MCP_SERVER_LIST value must use https:// for the IQ Integrator to connect to the MCP Server.

Validating post-deployment status

After deployment, upgrade, or configuration updates, validate the following baseline items:

IQ interface loads successfully in DX.
IQ requests complete cleanly for simple prompts.
MCP endpoints are fully reachable from expected network paths and exhibit correct HTTP upgrade or protocol behavior.
Requests process reliably without repeated timeout or payload-limit failures.
No persistent MCP connectivity errors, timeout logs, or unauthorized access patterns appear in the system logs.

Next steps

After configuring the MCP Server:

(Optional) Set up a PostgreSQL database for persistence.
Configure IQ Integrator authentication for LiteLLM access.

Related information