MCP server

This section describes how to install and configure the MCP server in the application server used by ConSol CM. The MCP server allows AI agents to access the ConSol CM REST API on behalf of an authenticated user. The user's permissions determine which data the agent can access and which actions it can perform.

The MCP server is also a prerequisite for using the AI agent in CM/Track.

Prerequisites

• An AI agent with MCP support and access to a Large Language Model (LLM). The customer provides the agent and the LLM.
• The MCP server must be able to reach the configured REST API and OAuth issuer URLs.
• The AI agent must be able to reach the MCP server and complete authentication with ConSol CM.

Configuring the MCP server

If the MCP server cannot communicate with the ConSol CM server directly via localhost, you need to configure the following environment variables:

Environment variable	Purpose	Default value
MCP_OAUTH_ENGINEER_ISSUER_URI	OAuth issuer URL for engineer users	http://localhost:8080/cmas-auth-user
MCP_OAUTH_CONTACT_ISSUER_URI	OAuth issuer URL for contact users	http://localhost:8080/cmas-auth-portal-user
MCP_RESTAPI_BASE_URL	Base URL of the ConSol CM REST API	http://localhost:8080/restapi

Replace the default URLs with the URLs of your environment. The engineer and contact endpoints use separate OAuth issuers.

For JBoss / WildFly, add the variables to the application server's startup configuration. For example:

Windows: Add the following lines to standalone.conf.bat in the application server's bin directory:

set "MCP_OAUTH_ENGINEER_ISSUER_URI=https://cm.example.com/cmas-auth-user"
set "MCP_OAUTH_CONTACT_ISSUER_URI=https://cm.example.com/cmas-auth-portal-user"
set "MCP_RESTAPI_BASE_URL=https://cm.example.com/restapi"

Linux: Add the following lines to standalone.conf in the application server's bin directory:

export MCP_OAUTH_ENGINEER_ISSUER_URI=https://cm.example.com/cmas-auth-user
export MCP_OAUTH_CONTACT_ISSUER_URI=https://cm.example.com/cmas-auth-portal-user
export MCP_RESTAPI_BASE_URL=https://cm.example.com/restapi

Deploying the MCP server

1. Deploy the cm-mcp-server-{version}.war file in the application server used by ConSol CM.
2. Start or restart the application server so it reads the environment variables.
3. Check the application server log to confirm that the MCP server has started successfully.

Standalone deployment

Alternatively, you can run the MCP server in standalone mode by executing the cm-mcp-server-{version}.jar file.

The application context path is /mcp-server. The host and port depend on your application server configuration.

User type	MCP endpoint path	Example URL
Engineer	/mcp-server/mcp	https://cm.example.com/mcp-server/mcp
Contact	/mcp-server/mcp-contact	https://cm.example.com/mcp-server/mcp-contact

If a reverse proxy is used, make the required MCP endpoint available through the proxy and use its externally accessible URL in the AI agent configuration.

Configuring authentication in ConSol CM

1. Open the Authentication page in the Web Admin Suite.
2. In the OIDC for AI agents section, set OIDC enabled to True.
3. Review the client ID, client secret and redirect URI. The client ID and secret must match the values configured in the AI agent. The redirect URI must match the agent's OAuth callback URI.
4. Save the settings.

The settings are saved as system properties in the module cmas-core-security:

System property	Required setting
oidc.ai_agent.enabled.default	true
oidc.ai_agent.clientId.default	Client ID used by the AI agent
oidc.ai_agent.clientSecret.default	Client secret used by the AI agent
oidc.ai_agent.redirectUri.default	OAuth callback URI used by the AI agent

For details about the individual properties, see System properties.

Different configurations

If you want to access the MCP server with several agents which require different callback URIs, you can create additional authentication profiles on the System properties page.

Copy the properties holding the client ID, client secret and redirect URI and replace default in the property name with the name of your profile. The values from the default properties are used for all settings which are not overwritten explicitly.

Connecting an AI agent and verifying the installation

The exact client configuration steps depend on the AI agent. Provide the following information to the person configuring it:

• The full MCP endpoint URL for the required user type.
• The client ID and client secret configured in ConSol CM.
• The configured OAuth callback URI.

To verify the installation:

1. Configure the MCP connection in the AI agent.
2. Start authentication from the agent and log in on the ConSol CM login page with an account of the selected user type.
3. Confirm that the agent can retrieve the available tools and use a read operation, such as retrieving cases the account is allowed to access.

Example for opencode

opencode requires the callback URI http://127.0.0.1:19876/mcp/oauth/callback. Use this URL in the system property oidc.ai_agent.redirectUri.default. Provide the URL of the MCP server endpoint, the client ID and the client secret in the supplied opencode.json file. Authenticate the connection and start the agent:

opencode mcp auth ConSolCM_Tools
opencode