Setting Up the AI MCP Server

The AI MCP Server (Model Context Protocol) acts as the bridge between the AI Service and the Universal Controller REST API. It exposes UC operations as tools that the AI can invoke during a conversation or analysis.

It is assumed you have already configured multiple Tomcat deployments and have a dedicated Tomcat instance ready for the AI MCP Server (for example, at tomcat/instances/ai-mcp).

Installation Procedure

Deploy the WAR file

Copy the provided ai-mcp-{release}-{build}.war file into the webapps folder of your AI MCP Server Tomcat instance, as ai-mcp.war.

Configure base settings

Create a configuration file for the AI MCP Server. As with the AI Service, you can use a setenv.bat / setenv.sh file or an application.yml in the instance's conf folder.

A sample application.yml is given below. This file gives the minimal configurations needed to start the MCP Service.

Minimal configuration

application.yaml

logging:
  file:
    name: "${LOG_FILE_NAME:${LOG_DIR}/ai-mcp.log}"
  threshold:
    console: "${LOG_THRESHOLD_CONSOLE:OFF}"
  logback:
    rollingpolicy:
      max-file-size: 10MB
      max-history: 7
      total-size-cap: 0B
      clean-history-on-start: true
  level:
    com.stonebranch.ai: ${LOGGING_LEVEL_COM_STONEBRANCH_AI:INFO}
    org.springframework: ${LOGGING_LEVEL_SPRING:INFO}
    org.springframework.ai: ${LOGGING_LEVEL_SPRING_AI:${LOGGING_LEVEL_SPRING:INFO}}

stonebranch:
  ai-mcp:
    # MCP CORS Configuration
    # SECURITY: For production, restrict to specific trusted origins
    cors:
      enabled: ${MCP_CORS_ENABLED:true}
      # Production: specify exact origins like "https://your-app.com"
      allowed-origins: "${MCP_CORS_ALLOWED_ORIGINS:http://localhost:*,http://127.0.0.1:*}"
      # Example production config:
      # allowed-origins: "https://your-app.com,https://trusted-partner.com"

    # Default search time window settings for task instance list tools:
    # list_task_instances_by_name, list_task_instances_by_task_name, list_task_instances_by_task_id
    # Does NOT apply to workflow-scoped tools (list_task_instances_by_workflow_instance_*)
    tools:
      list-task-instances:
        default-time-window: "${MCP_LIST_TASK_INSTANCES_DEFAULT_TIME_WINDOW:48h}" # Applied when AI does not specify timeWindow
        max-time-window: "${MCP_LIST_TASK_INSTANCES_MAX_TIME_WINDOW:7d}"          # Maximum allowed time window
        default-limit: ${MCP_LIST_TASK_INSTANCES_DEFAULT_LIMIT:50}                # Maximum number of results returned

    # UC Remote API Configuration
    # Specifies the Base URL(s) of the Universal Controller web application(s) for API calls.
    #
    # Single URL Configuration:
    #   In a single-node configuration or when using a load balancer, specify a single URL:
    #   scheme://hostname[:port]/contextpath
    #   Example: https://uc-server:8080/uc
    #
    # Multiple URL Configuration:
    #   Use this format to configure multiple UC instances or HA cluster nodes.
    #   Common use cases:
    #     - Multiple environments (DEV, QA, PROD)
    #     - HA cluster nodes with node-specific hostnames
    #
    #   Format:
    #   cluster_node_id_1@scheme://hostname[:port]/contextpath|cluster_node_id_2@scheme://hostname[:port]/contextpath
    #
    #   Example:
    #   ha1:8080-uc@https://ha1:8080/uc|ha2:8080-uc@https://ha2:8080/uc
    #
    # Routing:
    #   Single URL Configuration:
    #     The configured URL is used for all API calls regardless of the
    #     X-AI-UC-Service-Instance-Id header value.
    #
    #   Multi-Node Configuration:
    #     The X-AI-UC-Service-Instance-Id header is required and must match a
    #     configured node ID exactly. If the header is missing or the node ID
    #     is not found in the configuration, an error is returned.
    uc:
      base-urls: "${UC_API_BASE_URLS:http://localhost:8080/uc}"

info

We recommend using these values (except for the options in the table below), unless you have a specific reason to change them. See Configuration for a full list of available options.

Set the following option with your own value, if needed:

Environment Variable / Property	Description	Default
MCP_SERVER_URL spring.ai.mcp.client.streamable-http.connections.ai-mcp.url	URL of the AI MCP Server.	http://localhost:8082/ai-mcp

You may also want to configure CORS for security.

Start the AI MCP Server

Start the Tomcat instance for the AI MCP Server. On Windows, run startup.bat from the instance's bin folder. On Linux, run startup.sh.

Check the logs in the instance's logs folder to verify a successful startup.

info

You can verify the service is running by accessing the actuator info endpoint: http://localhost:8082/ai-mcp/actuator/info. A healthy response will return JSON with the application name and version.

Once the AI and MCP services are running, proceed to Post-Installation.